GitHub Actionsを学ぶ#1
はじめに
勉強しておいて損はなさそうなので今さらながらGitHub Actionsを学ぼうと思います。
自分の備忘録をメインとしますが、私と同じようにまだ学習していない方が見たときに学習しやすい内容にしたいと思います。（思います）
今回は以下の書籍を参考にさせていただきました。
・参考書籍
GitHub CI/CD実践ガイド―持続可能なソフトウェア開発を支えるGitHub Actionsの設計と運用
GitHub Actionsを学ぶ書籍としてとても参考になりました。
セットアップ
今回はDockerでコンテナを作ってそこで作業します。
コマンド等は環境に応じて置き換えてください。
またGitHubのアカウントが必要になりますのでない場合は事前に取得してください。
コンテナ作成
DockerイメージはAWS公式ドキュメントに記載されているものを使います。
$ docker pull amazonlinux:2023
$ docker run -it amazonlinux:2023 /bin/bash
GitHub CLIのインストール
コマンドで操作していくためインストールしておきます。
GitHub CLI は、すべての作業を 1 か所で行うことができるように、pull request、issues、GitHub Actions、およびその他の GitHub 機能をターミナルに集めたコマンドライン ツールです。
# dnf install git
# git --version
git version 2.40.1
# dnf install 'dnf-command(config-manager)'
# dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
# dnf install gh --repo gh-cli
# gh --version
gh version 2.55.0 (2024-08-20)
https://github.com/cli/cli/releases/tag/v2.55.0
[補足]
・Dockerイメージにgitがインストールされていなかったのでインストールしています
・GitHub CLIのインストール方法は以下を参考にしました。
ログイン(認証)
コマンド実行後に対話式で入力していきます。
# gh auth login
学習用にコンテナで作業しているため、選択は参考程度にしてください。
? What account do you want to log into?
「GitHub.com」を選びました。
? What is your preferred protocol for Git operations on this host?
「HTTPS」を選びました。
? Authenticate Git with your GitHub credentials?
「Yes」を選びました。
? How would you like to authenticate GitHub CLI?
「Login with a web browser」を選びました。
! First copy your one-time code: {コード}
Press Enter to open github.com in your browser...
上記のcodeをコピーしておきましょう。
「Enter」を押すとブラウザが開くようですが、私の場合は下記が出力されました。
! Failed opening a web browser at https://github.com/login/device
exec: "xdg-open,x-www-browser,www-browser,wslview": executable file not found in $PATH
Please try entering the URL in your browser manually
自分でブラウザを起動して https://github.com/login/device にアクセスすれば問題ないようです。
アクセスした後に先ほどコピーしたcodeを入力して、画面に表示される通りに沿って進めればOKです。
認証が完了すると、コンソールに以下が出力されます。
✓ Authentication complete.
- gh config set -h github.com git_protocol https
✓ Configured git protocol
! Authentication credentials saved in plain text
✓ Logged in as {ユーザ名}
リポジトリ作成
この後で使うリポジトリを作成します。
GitHub CLIをインストールしたのでghコマンドから作成してみます。
# gh repo create {リポジトリ名} --public --clone --add-readme
# gh repo list
NAME DESCRIPTION INFO UPDATED
{ユーザ名}/{リポジトリ名} public less than a minute ago
ブラウザで確認するとリポジトリが追加されています。
また上記コマンドはパブリックリポジトリとして作成していますのでご注意ください。
GitHub Actionsに触れる
GitHub ActionsにはワークフローファイルというYAMLファイルが必要になります。
このファイルにやりたいことを書いてリポジトリに配置することでGitHub Actionsが使えるようになります。
ワークフローファイルは以下の制約があるようです。
- 拡張子は「.yaml」か「.yml」
- 「.github/workflows」配下に配置する必要がある
ディレクトリでファイルを分けることができないので、ファイル名は用途が分かるようにつけたほうが良さそうです。
ワークフローファイルの作成
参考書籍を元にワークフロー構文について簡単に記載します。
ワークフロー構文
- name
ワークフローの名前を指定する。省略可能だが基本は設定しておく。 - run-name
ワークフローの実行名を指定する。空の場合はイベント固有の情報に設定されるようです。
動的に値を変えることができるため、誰が実行したみたいな情報も設定できるようです。
run-name: Deploy to ${{ inputs.deploy_target }} by @${{ github.actor }}
- on
何かしらイベントを起点にワークフローを自動的に実行させたい場合に指定する。
それ以外にも時間や特定のファイル、タグ、またはブランチの変更なども対応しているようです。
# 単一の場合
on: push
# 複数の場合
on: [push, fork]
- jobs
ワークフローの実行単位で、runs-onに指定されたランナー環境で実行されます。
ジョブは複数指定でき、ジョブIDで区別させます。
基本的に並列実行のようですが、依存関係を持たせてジョブを順番に実行させる方法もあるようです。 - runs-on
ジョブの実行環境を指定します。
・GitHub-Hosted Runners：GitHubが提供するマネージドな環境
・Self-Hosted Runners：自前で用意及び管理する環境
要件に応じて使い分けるやつですね。今回の学習では手間を省きたいのでホスト型を使います。 - steps
ジョブ内で何を実行するかをここで指定する。
複数設定が可能であり、ステップごとに名前をつけたり変数なども設定できるので自由度が高そう。
シェルコマンドを実行する際に複数行指定することも可能。
- name: Clean install dependencies and build
run: |
npm ci
npm run build
- uses
アクションを呼びすことができ、ワークフローを再利用できます。
お約束の「Hello World」をやるために先ほど出てきたディレクトリとワークフローファイルを作成します。
以下は参考書籍の内容を一部変えています。
# cd {リポジトリ}
# mkdir -p .github/workflows
# cat << 'EOF' > .github/workflows/helloworld.yml
name: HelloWorld # ワークフロー名
run-name: by @${{ github.actor }} # ワークフロー実行名
on: push # イベント
jobs: # ジョブの定義
hello: # ジョブID
runs-on: ubuntu-latest # 実行環境
steps: # ステップの定義
- run: echo "Hello World" # シェルコマンドの実行
EOF
上記は「push」をトリガーにステップに記載されている内容をubuntuで実行するといった内容になっています。
動作確認
今回追加したワークフローファイルはpush時に実行されるため、先ほど作成したファイルをpushしたら実行されるようです。
(作成したワークフローファイルを追加したときも実行されるのは少し疑問が残りますけど)
コンテナ環境を作ったので、gitの設定を行う（設定していない人だけ）
# git config --global user.email "{you@example.com}"
# git config --global user.name "{Your Name}"
作成したファイルをリポジトリに追加します。今回は作業用にブランチは作っていません。
# git add .github/workflows/helloworld.yml
# git commit -m "add workflow file"
# git push
これで実行されたようです。
ブラウザからリポジトリを確認すると実行されていることが確認できました。
run-nameで指定したところがリンクになっているので、そこをクリックすると各ステップの情報を見ることができ、詳細なログを確認することができます。
今度はGitHub CLIから確認を行います。
対話形式でどのワークフローを見るか選択してEnterを押すと確認できます。
# gh run view
? Select a workflow run [Use arrows to move, type to filter]
> ✓ {run-name}, {name} (main) 30m22s ago
~選択後の出力は省略~
実行中のワークフローを確認する場合は以下を使うようです。
# gh run watch
ワークフローの手動実行
onにworkflow_dispatch を指定すると手動で実行できるようになります。
以下は参考書籍の内容を一部変えています。
# cat << 'EOF' > .github/workflows/manual.yml
name: Manual
on:
workflow_dispatch: # 手動実行イベント
inputs:
breed: # パラメータ名
type: string # 型
default: "Border Collie" # デフォルト値
required: true # 必須フラグ
description: input breed # 説明
jobs:
run:
runs-on: ubuntu-latest
steps:
- run: echo "My favorite dog is ${{ inputs.breed }}"
EOF
変数を使うときは ${{ inputs.変数名 }} で参照が可能になります。
さてリポジトリに追加したらブラウザから以下の手順で実行できます。
[追加したワークフロー] > [Run workflow] > [パラメータ入力] > [Run workflow]
# gh workflow run manual.yml -f breed="Siberian Husky"
✓ Created workflow_dispatch event for manual.yml at main
To see runs for this workflow, try: gh run list --workflow=manual.yml
ワークフローファイルはファイル名を指定するだけでよいのは楽です。
パラメータを指定する場合はオプション「f」を指定しましょう。
ワークフローの定期実行
onにscheduleを指定すると定期実行できるようになります。
スケジュールの部分だけ記載します。
on:
schedule: # スケジュールの設定
- cron: '* */1 * * *' # 1時間ごとに実行する
cron形式で記述するため難しくないですが、実行時間のタイムゾーンがUTCのようです。
JSTの何時に実行するといったことが多いと思うので注意が必要です。
また負荷状況に応じて遅延することもあるため時間制約が厳しいものは気をつけましょう。
おわりに
今回はGithub Actionsを触る程度の学習を行いました。
どうゆう時に（イベント）何をしたいか（ジョブのステップ）を明確にすれば、結構簡単そうでした。
次は運用面や継続的インテグレーション（言ったことない）について勉強できればと思います。
Discussion