2022-04-15

• #github
• #github-actions
• #circleci

Overview

Belong はこれまで CircleCI を CI/CD ツールとして用いていました。 今後 GitHub Action にふれる機会が増えそうなので、CircleCI 経験者が素早く GitHub Actions に慣れられるようなポイントをまとめたいと思います。

GitHub Actions の概要

GitHub Actions の概要についてまず少し触れて概念を理解してから CiecleCI との違いを見ていきます。 詳しく知りたい場合は公式ドキュメントを読むことをお勧めします。

GitHub Actions のコンポーネント

• ワークフロー
  • ワークフローは特定のイベントにより起動する処理のこと
• イベント
  • ワークフローを起動させるトリガーとなるもの
• ジョブ
  • ワークフロー内で複数のステップにより定義される処理のこと
  • ジョブを分けるとワークフロー内の別の処理として UI にも表現される
• アクション
  • アクションは繰り返し利用されるような処理を定義する GitHub Actions で利用されるカスタムアプリケーション
• ランナー
  • ワークフローが走る実行環境

ワークフローの例 (公式ドキュメントより)

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

CircleCI と GitHub Action

設定ファイルのパス

CircleCI の場合は基本的に .circleci/conig.yml の形で設定を定義します。

再利用可能なリソースを Orbs として別ファイルに定義して再利用したりもしますが、そのリポジトリのワークフローで利用する場合には同一ファイル内の jobs で定義し、環境ごとのワークフローを作ってジョブを使い回すことも出来ます。

|-- repository
|   |__ .circleci
|       └── config.yml

CircleCI の設定ファイルで使われる基本的なフィールド:

version:
orbs:
executors:
jobs:
  my-job:
    executor:
    steps:
      -
workflows:
  version:
  my-workflow-dev
    jobs:
      - my-job:
        requires:
        filters:

GitHub の場合、設定ファイル構成は以下のようになります。実行の主体となるワークフローは .github/workflows ディレクトリ以下に YAML ファイルで定義します。 .github/actions については後ほど触れます。

|-- repository
|   |__ .github
|       └── workflows
|           └── my-workflow.yml
|       └── actions
|           |__ my-action
|               └── action.yml

イベント

CircleCI 特定のイベントのみで処理を走らせたい場合ワークフロー内のジョブ毎に filters を設定し、branch や tag の条件を指定します。 また、branch と tag 双方で走ると言った制限は難しく、別のワークフローで定義する必要があります¹。

workflows:
  my-workflow-dev
    jobs:
      - my-job:
        filters:
          branches:
           develop

GitHub Actions の場合、on 構文を用いてイベントはワークフローのファイルごとに定義します。

on:
  push:
    branches:
      - main
      - develop
    tags:
      - v2
      - v1.*

ジョブの依存管理

CircleCI は job で requires を用います。

workflows:
  version:
  my-workflow-dev
    jobs:
      - my-job:
          ...
      - my-job2:
        requires: my-job

GitHub Action は job で needs を用います

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

ランナー

CircleCI の実行環境は executors で指定でき、環境も Docker などを指定して様々な環境が選べます。

GitHub Actions の実行環境は Linux (ubuntu), macOS, Windows と絞られており、必要に応じて環境上で Docker などを立ち上げて処理が可能です。

実行環境で利用可能なソフトウェアは Setup Job -> Virtual Environment -> Included Software で見つけることが出来ます。 本記事執筆時点での Linux は Ubuntu 20.04.4 LTS で、含まれるソフトウェアは Ubuntu2004-Readme.mdで確認可能です。

再利用可能な処理

CircleCI は再利用可能な処理は jobs フィールドもしくは orbs で定義ができました。 同一ファイル内で利用するだけなら jobs で定義し、環境毎に異なるパラメータを用いるワークフローから引数を変えて呼び出すことが出来ますし、複数のリポジトリで再利用可能にしたい場合はカスタム Orbs を定義して各リポジトリからインポートができます。

orbs:
  custom-orbs
executors:
  docker
jobs:
  my-job:
    executor: docker
    steps:
    - custom-orbs
workflows:
  my-workflow-dev
    jobs:
      - my-job:

GitHub Actions で再利用可能な処理を定義する場合は Action を用います。

About Custom Actions に詳しくありますが、Custom Actions には以下のような特徴があります。

• いくつかの作成方法がある
  • Docker を用いて処理を定義する
  • JavaScript を用いて処理を定義する
  • Yaml を用いて複数の step で処理を定義する (Composite action)
• Action 毎に個別のファイル
• .github/ACTION_NAME/action.yml (もしくは action.yaml) というファイル名である必要がある

YAML を用いて Action を定義すると以下のようになります。

.github/actions/sample-composite-action/action.yml

name: 'Sample Composite Action'
description: 'Composite action usable fields are listed'
inputs:
  sample_input:
    description: 'Sample Input Value'
    required: true
runs:
  using: 'composite'
  steps:

このアクションを同一のリポジトリ内で利用すると以下の形になります。

name: 'Dev deploy'

jobs:
  use-sample-action
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: 'Go Sample'
        uses: ./.github/actions/sample-composite-action
        with:
          sample_input: 'sample-value'

Rerefences

1. Workflow syntax for GitHub Actions

Footnotes

1. 少なくとも弊社ではそうしてました ↩