GitHub - Actions
概要
GitHub Actionsは、GitHubリポジトリ内でCI/CD (継続的インテグレーション / 継続的デリバリー) ワークフローを構築・実行できる自動化プラットフォームである。
コードのプッシュやPullRequestの作成といったリポジトリのイベントをトリガーとして、テスト・ビルド・デプロイ等の処理を自動化できる。
ワークフローはYAML形式で定義され、リポジトリの .github/workflows/ ディレクトリに配置する。
GitHub Actionsを構成する主要な概念を以下に示す。
- ワークフロー (Workflow)
- 1つ以上のジョブで構成される自動化プロセス全体を指す。
- YAMLファイルとして定義され、特定のイベントによってトリガーされる。
- ジョブ (Job)
- ワークフロー内で並列または順次実行される処理単位である。
- 各ジョブは独立したランナー環境で実行される。
- ステップ (Step)
- ジョブ内で順次実行されるコマンドまたはアクションの単位である。
- アクション (Action)
- 複雑な処理をカプセル化した再利用可能なコンポーネントである。
- GitHubが提供する公式アクションの他、GitHub Marketplaceからサードパーティ製アクションを利用できる。
ワークフローの基本
ワークフローファイル
ワークフローファイルは、リポジトリの .github/workflows/ ディレクトリにYAML形式で配置する。
1つのリポジトリに複数のワークフローファイルを配置することができる。
ワークフローファイルの基本構造を以下に示す。
name: ワークフロー名
on:
push:
branches: [ "main" ]
pull_request:
branches: [ "main" ]
permissions:
contents: read
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: ステップ名
run: echo "Hello, World!"
下表に、ワークフローを構成する主要なキーを示す。
| 設定項目 | 説明 |
|---|---|
name |
ワークフローの名称 GitHubのActionsタブに表示される。 |
on |
ワークフローをトリガーするイベントを定義する。 |
permissions |
GITHUB_TOKENに付与する権限を定義する。 |
jobs |
実行するジョブの定義を記述する。 |
トリガー (イベント)
ワークフローのトリガーは on キーで定義する。
下表に、主なトリガーイベントを示す。
| イベント | 説明 |
|---|---|
push |
コードがプッシュされた時にトリガーされる。 |
pull_request |
Pull Requestが作成・更新・マージされた時にトリガーされる。 |
schedule |
cron形式で指定したスケジュールに従い定期実行される。 |
workflow_dispatch |
GitHub Web UI または APIから手動でトリガーできる。 |
release |
リリースが作成・公開された時にトリガーされる。 |
issues |
Issueが作成・編集・クローズされた時にトリガーされる。 |
workflow_run |
別のワークフローの完了をトリガーとして実行される。 |
repository_dispatch |
外部システムからのAPIリクエストによってトリガーされる。 |
ブランチやパスでフィルタリングする例を以下に示す。
on:
push:
branches:
- main
- "release/**"
paths:
- "src/**"
- "!src/docs/**"
paths-ignore:
- "**.md"
pull_request:
types: [opened, synchronize, reopened]
branches:
- main
schedule:
- cron: "0 9 * * 1-5"
workflow_dispatch:
inputs:
environment:
description: "デプロイ先の環境"
required: true
default: "staging"
下表に、フィルタリングに使用できるキーを以下に示す。
| 設定項目 | 説明 |
|---|---|
branches |
対象ブランチを指定する。 ワイルドカード ( *, **) が使用できる。
|
paths |
指定したパスのファイルが変更された場合のみトリガーされる。! プレフィックスで除外パスを指定できる。
|
paths-ignore |
指定したパスのファイルのみが変更された場合はトリガーされない。 |
ジョブとステップ
ジョブの定義
ジョブは jobs キー配下に定義する。
各ジョブは独立したランナー環境で実行され、デフォルトでは並列に実行される。
下表に、ジョブ定義の主要なキーを示す。
| 設定項目 | 説明 |
|---|---|
runs-on |
ジョブを実行するランナーを指定する。 必須項目である。 |
timeout-minutes |
ジョブのタイムアウト時間を分単位で指定する。 デフォルトは360分である。 |
permissions |
ジョブレベルでGITHUB_TOKENの権限を上書き設定できる。 |
jobs:
build:
runs-on: ubuntu-latest
timeout-minutes: 30
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
ジョブ間の依存関係
needs キーを使用して、ジョブ間の依存関係を定義できる。
needs キーに指定したジョブが全て正常に完了した後に、該当ジョブが実行される。
jobs:
build:
runs-on: ubuntu-latest
steps:
- run: echo "ビルド実行"
test:
runs-on: ubuntu-latest
needs: build
steps:
- run: echo "テスト実行"
deploy:
runs-on: ubuntu-latest
needs: [build, test]
steps:
- run: echo "デプロイ実行"
マトリックスビルド
strategy.matrix を使用することにより、複数の環境や設定の組み合わせに対してジョブを並列実行できる。
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
node-version: [18, 20, 22]
max-parallel: 4
fail-fast: false
include:
- os: ubuntu-latest
node-version: 20
experimental: true
exclude:
- os: macos-latest
node-version: 18
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
- run: npm test
マトリックスビルドに関連するキーを以下に示す。
| 設定項目 | 説明 |
|---|---|
matrix |
変数名と値のリストを定義する。 全ての組み合わせに対してジョブが実行される。 |
max-parallel |
同時に実行するジョブの最大数を指定する。 |
fail-fast |
true の場合、いずれかのジョブが失敗すると残りのジョブをキャンセルする。デフォルトは true である。
|
include |
既存の組み合わせに変数を追加 または 新しい組み合わせを追加する。 |
exclude |
特定の組み合わせを除外する。 |
条件付き実行
if キーを使用して、ジョブまたはステップの実行条件を定義できる。
jobs:
deploy:
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
steps:
- name: 成功時のみ実行
if: success()
run: echo "前のステップが成功しました"
- name: 失敗時のみ実行
if: failure()
run: echo "前のステップが失敗しました"
- name: 常に実行
if: always()
run: echo "常に実行されます"
下表に、条件式でよく使用するステータス関数を示す。
| 関数 | 説明 |
|---|---|
success() |
前の全てのステップが成功した場合に true を返す。
|
failure() |
前のステップのいずれかが失敗した場合に true を返す。
|
always() |
常に true を返す。キャンセルされた場合も実行される。 |
cancelled() |
ワークフローがキャンセルされた場合に true を返す。
|
ステップの定義
ステップは steps キー配下に定義する。
各ステップはアクションの実行またはコマンドの実行のいずれかの形式で記述する。
steps:
- name: リポジトリのチェックアウト
uses: actions/checkout@v4
- name: Node.jsのセットアップ
uses: actions/setup-node@v4
with:
node-version: "20"
- name: 依存関係のインストール
run: npm ci
env:
NODE_ENV: production
- name: テストの実行
run: npm test
continue-on-error: true
working-directory: ./app
- name: マルチラインコマンド
shell: bash
run: |
echo "ステップ1"
echo "ステップ2"
下表に、ステップ定義の主要なキーを示す。
| 設定項目 | 説明 |
|---|---|
uses |
実行するアクションを owner/repo@ref 形式で指定する。 |
run |
実行するシェルコマンドを記述する。 |
with |
アクションに渡すパラメータを定義する。 |
env |
ステップレベルで環境変数を設定する。 |
continue-on-error |
true の場合、ステップが失敗してもジョブを継続する。
|
working-directory |
コマンドを実行する作業ディレクトリを指定する。 |
shell |
コマンドを実行するシェルを指定する。 デフォルトは bash (Linux / MacOS) または pwsh (Windows) である。
|
ランナー
GitHubホスト型ランナー
GitHubが提供・管理するランナーを使用する場合、runs-on に以下に示すラベルを指定する。
| ラベル | OS | CPU | RAM |
|---|---|---|---|
ubuntu-latest |
Ubuntu (最新LTS) | 2コア | 7[GB] |
ubuntu-24.04 |
Ubuntu 24.04 | 2コア | 7[GB] |
ubuntu-22.04 |
Ubuntu 22.04 | 2コア | 7[GB] |
windows-latest |
Windows Server (最新) | 2コア | 7[GB] |
macos-latest |
MacOS (最新) | 3コア | 14[GB] |
macos-14 |
MacOS 14 (Apple Silicon) | 3コア | 7[GB] |
GitHubホスト型ランナーは、各ジョブ実行のたびに新しい仮想マシンが用意される。
パブリックリポジトリではGitHubホスト型ランナーを無料で使用できる。
セルフホスト型ランナー
自身で用意したマシンをランナーとして使用できる。
runs-on: self-hosted または 追加ラベルを指定して使用する。
jobs:
build:
runs-on: [self-hosted, linux, x64]
steps:
- uses: actions/checkout@v4
セルフホスト型ランナーの主な特徴を以下に示す。
- 使用時間に対する課金が発生しない。
- 専用のハードウェアやカスタム環境を利用できる。
- ジョブの実行環境を完全にコントロールできる。
- パブリックリポジトリでの使用にはセキュリティリスクが伴うため、推奨されない。
アクション
アクションとは
アクションは、ワークフローのステップとして実行できる再利用可能なコンポーネントである。
下表に、アクションの種類を以下に示す。
| 種類 | 説明 | 対応OS |
|---|---|---|
| Docker container | Dockerコンテナ内で処理を実行する。 | Linuxのみ |
| JavaScript | Node.jsを使用して処理を実行する。 | 全OS対応 |
| Composite | 複数のステップを1つのアクションにまとめる。 | 全OS対応 |
公式アクション
下表に、GitHubが提供する主要な公式アクションを示す。
| アクション | 説明 |
|---|---|
actions/checkout@v4 |
リポジトリのコードをランナーにチェックアウトする。 |
actions/setup-node@v4 |
Node.js環境をセットアップする。 |
actions/setup-python@v5 |
Python環境をセットアップする。 |
actions/setup-java@v4 |
Java環境をセットアップする。 |
actions/cache@v4 |
依存関係等のファイルをキャッシュする。 |
actions/upload-artifact@v4 |
ファイルをアーティファクトとしてアップロードする。 |
actions/download-artifact@v4 |
アップロードしたアーティファクトをダウンロードする。 |
アクションの参照方法
アクションは以下の形式で参照できる。
- GitHubリポジトリのアクション
owner/repo@ref形式で指定する。refにはタグ (v4)、ブランチ名、または、SHA (コミットハッシュ) を指定できる。- セキュリティの観点から、SHA固定が推奨される場合がある。
- ローカルアクション
./.github/actions/アクション名形式で同リポジトリ内のアクションを参照できる。
steps:
# タグ指定
- uses: actions/checkout@v4
# SHA固定
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
# ローカルアクション
- uses: ./.github/actions/my-action
GitHub Marketplace
GitHub Marketplace (https://github.com/marketplace?type=actions) では、コミュニティが公開しているサードパーティ製アクションを検索・利用できる。
サードパーティ製アクションを使用する時は、以下に示す点に注意する。
- アクションのソースコードを確認して、悪意のあるコードが含まれていないことを確認する。
- SHAを固定することにより、意図しないコード変更の影響を防ぐ。
- 信頼できるベンダーが公開しているアクションを優先して使用する。
環境変数とシークレット
環境変数
環境変数はワークフロー全体、ジョブ、ステップの3つのレベルで定義できる。
# ワークフローレベル
env:
APP_ENV: production
jobs:
build:
# ジョブレベル
env:
BUILD_DIR: ./dist
steps:
- name: ビルド
# ステップレベル
env:
NODE_ENV: production
run: npm run build
定義した環境変数は $テンプレート:Env.変数名 または $変数名 (Linux / MacOS) で参照できる。
コンテキスト変数
GitHub Actionsは、ワークフローの実行に関する情報にアクセスするためのコンテキストを提供する。
下表に、主なコンテキスト変数を示す。
| コンテキスト | 主なプロパティ | 説明 |
|---|---|---|
github |
github.event_namegithub.refgithub.shagithub.repositorygithub.actor |
ワークフローのトリガーとなったイベントやリポジトリの情報 |
job |
job.status |
現在のジョブの状態 |
runner |
runner.osrunner.arch |
ランナーのOS情報 |
steps |
steps.ステップID.outputssteps.ステップID.outcome |
前のステップの出力と実行結果 |
matrix |
matrix.変数名 |
マトリックスビルドの現在の変数値 |
シークレット
APIキーやパスワード等の機密情報はシークレットとして管理する。
シークレットはリポジトリ、環境、またはOrganizationレベルで設定できる。
- シークレットの設定場所
- [リポジトリ]ページ - [Settings] - [Secrets and variables] - [Actions]
steps:
- name: デプロイ
env:
API_KEY: ${{ secrets.API_KEY }}
DATABASE_URL: ${{ secrets.DATABASE_URL }}
run: ./deploy.sh
シークレットに関する主な注意事項を以下に示す。
- シークレットの値はログに自動的にマスキングされる。
- フォークされたリポジトリからのPull Requestでは、シークレットは渡されない。
- シークレットの値は設定後に再表示できない。
GITHUB_TOKEN
GITHUB_TOKEN は、各ワークフロー実行時にGitHubが自動的に生成するトークンである。
リポジトリへのアクセス権限を持ち、API呼び出しやリポジトリ操作に使用できる。
permissions キーを使用して、ワークフロー または ジョブレベルでGITHUB_TOKENの権限を制御できる。
permissions:
contents: read
issues: write
pull-requests: write
packages: write
deployments: write
権限には read, write, none のいずれかを指定できる。
最小権限の原則に従い、必要な権限のみを付与することを推奨する。
アーティファクト
アーティファクトの管理
アーティファクトは、ワークフロー実行中に生成されたファイルをGitHubサーバに保存する機能である。
ビルド成果物、テストレポート、ログファイル等を保存・共有する時に使用する。
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: ビルド
run: npm run build
- name: アーティファクトのアップロード
uses: actions/upload-artifact@v4
with:
name: build-output
path: ./dist
retention-days: 30
deploy:
runs-on: ubuntu-latest
needs: build
steps:
- name: アーティファクトのダウンロード
uses: actions/download-artifact@v4
with:
name: build-output
path: ./dist
下表に、アーティファクトに関連するパラメータを示す。
| 設定項目 | 説明 |
|---|---|
name |
アーティファクトの識別名を指定する。 |
path |
アップロードするファイルまたはディレクトリのパスを指定する。 |
retention-days |
アーティファクトの保持日数を指定する。 1から400の範囲で設定できる。 デフォルトは90日である。 |
ジョブ間のデータ共有
アーティファクトを使用することにより、異なるジョブ間でファイルを共有できる。
ステップ間での値の受け渡しには $GITHUB_OUTPUT を使用する。
jobs:
prepare:
runs-on: ubuntu-latest
outputs:
version: ${{ steps.get_version.outputs.version }}
steps:
- name: バージョン取得
id: get_version
run: echo "version=1.2.3" >> $GITHUB_OUTPUT
build:
runs-on: ubuntu-latest
needs: prepare
steps:
- name: バージョンの使用
run: echo "ビルドバージョン: ${{ needs.prepare.outputs.version }}"
キャッシュ
キャッシュの使用方法
actions/cache アクションを使用して、依存関係等のファイルをキャッシュすることでワークフローの実行時間を短縮できる。
steps:
- uses: actions/checkout@v4
- name: Node.jsのセットアップ
uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
# または、actions/cacheを直接使用する
- name: npmキャッシュの復元
uses: actions/cache@v4
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
- run: npm ci
下表に、キャッシュに関連するパラメータを示す。
| 設定項目 | 説明 |
|---|---|
path |
キャッシュするファイルまたはディレクトリのパスを指定する。 |
key |
キャッシュを識別するキーを指定する。 キーが一致した場合にキャッシュが復元される。 |
restore-keys |
key に一致するキャッシュが存在しない場合に、前方一致で検索するキーのリストを指定する。
|
hashFiles() 関数を使用することにより、ロックファイルの内容に基づいたハッシュ値をキャッシュキーに含められる。
ロックファイルが変更されると新しいキャッシュが作成される。
キャッシュのスコープと制限
キャッシュのスコープと制限に関する主な事項を以下に示す。
- スコープ
- キャッシュはブランチ間でアクセス制限がある。デフォルトブランチのキャッシュは全ブランチから参照できる。
- フォークされたリポジトリはベースリポジトリのキャッシュにアクセスできない。
- 容量制限
- リポジトリあたり10[GB]までキャッシュを保存できる。
- 制限を超えた場合、古いキャッシュが自動的に削除される。
- 有効期限
- 7日間アクセスされていないキャッシュは自動的に削除される。
デプロイメント
環境 (Environments)
環境 (Environments) 機能を使用することにより、デプロイ先の環境 (staging, production等) を定義して、環境固有のシークレットや保護ルールを設定できる。
- 環境の設定場所
- [リポジトリ]ページ - [Settings] - [Environments]
jobs:
deploy-staging:
runs-on: ubuntu-latest
environment:
name: staging
url: https://staging.example.com
steps:
- name: ステージングへのデプロイ
env:
DEPLOY_KEY: ${{ secrets.STAGING_DEPLOY_KEY }}
run: ./deploy.sh staging
deploy-production:
runs-on: ubuntu-latest
needs: deploy-staging
environment:
name: production
url: https://example.com
steps:
- name: 本番環境へのデプロイ
run: ./deploy.sh production
環境保護ルール
環境に対して保護ルールを設定することにより、デプロイのプロセスを制御できる。
主な保護ルールを以下に示す。
- 必須レビュアー (Required reviewers)
- 指定したユーザーまたはチームによる承認が必要となる。最大6名まで指定できる。
- 承認者がデプロイジョブの実行を承認するまでジョブは待機する。
- 待機時間 (Wait timer)
- ジョブが実行されるまでの待機時間を分単位で指定できる。
- 最大43,200分 (30日) まで設定できる。
- デプロイメントブランチ (Deployment branches)
- デプロイできるブランチを制限する。
- [All branches]、[Protected branches]、[Selected branches]から選択できる。
デプロイメントの例
mainブランチへのプッシュ時にステージングへデプロイして、手動承認後に本番環境へデプロイするワークフローの例を以下に示す。
name: デプロイメントワークフロー
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci && npm run build
- uses: actions/upload-artifact@v4
with:
name: build
path: dist/
deploy-staging:
runs-on: ubuntu-latest
needs: build
environment: staging
steps:
- uses: actions/download-artifact@v4
with:
name: build
- run: ./deploy.sh staging
deploy-production:
runs-on: ubuntu-latest
needs: deploy-staging
environment: production
steps:
- uses: actions/download-artifact@v4
with:
name: build
- run: ./deploy.sh production
ワークフロー構文の詳細
concurrency
concurrency を使用することにより、同一グループ内で同時に実行されるワークフローを制御できる。
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
| 設定項目 | 説明 |
|---|---|
group |
同時実行を制御するグループ名を指定する。 同じグループ名のワークフローは同時に1つしか実行されない。 |
cancel-in-progress |
true の場合、同じグループで既に実行中のワークフローをキャンセルして新しいワークフローを実行する。 |
出力 (outputs)
ステップ間またはジョブ間で値を受け渡す場合は、環境変数 $GITHUB_OUTPUT を使用する。
steps:
- name: 値の設定
id: my-step
run: |
echo "my-output=hello" >> $GITHUB_OUTPUT
echo "another-value=world" >> $GITHUB_OUTPUT
- name: 値の参照
run: echo "${{ steps.my-step.outputs.my-output }}"
なお、以前使用されていた set-output コマンドは非推奨であり、$GITHUB_OUTPUT の使用が推奨されている。
式と関数
GitHub Actionsの式は ${{ }} 構文で記述する。
下表に、主な組み込み関数を示す。
| 関数 | 説明 |
|---|---|
contains(search, item) |
search が item を含む場合に true を返す。
|
startsWith(searchString, searchValue) |
searchString が searchValue で始まる場合に true を返す。
|
endsWith(searchString, searchValue) |
searchString が searchValue で終わる場合に true を返す。
|
format(string, ...) |
文字列をフォーマットする。 |
join(array, separator) |
配列を区切り文字で結合した文字列を返す。 |
toJSON(value) |
値をJSON文字列に変換する。 |
fromJSON(value) |
JSON文字列をオブジェクトに変換する。 |
hashFiles(path) |
指定したパスのファイルのSHA-256ハッシュ値を返す。 |
再利用可能なワークフロー
workflow_call トリガーを使用することにより、他のワークフローから呼び出せる再利用可能なワークフローを作成できる。
再利用可能なワークフロー (.github/workflows/reusable.yml) の定義例を以下に示す。
# 再利用可能なワークフロー
on:
workflow_call:
inputs:
environment:
required: true
type: string
node-version:
required: false
type: string
default: "20"
secrets:
deploy-key:
required: true
outputs:
deploy-url:
description: "デプロイ先のURL"
value: ${{ jobs.deploy.outputs.url }}
jobs:
deploy:
runs-on: ubuntu-latest
outputs:
url: ${{ steps.deploy.outputs.url }}
steps:
- name: デプロイ
id: deploy
run: echo "url=https://example.com" >> $GITHUB_OUTPUT
再利用可能なワークフローを呼び出す例を以下に示す。
jobs:
call-reusable:
uses: owner/repo/.github/workflows/reusable.yml@main
with:
environment: production
node-version: "20"
secrets:
deploy-key: ${{ secrets.DEPLOY_KEY }}
再利用可能なワークフローに関する制限事項を以下に示す。
- ネストの深さは最大10レベルまでである。
- 同一ワークフロー実行内で最大20の再利用可能なワークフローを呼び出せる。
課金
無料枠
下表に、GitHub Actionsの各プランの無料枠を示す。
| プラン | 無料実行時間 | ストレージ |
|---|---|---|
| Free | 2,000分/月 | 500[MB] |
| Pro | 3,000分/月 | 1[GB] |
| Team | 3,000分/月 | 2[GB] |
| Enterprise | 50,000分/月 | 50[GB] |
パブリックリポジトリでのワークフロー実行は、全プランで無料である。
セルフホスト型ランナーの使用も無料である。(ランナーの維持費用は別途発生する)
超過時の課金
下表に、無料枠を超過した場合の分単位の料金を示す。
| ランナー | 分単価 | 倍率 |
|---|---|---|
| Linux | $0.008/分 | 1倍 |
| Windows | $0.016/分 | 2倍 |
| MacOS | $0.08/分 | 10倍 |
Windowsは無料枠の実行時間を2倍、MacOSは10倍として消費する。
例えば、MacOSで1分実行すると、無料枠から10分消費される。
