GitHub - Actions

提供: MochiuWiki : SUSE, EC, PCB

📢 Webサイト閉鎖と移転のお知らせ
このWebサイトは2026年9月に閉鎖いたします。
新しい記事は移転先で追加しております。（旧サイトでは記事を追加しておりません）

概要

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


マトリックスビルドに関連するキーを以下に示す。

strategyの設定項目一覧
設定項目 説明
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 に以下に示すラベルを指定する。

GitHubホスト型ランナーの主な種類とスペック
ラベル 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_name
github.ref
github.sha
github.repository
github.actor		 ワークフローのトリガーとなったイベントやリポジトリの情報
job job.status 現在のジョブの状態
runner runner.os
runner.arch		 ランナーのOS情報
steps steps.ステップID.outputs
steps.ステップ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


下表に、アーティファクトに関連するパラメータを示す。

actions/upload-artifactの設定項目一覧
設定項目 説明
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


下表に、キャッシュに関連するパラメータを示す。

actions/cacheの設定項目一覧
設定項目 説明
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


concurrencyの設定項目一覧
設定項目 説明
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分消費される。


「http://mochiuwiki.e2.valueserver.jp/index.php?title=GitHub_-_Actions&oldid=14578」から取得