GitHub Actions でカスタムアクションを作成し他のリポジトリから利用する

前提条件

• GitHub のアカウントを持っていること
• GitHub Actions について基本的な操作を理解していること

GitHub Actions のカスタムアクションとは

GitHub Actions では独自のコンテナやコード、タスクをカスタムアクションとしてパブリックやMarketplace に公開したり組織内で利用できます。GitHub Actions のカスタムアクションにはDocker コンテナアクションとJavaScript アクション、Composite アクションの3種類があります。

Docker コンテナアクションはコンテナに様々なツールや依存関係をパッケージ化してGitHub Actions のジョブで利用します。Docker コンテナアクションで利用できるOS はLinux のみとなります。ジョブに必要なツールや環境をコンテナとして整えられるため、ツール準備のタスクを少なくできます。ただし、ジョブの中でコンテナの準備が必要となるため、他のアクションより実行速度が遅くなることもあります。

JavaScript アクションはアクションで実行するタスクをJavaScript (TypeScript) で記述するアクションです。処理の内容をコード化できるため様々なカスタマイズが可能です。JavaScript アクションはWindows、macOS、Linux で利用可能です。 actions/checkout などの公式で提供されているアクションもTypeScript を利用したアクションです。JavaScript アクションはGitHub Actions Toolkit でNode.js の開発パッケージも提供されています。

Composite アクションは複数のワークフローを1つのタスクとしてまとめられるアクションです。同じ処理を何度も繰り返して利用する場合や組織内で利用するツール用の処理などの用途で利用されます。ワークフローのファイル名にはaction.yml またはaction.yaml を指定します。ユーザー側で決まったワークフローを何度も設定する必要が無くなるため、まとまった処理のカスタムアクションを提供することで開発の負担を削減できます。ただし、Composite アクションではシークレットや変数が利用できないため、これらの値を利用する場合はワークフローで入力するなどの対処が必要です。

カスタムアクション化する内容、Marketplace のカスタムアクション

カスタムアクションを作成し利用するケースは以下のようなものが想定されます。

• 開発、インフラ構築における共通タスク
• 既存タスクの効率化、独自設定追加
• 各種ツールの操作、設定
• 組織独自の環境設定
• 特定用途に合わせた既存タスクのカスタマイズ

カスタムアクションを作成するのも良いですが、GitHub ではカスタムアクションを公開しているMarketplace があります。カスタムアクションを作成する前に想定する処理のタスクがMarketplace で公開されていないかを確認しましょう。

Marketplace

Marketplace に目的のアクションがあればそちらを使うのも一つの手段です。ただし、Marketplace に要件に合うアクションがあるとは限らないため、目的のアクションが無ければ独自で作成も検討します。カスタムアクションを使う際にはある程度中身を確認した上で利用するのが望ましいです。信頼性の低い発行元だと、カスタムアクションを用いたスクリプトインジェクションなどのセキュリティリスクもあるため注意が必要です。

カスタムアクションの公開

カスタムアクションはパブリック、組織 (プライベート)、Marketplace で公開できます。パブリックで公開する場合はリポジトリの公開範囲をパブリックにし、ブランチを指定するまたはリリースを作成して参照できるようにします。GitHub Enterprise Server やEnterprise Cloud では公開範囲を組織内でのみ指定することで、組織に所属するユーザーにのみカスタムアクションを公開できます。GitHub には様々なカスタムアクションを公開する Marketplace があり、リリースの作成時にMarketplace への公開にチェックを入れることで公開できます。Marketplace のカスタムアクションは公開後にGitHub 側でレビューが行われますが、一定の要件を満たせばこのレビューが不要となります。今回は扱いませんが、Marketplace 公開の詳細は以下ドキュメントを参照してください。

GitHub Marketplaceでのアクションの公開

カスタムアクションをユーザーに公開する場合、タグやブランチを利用したリリース管理が推奨されています。GitHub Marketplace で公開する場合は新しいリリースでのタグ付けが必要となります。タグやブランチ以外にも、カスタムアクションをどのように利用するかのREADME も準備が必要です。GitHub のドキュメントでは以下のような項目が挙げられています。

• アクションの動作に関する詳細な説明
• 必須の入力および出力の引数
• 省略可能な入力および出力の引数
• アクションで使用されるシークレット
• アクションで使用される環境変数
• ワークフローでのアクションの使用方法の例

カスタムアクションの注意点

カスタムアクションは既存のアクションを利用するのと違い、作成後に運用・管理が必要です。不必要にカスタムアクションを作成すると、メンテナンス工数が増加し負債化する恐れもあります。また、独自のカスタムアクションばかりでワークフローを構成すると、カスタムアクションに依存し変更がしにくくなる、カスタムアクションの意図しない修正でジョブが失敗することもあります。

カスタムアクションを組織内で利用する場合は事前の設計が重要です。特に組織名、リポジトリ、フォルダ名は変更すると影響が大きくなるため、事前にどのような用途で利用するか、どういった役割で分割するかを決めておきます。また、リポジトリ名やフォルダ名を変更する場合、ユーザー側のワークフローファイル修正が必要となるため極力避けるようにしてください。

今回の構成

今回はカスタムアクションの仕組みを知るために、渡したパラメーターを表示するカスタムアクションを作成します。リポジトリはカスタムアクション用のリポジトリとワークフローファイル用の2つを使います。リポジトリ名は以下で分けます。

カスタムアクション用のリポジトリ構成は以下となります。

.
├── README.md
└── action.yaml

ワークフローファイル用のリポジトリ構成は以下となります。

.
└── .github
    └── workflows
        └── workflow.yaml

カスタムアクションの作成

初めにカスタムアクションのaction.yaml ファイルを作成します。ワークフローファイルから引数を受け取るためinputs を使います。

name: Echo parameter
description: Output parameter in terminal

inputs:
  parameter:
    description: "Parameter for echo."
    required: true

runs:
  using: composite
  steps:
    - name: "echo test"
      shell: bash
      run: echo "設定したパラメーターは ${{ inputs.parameter }} です。"

action.yaml の準備後、README ファイルを作成します。今回は使い方とパラメーターを簡易的に記載していますが、README の記載は個人や組織のルールに沿って記載してください。

# echoparam

このカスタムアクションは受け取ったパラメーターをターミナルに表示するアクションです

## 変数

このアクションを利用するには以下の引数が必要です。

| パラメーター  | 型 | 概要 |
| ------------- | ------------- | ------------- |
| parameter | String | ワークフローで表示するパラメーター  |

## 使い方

このアクションはワークフローファイルで以下のように呼び出します。

```yaml
jobs:
  echo-example:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: <GitHubアカウント名 or 組織名>/echoparam@main
        with:
          parameter: "hogehoge"
```

ワークフローファイルの作成

カスタムアクション作成後、ワークフローファイルを作成します。今回はブランチ名で指定する方法でカスタムアクションを利用します。

name: Custom Action demo

on: [push]

jobs:
  EchoParameter:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: <GitHubアカウント名 or 組織名>/echoparam@main
        with:
          parameter: "hogehoge"

ワークフロー作成後、ワークフローファイル用のリポジトリにプッシュします。

動作確認

ワークフローファイルのプッシュ後、GitHub Actions が実行されるため結果を確認します。ジョブ内でカスタムアクションを実行し、実行結果にパラメーターが表示されたことを確認します。

まとめ

• GitHub Actions では独自のコンテナやコード、タスクをまとめたカスタムアクションを作成できる
• カスタムアクションはパブリックリポジトリやMarketplace、組織内に制限した公開が可能
• 組織内でカスタムアクションを公開する場合、事前の設計や運用・管理面も考慮した上で提供する

参考資料

• カスタム アクションについて
• Docker コンテナーのアクションを作成する
• JavaScript アクションを作成する
• 複合アクションを作成する