【GitHub】GitHub Actionsの使い方、構文について徹底解説!!

【GitHub】 GitHub Actionsの使い方、 構文について徹底解説!! インフラ
スポンサーリンク

はじめに

この記事で分かること
  • ワークフローの構造
  • ymlファイルの記述方法
ぴんくうさぎ
ぴんくうさぎ

うさぎの現場、CIでGitHub Actionsを使っているんだけど、

コードが全然読めないぞ。

みどりがめ
みどりがめ

今回はGitHub Actionsのymlファイルの書き方

について学んでいこう!

GitHub Actionsの基礎知識については以下で解説しております。併せて参照ください。

ワークフローの構造

実行する処理はワークフロー(YAMLファイル)に定義していきます。
また、実行する処理はワークフロー、ジョブ、ステップの3層構造で成り立っています。

workflowの構造

ワークフロー(workflow)

.github/workflow以下に配置される一つのYAMLファイルが一つのワークフローになります。
ワークフローは、イベントのトリガーや実行条件、ジョブのシーケンスなどを定義します。

YAMLファイルが複数あれば、複数のワークフローが定義されていることになります。
また、実行時にはワークフローは並列で実行されます。

ジョブ(job)

ジョブはワークフロー内で実行される単一のタスク単位です。
ワークフロー内に複数のジョブを定義することができ、それぞれのジョブは並列に実行されます。
ジョブ毎に実行環境が立ち上がって処理が実行されるため、ジョブ毎に異なる環境やプラットフォームで実行することが可能です。

ステップ(step)

ステップはジョブ内の個々の処理です。コマンドやAction、スクリプトなど処理の実態を定義します。
例えば、ソースコードのビルド、テストの実行、デプロイの実施など具体的な処理を記載していきます。
各ステップは前のステップの完了に依存して実行されます。

以下に具体的なワークフローを記載しています。
上記の解説との対応を意識して読んでみてください。

# ワークフローの名称
name: 'Hello World'
# ①トリガー
on: [push]

jobs: #②ジョブ
  hello-world:
    name: hello world job
    runs-on: ubuntu-latest
    steps: #③ステップ
      - run: echo "Hello World!!"

トリガー

ワークフローが実行されるきっかけです。「on」配下に記載します。
例えば、以下のようなものがあります。

種別記述説明
イベントpush push時に実行される。
イベントforkfork時に実行される。
イベントpull_requestpull_request作成時に実行される。
スケジュールschedule決められた時刻に定期的に実行
手動実行workflow_dispatchGitHubのブラウザ上から実行する
他のワークフロー依存workflow_run他のワークフローの完了をトリガーに実行

記述例は以下の通りです。

# masterブランチにpush時に実行される
on:
  push:
    branches:
      - master
# 毎日11:30(UTC)に実行される
on:
  schedule:
    - cron:  '30 11 * * *'

ジョブ

ジョブはワークフロー内で実行される単一の処理のかたまりです。
「runs-on」で指定する実行環境には「windows-latest」、「macos-11」など様々なランナーを指定できます。

jobs: 
  hello-world: #ジョブID
    name: hello world job #ジョブ名
    runs-on: ubuntu-latest #実行する環境(ランナー)
    steps: #実行する処理(ステップ)を記述していく

ステップ

ステップはジョブ内の個々の処理です。
コマンドやAction、スクリプトなど処理の実態を定義します。
以下にいくつか記載例を示します。

コマンドを実行する際は「run」を使用します。

jobs: 
  hello-world:
    name: hello world job
    runs-on: ubuntu-latest
    steps: 
      - name: hello world #ステップ名
        run: echo "hello world!!" #実行したいコマンドを記述する

アクションを実行するには「uses」を使用します。
アクションはマーケットプレースに定義されたものを使用したり、ワークフロー内に定義したものを利用することができます。

例えば、以下はSlack通知をするためのアクションを使用しています。

    steps:
      - name: Slack Notify Sample #ステップ名
        uses: slackapi/slack-github-action@v1.24.0 #実行したいアクションを記述する
        with: #引数を指定する。どのような引数があるかは各アクションの説明箇所を確認する
          channel-id: '{チャンネルID}'
          payload: |
            {
              "attachments": [
                {
                  "blocks": [
                    {
                      "type": "section",
                      "text": {
                        "type": "plain_text",
                        "text": "Slack通知サンプルです。",
                        "emoji": true
                      }
                    }
                  ]
                }
              ]
            }
        env:
          SLACK_BOT_TOKEN: ${{secrets.SLACK_API_TOKEN}}

マーケットプレイスのアクションは以下から探します。

Build software better, together
GitHub is where people build software. More than 100 million people use GitHub to discover, fork, an...

環境変数

外部から値を与える仕組みです。
以下ではenvとしてAWS_REGIONを定義し、step内で使用しています。

env:
  AWS_REGION: ap-northeast-1

jobs:
  terraform:
    name: 'terraform'
    runs-on: ubuntu-latest
    steps:
          terraform fmt -check
      - name: Configure AWS credential
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-region: ${{env.AWS_REGION}}

環境変数はGitHub側でデフォルトで定義されているのものがあります。

key説明
GITHUB_REPOSITORYリポジトリ名
GITHUB_RUN_IDワークフローの一意なID
GITHUB_EVENT_NAMEトリガーされたイベント名

詳しくは以下に記載されています。

変数 - GitHub Docs
GitHub は GitHub Actions ワークフロー実行ごとに、既定の変数を設定します。 単一のワークフローまたは複数のワークフローで使用するカスタム変数を設定することもできます。

シークレット

秘匿情報をコードに直接ハードコードせず、GitHubのシークレットとして登録し利用する仕組みです。
シークレットに登録された値は実行環境では表示されません(**に置換されます。)。

以下はstepでも紹介したSlack通知の実装例です。末尾のenvでGitHubに登録されたシークレットを読み込んでいます。

    steps:
      - name: Slack Notify Sample 
        uses: slackapi/slack-github-action@v1.24.0 
        with: 
          channel-id: '{チャンネルID}'
          payload: |
            {
              "attachments": [
                {
                  "blocks": [
                    {
                      "type": "section",
                      "text": {
                        "type": "plain_text",
                        "text": "Slack通知サンプルです。",
                        "emoji": true
                      }
                    }
                  ]
                }
              ]
            }
        env:
          SLACK_BOT_TOKEN: ${{secrets.SLACK_API_TOKEN}}

GitHub上にシークレットを作成する方法は以下をご確認ください。

GitHub Actions でのシークレットの使用 - GitHub Docs
シークレットは、機密情報を組織、リポジトリ、リポジトリ環境に格納できるようにします。

条件分岐

GitHub Actions上の条件分岐はif文を使います。
例えば、以下ではイベントがpull_reuqestだった場合のみ、stepの処理を実行します。

jobs:
  notify:
    name: Slack Notify Sample
    runs-on: ubuntu-latest
    steps:
      - name: Slack Notify Sample
        if: github.event_name == 'pull_request'
        uses: slackapi/slack-github-action@v1.24.0

依存関係

基本的にジョブは並列で実行されます。
何らかの理由で直列で実行したい場合には、依存関係(needs)を定義します。

以下はjobBの開始条件として、jobAが正常に完了する必要があります。
また、jobCの開始条件として、jobA、jobBが正常に完了する必要があります。

jobs:
  jobA:
  jobB:
    needs: jobA
  jobC:
    needs: [jobA, jobB]

終わりに

本記事はここまでとなります。

最後にGitHub Actionsの学習におすすめのUdemy講座を紹介します。
いずれも多くの方に支持されているベストセラーです。是非、学習にご活用ください。

ご覧いただきありがとうございました。ご指摘等がございましたら頂けますと嬉しいです。
引き続き、プログラミングについて定期的に発信していきますのでよろしくお願いします!
また、もしよろしければtwitterもフォローしていただけると嬉しいです!🐢

コメント