GitHub Actions 導入までの流れ - ShirotsuのCG学習録

GitHubで利用できるCI/CD機能 GitHub Actions を利用する際の流れまとめ。
備忘録的に記していきます。

1. YAMLファイル記述と設置

Actionsを利用するために、YAMLファイルに自動実行するプロセスを記述します。

YAMLファイルの置き場所

リポジトリのルートディレクトリ直下に.github/workflowsというディレクトリを作り、その下に任意のファイル名でYAMLファイルを設置します。
すると、Actionsが自動で読み込んで特定のタイミングで実行してくれるようになります。

# 例
REPOSITORY_ROOT/.github/workflows/build_verification.yml

記述項目

Actions固有の設定項目や実行プロセス名などを書き込んでいきます。
詳しくは -> GitHub Actionsのワークフロー構文 - GitHubヘルプ
以下重要なものを列挙します。

name : このYAMLファイルで実行するワークフローの名前指定。
on : ワークフローを実行するトリガーイベントの指定。
jobs : 一連のワークフロー実行のブロック。OSごとのテストや他のプロセスのひとまとまりなどをまとめる。この下(インデント的に)に↓の構文を記述していく。
- <任意のジョブ名> : ジョブ名指定。
  - runs-on : ワークフローの各ジョブを実行する仮想環境の指定。仮想マシンについては後述。
  - needs : このジョブを実行する前に終わらせる必要のある他ジョブを指定。
  - steps : 1つ以上のアクションまたはシェルコマンドを実行。複数の場合は配列として記述する。
    - name : 1つのステップの名前。GitHub上で表示される。
    - uses : ステップの一部として実行するアクションを指定。公開されているパブリックリポジトリのものなどを使用できる。
    - run : シェルコマンドを実行する。
    - shell : 実行するシェルを指定。bashやpythonなど。bashはWin/mac/Linuxすべてで利用可。
  - container : ジョブを実行するコンテナの指定。
    - image : Dockerイメージの指定。Docker Hubイメージ名かpublic dockerレジストリ名で。

  # 例
  name : Build
  on   : [push, pull_request]
  jobs : 
    example_job:
      runs-on : ubuntu-latest
      
    release_build:
      runs-on : ubuntu-latest
      needs   : example_job
      steps   : 
        - name : Print path
          run  : echo $PATH
          shell: bash
          
        - uses : actions/setup-node@74bc508

2. ステータスバッジ設置

ワークフローのステータスを表示するバッジを表示します。
README.mdによくある Build|passingみたいなやつ。
以下のうちどちらかのURLで画像を取得できます。

https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_NAME>/badge.svg
https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_FILE_PATH>/badge.svg

あとはREADME.mdなどに
![build status](<上のURL>)
などとすればOK。

3. GitHub上で確認

私のリポジトリにこのようなYAMLファイルを追加し、確認してみます。

name: build

on: 
  push:
    branches:
      - autobuild_setup

jobs:
  build:
    runs-on: ubuntu-latest
    steps  :
      - name : test print
        run  : echo "this is test print"
        shell: bash

YAMLファイルをpushしたリポジトリのActionsタブを見ると、実行されたワークフローの履歴が表示されています。 github tab 最新のbuildを見てみると、こうなりました。
しっかりbuildのtest printが実行されてthis is test printが出力されています。

build detail

ステータス表示はこんな感じで。

github badge

appendix 1. ワークフロー実行の仮想環境

ワークフローを実行する仮想マシン環境を指定できます。

GitHubホストランナー

GitHubが標準で用意している環境を「GitHubホストランナー」といい、Actionsを実行するアプリケーションがインストールされています。
Windows macOS Linux のActions環境を用意してくれているようです。
LinuxとmacOSに関しては、パスワード無しでsudoつきコマンドを実行できます。
以下、yamlのruns-onに指定できるラベル一覧。

windows-latest : Windows Server 2019
ubuntu-latest : Ubuntu 18.04
ubuntu-18.04 : Ubuntu 18.04
macos-latest : macOS Catalina 10.15

これらの環境に標準でインストールされているコマンド/ツールはここ -> GitHubホストランナーにインストールされるソフトウェア - GitHubヘルプ

自己ホストランナー

実行する仮想マシン指定は、GitHubホストランナーでないものも利用できます。
この記事では詳しくは触れません。
以下参考リンク↓
自己ホストランナーについて - GitHubヘルプ
 ワークフローでのセルフホストランナーの利用 - GitHubヘルプ

appendix 2. Dockerコンテナ

CI/CDを実現したいリポジトリとは別にリポジトリを作成し、そちらのルートディレクトリにDockerfile, action.yml, extrypoint.shを置くことで1つのアクションとして公開できます。
こうするとCI/CDを実現したいリポジトリのワークフローYAMLファイルの jobs.<jobname>.steps.usesで指定できるようになります。
詳細 -> Dockerコンテナのアクションを作成する - GitHubヘルプ

参考文献

ワークフローを設定する - GitHubヘルプ
 GitHubホストランナーの仮想環境 - GitHubヘルプ
 GitHub Actionsのワークフロー構文 - GitHubヘルプ
 Dockerコンテナのアクションを作成する - GitHubヘルプ
 GitHubホストランナーにインストールされるソフトウェア - GitHubヘルプ
 自己ホストランナーについて - GitHubヘルプ
 ワークフローでのセルフホストランナーの利用 - GitHubヘルプ

2020/1/1 追記
詳しい解説記事を見つけましたので追加しておきます。