実践例

ワークフローの配置場所

GitHub Actionsは “.github/workflows”の配下にyamlファイルを配置するだけで、Githubが自動的にワークフローを認識してくれるのでとても簡単で手軽にCI/CDを実行することができます。

ワークフローの構成

前回パート1で紹介したGitHub Actionsで頻出する用語を踏まえて、ワークフローの構成について確認していきます。

上記のワークフローについて、分解して解説していきたいと思います。

①name
　これはワークフローの名前です。今回は、プッシュしたときにフォーマットするワークフローを作成していくので、”format code”という名前にしました。

②on
　ここではトリガーにするイベントを指定します。今回はpushされたときにこのワークフローを動かしたいので”push”としています。イベントの例は下記の表をご覧ください。他にもたくさんイベントがあるので詳細は、公式のGitHub Docをご参照ください。

branchesでは、どのブランチでイベントが起こった時にワークフローを実行するかを指定できます。今回はmain branch以外で実行したいため、”**” と “!main”を指定しています。

③name
　これはジョブの名前です。この名前はワークフロー内で一意であり、他のジョブやステップから参照される識別子として使用されます。今回は、フォーマットからプッシュまでを行うジョブを作成したいので”format_through_push”という名前を設定しました。

④name
　では、このnameはなんの名前なのでしょうか。
これはActionのジョブに表示される名前であり、どのワークフローやジョブ、
ステップを実施しているか理解しやすくするために設定する値です。
ワークフローの実行には影響せず、必須でもありませんが、分かりやすいワークフローを
作成するために用いられます。ここで設定するnameはGitHub上で以下の画像のように表示され、
処理の把握がしやすくなります。

⑤runs-on
　ワークフローで使用される仮想環境を指定します。パート1で紹介したようにコストはUbuntuが一番抑えられるため、”ubuntu-latest”（Ubuntuの最新バージョン）を指定します。

⑥uses
　これは、actionです。パート1の復習になりますが、複雑な処理を一行で行うことができます。

⑦run
　runはワークフロー内で実行される個々のコマンドやスクリプトを指定するためのキーです。
これは、ジョブ内のステップとして使用され、そのコマンドが実行されるコマンドやスクリプトを定義しています。

ステップの説明

今回のワークフローの目的は、「mainブランチ以外でpushをした際にコードが成形される」というものです。ワークフローの目的から一つ一つ処理項目を検討してステップを追加していくことが必要です。今回設定したステップについて一つ一つ確認していきたいと思います。

1. リポジトリのチェックアウト
”actions/checkout@v4”はGitHubリポジトリからコードをチェックアウト（取得）するために使用しています。通常、ワークフローの最初のステップとして配置され、ワークフローが実行される環境にリポジトリのコードを持ってきます。

2. Git の設定
git configコマンドを使用して、Git のユーザー名とメールアドレスを設定します。
これにより、コミット時の識別子が設定されます。

3. パッケージのインストール
yarn installコマンドを使用して、必要なパッケージをインストールします。
このステップは、依存関係を解決するために行われます。

4. GitHub への情報の設定
git remote set-urlコマンドを使用して、リモートリポジトリの URL を設定します。
これにより、コードのプッシュ先が正しく設定されます。

5. コードのフォーマット
yarn run formatコマンドを使用して、コードのフォーマットを行います。
このステップでは、今回のワークフローの目的であるコードの整形が行われます。

6. ステータスの確認
git statusコマンドを使用して、変更されたファイルのステータスを確認します。
これにより、変更が正しくステージングされたかどうかを確認できます。

7. 変更のステージング
git diff –quiet && git diff –staged –quiet || git add .コマンドを使用して、変更をステージングします。このステップでは、変更がステージングされていない場合にのみ、変更をステージングします。

8. 変更のコミット
git diff –quiet && git diff –staged –quiet || git commit -m “Format code automatically”コマンドを使用して、変更をコミットします。このステップでは、変更がある場合にのみ、コミットが行われます。

9. 変更のプッシュ
git diff –quiet && git diff –staged –quiet || git push origin HEAD:$(git symbolic-ref –short HEAD)コマンドを使用して、変更をリモートリポジトリにプッシュします。
このステップでは、変更がある場合にのみ、プッシュが行われます。

7,8,9のステップに関しては、以下のようにまとめて処理を行うことも可能ですがステップを分けることでエラーが発生した際にエラーの原因を特定しやすくなります。

git diff --quiet && git diff --staged --quiet || git add . && git commit -m "Format code automatically" && git push origin HEAD:$(git symbolic-ref --short HEAD)

発生したエラー

今回、ワークフローを走らせる上でいくつかのエラーが発生したので、エラーの原因や解決方法についても紹介していきたいと思います。

1. PATの権限不足
　今回、ワークフロー内でフォーマットしたコードをaddからpushまで行うために、
PAT（Personal Access Token）を使用しました。業務で使用する場合は、
セキュリティ面や細かい設定が可能な点からもGitHub Appを導入することをおすすめします。
Github Appについての解説やインストール方法などは、今回の記事から脱線してしまうため、
こちらのGithub Appについてのページをご参照ください。
　今回利用したPATのFine-grained personal access tokenは2022年にBeta版として
リリースされた機能で、従来のPATより粒度が細かくスコープの設定などが可能になっています。
個人利用の場合はFine-grained personal access tokenで十分なセキュリティを確保できると感じました。

　Fine-grainedは細かい設定が可能で便利ですが、ここで必要な設定を見落としエラーが発生していました。
PATの設定の流れは下記のとおりです。
右上のアイコン ->Settings -> Developer Settings -> Personal access tokens -> Fine-grained tokens -> Generate new token

Permissions内を見直し、今回最終的に”Read and Write”のPermissionを付与したのは以下の通りです。

Repository permissions

• Actions
• Administration
• Contents
• Workflows

ワークフローの目的によってPermissionを付与することで、エラーを回避することができます。

add .
git commit -m “Format code automatically”
git push origin HEAD:$(git symbolic-ref --short HEAD)

ワークフロー以外のファイルを触り、このアクションを回すと問題なくpushできていました。
しかし、ワークフローのformat.yamlファイルのみを修正しpushすると、ワークフローが動く前後つまりフォーマットされる前と後で差分ができないのでエラーが吐き出されていました。
そのエラーを解消するために下記のコードを追加しました。

git diff --quiet && git diff --staged --quiet

これは、ステージングエリアと最新のコミットとの間での差分を確認し、変更がない場合は何も表示されずに終了します。変更がある場合のみ、addからpushまでを行うように修正することで、エラーを解消することができました。

　Github Actiuonsのエラーは、以下の画像のようにどのステップで発生しているのか一目瞭然なので、エラーの原因特定もそこまで難易度は高くないように感じました。

おわりに

繰り返し行うテストやデプロイなどの作業を
効率的に実行することができるGitHub Actionは、導入も手軽で始めやすい機能です。
今回行ったformatなどのテストやスクリーニング作業は、
人の目だと見落としてしまうこともあるので、効率的且つ合理的に行うためにも
積極的に自動化できるCI/CDツールを活用していきたいと思いました。