GitHub Actionsのクイックスタートデモをしっかり理解する

はじめに

仕事でCI/CDに携わることになりました。
技術選定はGitHub Actionsに指定を受けたのですが、使い込んだというほどではありませんでした。使いそうな知識を記事として公開しつつ、どんどん追記していきたいと思います。

はじめての動作

公式のクイックスタートをやってみました。じっくりとこれを記事にして考えることで理解度を深めていきます。

ルートディレクトリに.github/workflowsを作成します。その下にxxx.yamlを作成。このYAMLファイルに処理を記述することがスタートです。

demo.yaml

name: GitHub Actions Demo
run-name: ${{ github.actor }} is testing out GitHub Actions 🚀
on: [push]
jobs:
  Explore-GitHub-Actions:
    runs-on: ubuntu-latest
    steps:
      - run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event."
      - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by GitHub!"
      - run: echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
      - name: Check out repository code
        uses: actions/checkout@v3
      - run: echo "💡 The ${{ github.repository }} repository has been cloned to the runner."
      - run: echo "🖥️ The workflow is now ready to test your code on the runner."
      - name: List files in the repository
        run: |
          ls ${{ github.workspace }}
      - run: echo "🍏 This job's status is ${{ job.status }}."

Pushし、GitHubの画面をみてみます。登録したワークフローが現れました。

さっそくReadMe.mdを更新Pushしてみます。ワークフローが動作しました。

Jobsにて詳細がみれます。

ここまででわかったことを記載していきます。
すこしずつ理解していきましょう。

name:

ワークフローの名前。Actionsに表示されています。

run-name:

ワークフローから生成されたワークフロー実行の名前。これもActionsに表示されています。

コンテキスト

${{ github.actor }}のように ${{}} でくくることでコンテキスト情報へアクセスできます。
デモではいくつか使われていますね。

• github.actor：実行した人が設定されるようです。だれがデプロイをおこなったのか証跡を残すのに便利そうです
• github.event_name：どのイベントでトリガーしたか表示されます。複数のトリガー条件を設定している場合は便利でしょう。例えばon [push, label]のように複数イベントを設定した場合です。
• runner.os：実行OSが表示されます。デバッグログ的なものでしょうか。必須ではないかもしれません。
• github.ref：どのブランチで実行されたのかがわかります。ブランチによって動作がわかれるようなケースだと重要な情報であるでしょう。ブランチ名のみで表示させたい場合はgithub.ref_nameとするようです。
• github.repository：リポジトリ名が記録されます。ログをSlackなどに転記するようなケースだと役に立ちそうです
• github.workspace：規定の作業ディレクトリ表示のようでした。デバッグログ的なものでしょうか。必須ではないかもしれません。
• job.status：success、failure、または cancelledが設定されます。今回の実行結果はsuccessが表示されていますね。

on:

ワークフローをどうやってトリガーするかが記載されています。今回の例だと[push]なのでGitHubへPushが発生するとトリガーされます。[]でくくる必要性は１つではなく省略可能です。2つ以上ある場合は配列のように記載することができます。以下のようにすればブランチを指定することができるなど応用は様々です。深く知ることがご自身の引き出しとなってきますので詳しく公式ドキュメントを読み込むとよいでしょう

  push:
    branches:
      - main

push以外だと、workflow_dispatchのイベントはとても便利で使っていくことになるでしょう。これを設定すると手動でワークフローを動作できるようになります。
ワークフローを動かしたいシーンはデプロイだけではありません。チェック関連やテスト実行など様々です。ユースケースについても調べておく必要があると思います。

jobs:

1つのワークフローには1つ以上のジョブを定義します。1つのイベントから2つ以上のジョブを作ることもでき、それらは依存関係を定義することで順番を固定できます。

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

Explore-GitHub-Actions:

ジョブの名前です。名前以下が1ジョブとなります。この名称は何でも問題ありません。

runs-on:

ジョブのランナーを選択することができます。GitHubがホストしているランナーは公式サイトから確認しましょう。執筆時点では以下となります。

steps:

ジョブのステップです。後続のハイフン１つずつが別ステップとなるのですが、別シェルが動くという構造になっています。１つのシェルで実行したいケースではまとめて記載する必要があるでしょう。

- run:

実行文です。ランナーに合わせた構文を記載します。複数のシェルを実行するサンプルを記載しておきます。

run: |
   echo "install pkgs"
   apt install vim

- name:

説明書きです。こちらもしっかりと実行ログに残ります。

- uses:

実行アクションを指定します。ここには無数のアクションが存在していて把握することが難しいでしょう。公式のactions/xxxxはGitHubより探してください。サードパーティ製など様々あります。
https://github.com/actions

さいごに

ここで紹介したのはまだ入門レベルとなります。しかし、ここから先は応用知識を蓄えていくだけですのでスタートラインには立てたでしょう。ビジネスレベルではもう少し先のレベルに到達する必要があります。私もプロダクトで使う予定ですのでもっと学んでいこうかと思っています。