Github Docs

GitHub Actions -- アーティファクト

ワークフロー内でのデータ保存・共有のリファレンス。

公式ドキュメント: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow

---

概要

アーティファクトを使用して、ビルド出力やテスト結果をワークフロー実行内のジョブ間で共有したり、ワークフロー完了後にダウンロード可能にしたりする。

---

アーティファクトのアップロード

actions/upload-artifact アクションを使用する。

基本的な使用方法

steps:
  - run: npm run build

  - uses: actions/upload-artifact@v4
    with:
      name: build-output
      path: dist/

全パラメータ

複数ファイル/ディレクトリ

- uses: actions/upload-artifact@v4
  with:
    name: test-results
    path: |
      coverage/
      test-reports/
      !test-reports/**/*.tmp

除外パターンは ! プレフィックスで指定する。

保持期間の指定

- uses: actions/upload-artifact@v4
  with:
    name: logs
    path: logs/
    retention-days: 5

---

アーティファクトのダウンロード

actions/download-artifact アクションを使用する。

特定のアーティファクト

steps:
  - uses: actions/download-artifact@v4
    with:
      name: build-output

  - run: ls build-output/

全アーティファクトの一括ダウンロード

name を省略すると全アーティファクトがダウンロードされる。各アーティファクトは個別のディレクトリに展開される。

steps:
  - uses: actions/download-artifact@v4
    # name を省略 -> 全アーティファクトをダウンロード

  - run: ls -R

ダウンロード先の指定

- uses: actions/download-artifact@v4
  with:
    name: build-output
    path: ./downloaded-artifacts

---

ジョブ間のデータ共有

アーティファクトを使って複数ジョブ間でデータを受け渡す。

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run build

      - uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: build-output
          path: dist/

      - run: ./deploy.sh dist/

• needs でジョブの依存関係を定義し、実行順序を保証する
• 依存ジョブはアーティファクトのアップロード完了を自動的に待機する

---

アーティファクトの整合性検証

upload-artifact アクションは digest という SHA256 ハッシュ値の出力を返す。ダウンロード時に自動的にチェックサムが検証され、不一致の場合は警告が表示される。

- uses: actions/upload-artifact@v4
  id: upload
  with:
    name: my-artifact
    path: output/

- run: echo "Digest is ${{ steps.upload.outputs.digest }}"

---

ワークフロー間でのアーティファクト共有

別のワークフロー実行のアーティファクトをダウンロードするには、run-id パラメータとトークン認証が必要。

- uses: actions/download-artifact@v4
  with:
    name: build-output
    github-token: ${{ secrets.GITHUB_TOKEN }}
    run-id: ${{ github.event.workflow_run.id }}

---

保持期間

• デフォルトの保持期間はリポジトリ/Organization の設定に依存（通常 90 日間）
• retention-days パラメータでアーティファクト単位に設定可能
• リポジトリ/Organization の設定上限を超える保持期間は設定できない
• 期間経過後、アーティファクトは自動的にスケジュール削除される

---

サイズ制限

---

v4 での重要な変更点

actions/upload-artifact@v4 および actions/download-artifact@v4 での主な変更:

• アーティファクトはイミュータブル（不変）: 同名のアーティファクトを再アップロードするとエラーになる（overwrite: true を明示的に設定しない限り）
• 各アーティファクトには一意の名前が必要
• パフォーマンスの大幅な改善

---

ベストプラクティス

1. アーティファクト名を明確にする: デフォルトの artifact ではなく、わかりやすい名前を付ける 2. 保持期間を適切に設定: 不要に長い保持期間はストレージを消費する 3. 不要なファイルを除外: 除外パターンでテンポラリファイル等を除く 4. ジョブ間共有の代わりにキャッシュを検討: 依存関係のような再利用可能なデータにはキャッシュの方が効率的 5. 機密情報を含めない: アーティファクトはワークフロー参加者がダウンロード可能

GitHub Actions -- キャッシュ

依存関係キャッシュによるワークフロー高速化のリファレンス。

公式ドキュメント: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows

---

概要

actions/cache を使用して依存関係やビルド出力をキャッシュし、ワークフローの実行時間を短縮する。

---

基本的な使用方法

steps:
  - uses: actions/checkout@v4

  - uses: actions/cache@v4
    with:
      path: ~/.npm
      key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-npm-

  - run: npm ci

---

入力パラメータ

---

出力パラメータ

- uses: actions/cache@v4
  id: cache-deps
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

- if: steps.cache-deps.outputs.cache-hit != 'true'
  run: npm ci

---

キャッシュキーの設計

動的キー（ハッシュベース）

依存関係ファイルのハッシュを使用して、変更時に自動的に新しいキャッシュを作成する。

key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}

restore-keys パターン

最も具体的なものから最も一般的なものの順に記載する:

restore-keys: |
  ${{ runner.os }}-npm-feature-${{ hashFiles('**/package-lock.json') }}
  ${{ runner.os }}-npm-feature-
  ${{ runner.os }}-npm-

---

キャッシュの動作

キャッシュヒット（完全一致）

提供された key に完全一致するキャッシュが見つかった場合:

• 指定された path にファイルが復元される
• cache-hit 出力が true になる

キャッシュミス

key に完全一致するキャッシュがない場合: 1. restore-keys を順番に検索し、プレフィックス一致するキャッシュを探す 2. 部分一致が見つかった場合、最新のキャッシュを復元する 3. ジョブが正常に完了した場合、新しいキャッシュが自動的に作成される

---

キャッシュスコープ（ブランチベース）

ワークフローは以下のブランチのキャッシュを復元できる:

• 現在のブランチ
• デフォルトブランチ（main）
• ベースブランチ（PR の場合）
• フォークリポジトリのベースブランチ

制限

• 子ブランチや兄弟ブランチのキャッシュにはアクセスできない
• 異なるタグ名のキャッシュにはアクセスできない
• マージ ref で作成された PR キャッシュは再実行時のみ復元可能

---

サイズ制限と退避ポリシー

退避ポリシー

ストレージ制限に達した場合、最終アクセス日が古い順にキャッシュが削除される。

---

言語別のキャッシュ例

Node.js (npm)

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

Node.js (yarn)

- uses: actions/cache@v4
  with:
    path: |
      ~/.cache/yarn
      node_modules
    key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}

Python (pip)

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}

Ruby (Bundler)

- uses: actions/cache@v4
  with:
    path: vendor/bundle
    key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}

Go

- uses: actions/cache@v4
  with:
    path: |
      ~/go/pkg/mod
      ~/.cache/go-build
    key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}

---

setup-* アクションによる簡易キャッシュ

多くの setup-* アクションには組み込みのキャッシュ機能がある:

# Node.js
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # npm, yarn, pnpm に対応

# Python
- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    cache: 'pip'

# Go
- uses: actions/setup-go@v5
  with:
    go-version: '1.22'
    cache: true

---

ベストプラクティス

1. 機密情報を含めない: キャッシュパスにアクセストークンやログイン情報を保存しない 2. ハッシュベースのキーを使用: 依存関係ファイルのハッシュでキーを構成し、変更時に自動更新 3. restore-keys を活用: 部分一致によるフォールバックで、完全に新しいキャッシュの構築を回避 4. cache-hit を利用: キャッシュヒット時にインストールステップをスキップして時間を節約 5. *setup- アクションを優先*: 言語固有の `setup-` アクションの組み込みキャッシュが最も簡単 6. キャッシュ使用量を監視: ストレージ制限に近づいたら不要なキャッシュを削除

GitHub Actions -- 複合アクション

複合アクション（Composite Actions）のリファレンス。

公式ドキュメント: https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action

---

概要

複合アクションは、複数のワークフローステップを 1 つのアクションにまとめる仕組み。run コマンドと uses アクションを組み合わせて使用できる。

---

action.yml の構造

name: 'Setup and Build'
description: 'Install dependencies and build the project'
author: 'Your Name'

inputs:
  node-version:
    description: 'Node.js version to use'
    required: false
    default: '20'
  working-directory:
    description: 'Working directory for the build'
    required: false
    default: '.'

outputs:
  build-version:
    description: 'The version that was built'
    value: ${{ steps.version.outputs.version }}

runs:
  using: 'composite'
  steps:
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}

    - name: Install dependencies
      run: npm ci
      shell: bash
      working-directory: ${{ inputs.working-directory }}

    - name: Build
      run: npm run build
      shell: bash
      working-directory: ${{ inputs.working-directory }}

    - name: Get version
      id: version
      run: echo "version=$(node -p 'require(\"./package.json\").version')" >> $GITHUB_OUTPUT
      shell: bash
      working-directory: ${{ inputs.working-directory }}

---

必須要素

runs.using: "composite"

複合アクションであることを宣言する必須キー。

runs.steps

実行するステップの配列。各ステップは以下のキーをサポートする:

重要: run ステップでは shell の指定が必須。複合アクション内では defaults.run.shell が適用されない。

---

入力（inputs）

inputs:
  environment:
    description: 'Target deployment environment'
    required: true
  debug:
    description: 'Enable debug mode'
    required: false
    default: 'false'

入力へのアクセス方法

• 式内: ${{ inputs.environment }}
• 環境変数: INPUT_ENVIRONMENT（大文字、スペースはアンダースコアに変換）

steps:
  - run: echo "Deploying to ${{ inputs.environment }}"
    shell: bash

  - run: echo "Environment is $INPUT_ENVIRONMENT"
    shell: bash

---

出力（outputs）

ステップの出力をアクションの出力にマッピングする。

outputs:
  result:
    description: 'The action result'
    value: ${{ steps.compute.outputs.result }}

runs:
  using: 'composite'
  steps:
    - id: compute
      run: echo "result=success" >> $GITHUB_OUTPUT
      shell: bash

value キーは複合アクションでは必須。ステップの $GITHUB_OUTPUT に書き込まれた値を参照する。

---

呼び出し方法

別リポジトリのアクション

steps:
  - uses: owner/repo-name@v1
    with:
      environment: production

同一リポジトリのアクション

steps:
  - uses: actions/checkout@v4
  - uses: ./.github/actions/my-composite-action
    with:
      environment: production

ローカルアクションを使用するには、先に actions/checkout でリポジトリをチェックアウトする必要がある。

---

ディレクトリ構造

.github/actions/my-action/
  action.yml     # アクションメタデータ
  scripts/       # オプション: 補助スクリプト
    helper.sh

または独立したリポジトリとして:

my-action/
  action.yml
  scripts/
    helper.sh
  README.md

---

実践的な例

テストとリント

name: 'Lint and Test'
description: 'Run linting and tests'

inputs:
  node-version:
    description: 'Node.js version'
    default: '20'

outputs:
  coverage:
    description: 'Test coverage percentage'
    value: ${{ steps.test.outputs.coverage }}

runs:
  using: 'composite'
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        cache: 'npm'

    - run: npm ci
      shell: bash

    - run: npm run lint
      shell: bash

    - id: test
      run: |
        COVERAGE=$(npm test -- --coverage 2>&1 | grep 'All files' | awk '{print $4}')
        echo "coverage=$COVERAGE" >> $GITHUB_OUTPUT
      shell: bash

条件付きステップ

runs:
  using: 'composite'
  steps:
    - if: inputs.debug == 'true'
      run: echo "Debug mode enabled"
      shell: bash

    - run: ./build.sh
      shell: bash
      continue-on-error: ${{ inputs.allow-failure == 'true' }}

---

再利用可能ワークフローとの違い

---

セキュリティ上の注意

• 入力値に信頼できないデータが含まれる可能性がある場合、インジェクション攻撃に注意する
• 外部入力を直接シェルコマンドに埋め込まない

# NG: インジェクションの危険
- run: echo "${{ inputs.user-input }}"
  shell: bash

# OK: 環境変数経由
- run: echo "$USER_INPUT"
  shell: bash
  env:
    USER_INPUT: ${{ inputs.user-input }}

GitHub Actions -- コンテキスト

ワークフロー実行に関するコンテキスト情報のリファレンス。

公式ドキュメント: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs

---

アクセス構文

コンテキストには 2 つの構文でアクセスできる:

# プロパティ参照構文
${{ github.sha }}

# インデックス構文
${{ github['sha'] }}

プロパティ参照構文は、プロパティ名が英字または _ で始まり、英数字・-・_ のみを含む場合に使用できる。

---

github コンテキスト

ワークフロー実行とトリガーイベントの情報。

---

env コンテキスト

ワークフロー・ジョブ・ステップレベルで設定された環境変数。

env:
  MY_VAR: hello
jobs:
  example:
    steps:
      - if: env.MY_VAR == 'hello'
        run: echo ${{ env.MY_VAR }}

---

vars コンテキスト

Organization、リポジトリ、または環境レベルで設定されたカスタム設定変数。

steps:
  - run: echo ${{ vars.MY_CONFIG_VAR }}

---

job コンテキスト

現在実行中のジョブに関する情報。

---

jobs コンテキスト

再利用可能ワークフローでのみ利用可能。出力の設定に使用する。

---

steps コンテキスト

現在のジョブで id が設定されたステップの情報。

conclusion と outcome の値: success, failure, cancelled, skipped

steps:
  - id: my-step
    run: echo "result=value" >> $GITHUB_OUTPUT
  - run: echo ${{ steps.my-step.outputs.result }}
  - if: steps.my-step.conclusion == 'success'
    run: echo "Step succeeded"

---

runner コンテキスト

ジョブを実行しているランナーの詳細。

---

secrets コンテキスト

ワークフローで利用可能なシークレットの名前と値。

steps:
  - run: echo "token length: ${#TOKEN}"
    env:
      TOKEN: ${{ secrets.GITHUB_TOKEN }}

注意: シークレットは if: 条件で直接参照できない。環境変数経由で使用する。

---

strategy コンテキスト

マトリクス実行戦略の情報。

---

matrix コンテキスト

ワークフローで定義されたマトリクスプロパティ。

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [18, 20]
steps:
  - run: echo "OS=${{ matrix.os }}, Node=${{ matrix.node }}"

---

needs コンテキスト

現在のジョブが依存する全ジョブの出力。

jobs:
  build:
    outputs:
      version: ${{ steps.ver.outputs.version }}
    steps:
      - id: ver
        run: echo "version=1.0" >> $GITHUB_OUTPUT
  deploy:
    needs: build
    steps:
      - run: echo "Deploying version ${{ needs.build.outputs.version }}"

---

inputs コンテキスト

再利用可能ワークフローまたは手動トリガーワークフローの入力プロパティ。

on:
  workflow_dispatch:
    inputs:
      environment:
        type: string
        required: true
jobs:
  deploy:
    steps:
      - run: echo "Deploying to ${{ inputs.environment }}"

GitHub Actions -- action.yml メタデータ構文

カスタムアクションの action.yml メタデータファイルの構文リファレンス。

公式ドキュメント: https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions

---

トップレベルキー

---

inputs

アクションが受け取る入力パラメータを定義する。

inputs:
  node-version:
    description: 'Node.js version to use'
    required: true
  cache:
    description: 'Enable caching'
    required: false
    default: 'true'
  old-param:
    description: 'Deprecated parameter'
    deprecationMessage: 'Use new-param instead'

入力のプロパティ

入力 ID のルール

• 英数字、-（ハイフン）、_（アンダースコア）が使用可能
• 英字または _ で始まる必要がある
• 大文字小文字を区別しない

環境変数としてのアクセス

入力は INPUT_<NAME> 環境変数として自動的に設定される:

• 大文字に変換される
• スペースは _ に変換される
• 例: who-to-greet → INPUT_WHO-TO-GREET

---

outputs

アクションが提供する出力パラメータを定義する。

Docker / JavaScript アクション

outputs:
  version:
    description: 'The detected version'
  status:
    description: 'Build status'

複合アクション

複合アクションでは追加で value キーが必須。

outputs:
  version:
    description: 'The detected version'
    value: ${{ steps.detect.outputs.version }}

出力の制限

---

runs

アクションの実行方法を定義する。3 つのタイプがある。

JavaScript アクション

runs:
  using: 'node20'
  main: 'dist/index.js'
  pre: 'dist/setup.js'
  pre-if: runner.os == 'Linux'
  post: 'dist/cleanup.js'
  post-if: always()

Docker コンテナアクション

runs:
  using: 'docker'
  image: 'Dockerfile'
  entrypoint: '/entrypoint.sh'
  args:
    - ${{ inputs.who-to-greet }}
  env:
    CUSTOM_VAR: 'value'
  pre-entrypoint: 'setup.sh'
  post-entrypoint: 'cleanup.sh'

image の形式

# ローカル Dockerfile
image: 'Dockerfile'

# Docker Hub
image: 'docker://alpine:3.18'

# GitHub Container Registry
image: 'docker://ghcr.io/owner/image:tag'

複合アクション

runs:
  using: 'composite'
  steps:
    - name: Setup
      uses: actions/setup-node@v4
      with:
        node-version: '20'

    - name: Build
      run: npm run build
      shell: bash
      working-directory: ./src

    - name: Test
      run: npm test
      shell: bash
      if: inputs.skip-tests != 'true'
      continue-on-error: true
      env:
        CI: true

ステップで使用可能なキー

---

branding

GitHub Marketplace でアクションを視覚的に識別するためのブランディング設定。

branding:
  icon: 'package'
  color: 'blue'

icon

Feather アイコン（v4.28.0）の名前を指定する。

使用可能なアイコン例: activity, airplay, alert-circle, alert-triangle, anchor, archive, arrow-*, at-sign, award, bar-chart, bell, bluetooth, bold, book, bookmark, box, briefcase, calendar, camera, cast, check-*, chevron-*, chrome, circle, clipboard, clock, cloud, code, command, compass, copy, cpu, credit-card, crop, crosshair, database, delete, disc, download, droplet, edit, external-link, eye, fast-forward, feather, file, film, filter, flag, folder, gift, git-*, globe, grid, hard-drive, hash, headphones, heart, help-circle, home, image, inbox, info, italic, layers, layout, life-buoy, link, list, lock, log-*, mail, map, maximize, menu, message-*, mic, minimize, minus, monitor, moon, more-*, move, music, navigation, octagon, package, paperclip, pause, pen-tool, percent, phone, pie-chart, play, plus, pocket, power, printer, radio, refresh-*, repeat, rewind, rotate-*, rss, save, scissors, search, send, server, settings, share, shield, shopping-*, shuffle, sidebar, skip-*, slash, sliders, smartphone, speaker, square, star, stop-circle, sun, sunrise, sunset, tablet, tag, target, terminal, thermometer, thumbs-*, toggle-*, trash, trending-*, triangle, truck, tv, type, umbrella, underline, unlock, upload, user, users, video, voicemail, volume, watch, wifi, wind, x, x-circle, x-square, zap, zoom-*

使用不可のアイコン: coffee, columns, divide-circle, divide-square, divide, frown, hexagon, key, meh, mouse-pointer, smile, tool, x-octagon

color

使用可能な色: white, black, yellow, blue, green, orange, red, purple, gray-dark

---

完全な例

JavaScript アクション

name: 'Setup and Cache Dependencies'
description: 'Install Node.js and cache npm dependencies'
author: 'Your Name'

branding:
  icon: 'package'
  color: 'green'

inputs:
  node-version:
    description: 'Node.js version'
    required: false
    default: '20'
  working-directory:
    description: 'Working directory'
    required: false
    default: '.'

outputs:
  cache-hit:
    description: 'Whether cache was hit'

runs:
  using: 'node20'
  main: 'dist/index.js'
  post: 'dist/cleanup.js'
  post-if: success()

Docker アクション

name: 'Custom Linter'
description: 'Run custom linting on the codebase'
author: 'Your Name'

branding:
  icon: 'check-circle'
  color: 'blue'

inputs:
  config-path:
    description: 'Path to linter config'
    required: false
    default: '.lintrc.yml'

outputs:
  issues-found:
    description: 'Number of issues found'

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - '--config'
    - ${{ inputs.config-path }}

複合アクション

name: 'Build and Test'
description: 'Build the project and run tests'
author: 'Your Name'

inputs:
  node-version:
    description: 'Node.js version'
    required: false
    default: '20'

outputs:
  test-result:
    description: 'Test execution result'
    value: ${{ steps.test.outputs.result }}

runs:
  using: 'composite'
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        cache: 'npm'

    - run: npm ci
      shell: bash

    - run: npm run build
      shell: bash

    - id: test
      run: |
        npm test && echo "result=pass" >> $GITHUB_OUTPUT || echo "result=fail" >> $GITHUB_OUTPUT
      shell: bash

GitHub Actions -- Docker コンテナアクション

Docker コンテナアクションの作成方法のリファレンス。

公式ドキュメント: https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-docker-container-action

---

概要

Docker コンテナアクションは、Docker コンテナ内でコードを実行する。任意の言語やツールを使用でき、一貫した環境を保証する。Linux ランナーでのみ動作する。

---

必要なファイル

1. action.yml

name: 'Hello World Docker Action'
description: 'Greet someone and record the time'
author: 'Your Name'

inputs:
  who-to-greet:
    description: 'Who to greet'
    required: true
    default: 'World'

outputs:
  time:
    description: 'The time we greeted you'

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.who-to-greet }}

runs セクションのキー

image の指定方法

# ローカル Dockerfile からビルド
image: 'Dockerfile'

# Docker Hub のイメージを直接使用
image: 'docker://alpine:3.18'

# GitHub Container Registry のイメージ
image: 'docker://ghcr.io/owner/image:tag'

---

2. Dockerfile

# ベースイメージ
FROM alpine:3.18

# 必要なパッケージのインストール
RUN apk add --no-cache bash curl jq

# エントリポイントスクリプトのコピー
COPY entrypoint.sh /entrypoint.sh

# 実行権限の付与
RUN chmod +x /entrypoint.sh

# エントリポイントの設定
ENTRYPOINT ["/entrypoint.sh"]

---

3. エントリポイントスクリプト

#!/bin/sh -l

# 入力はコマンドライン引数として渡される（args で指定した順）
echo "Hello $1"

# 現在時刻を取得
time=$(date)

# 出力の設定（GITHUB_OUTPUT ファイルに書き込む）
echo "time=$time" >> $GITHUB_OUTPUT

重要: エントリポイントスクリプトには実行権限が必要。

git add entrypoint.sh
git update-index --chmod=+x entrypoint.sh

---

入力の受け渡し

args 経由（コマンドライン引数）

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.who-to-greet }}
    - ${{ inputs.greeting-style }}

エントリポイント内では $1, $2, ... で参照する。

環境変数経由

入力は自動的に INPUT_<NAME> 環境変数としてもコンテナ内で利用可能。名前は大文字に変換され、スペースはアンダースコアになる。

#!/bin/sh -l
# INPUT_WHO-TO-GREET 環境変数として自動的に設定される
echo "Hello $INPUT_WHO_TO_GREET"

env キーで明示的に指定

runs:
  using: 'docker'
  image: 'Dockerfile'
  env:
    CUSTOM_VAR: 'value'
    API_KEY: ${{ inputs.api-key }}

---

出力の設定

$GITHUB_OUTPUT ファイルに key=value 形式で書き込む。

#!/bin/sh -l
echo "result=success" >> $GITHUB_OUTPUT
echo "version=1.0.0" >> $GITHUB_OUTPUT

複数行の出力:

#!/bin/sh -l
{
  echo 'json_data<<EOF'
  echo '{"key": "value"}'
  echo EOF
} >> $GITHUB_OUTPUT

---

ファイルシステムのマウント

---

実行ランナーの要件

Windows や macOS のランナーでは Docker コンテナアクションは使用できない。

---

リリースとバージョニング

git add action.yml Dockerfile entrypoint.sh
git commit -m "My Docker action"
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin main --follow-tags

---

ワークフローでの使用例

パブリックアクション

jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
      - uses: owner/hello-world-docker-action@v1
        with:
          who-to-greet: 'Mona the Octocat'

プライベート/ローカルアクション

jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ./
        with:
          who-to-greet: 'Mona the Octocat'

ローカルアクションは先に actions/checkout でリポジトリをチェックアウトする必要がある。

---

Docker Hub イメージを直接使用

Dockerfile を使わずに既存の Docker イメージを直接使用することもできる。

runs:
  using: 'docker'
  image: 'docker://alpine:3.18'
  entrypoint: '/bin/sh'
  args:
    - '-c'
    - 'echo Hello $INPUT_WHO_TO_GREET'

---

ベストプラクティス

1. 軽量なベースイメージを使用: alpine 等の軽量イメージで起動時間を短縮 2. マルチステージビルド: ビルドツールとランタイムを分離してイメージサイズを削減 3. 固定バージョンのベースイメージ: alpine:3.18 のようにバージョンを固定して再現性を確保 4. 実行権限の確認: エントリポイントスクリプトに chmod +x を忘れない 5. ENTRYPOINT vs CMD: アクションでは ENTRYPOINT を使用する（CMD は args で上書きされる）

GitHub Actions -- JavaScript アクション

JavaScript アクションの作成方法のリファレンス。

公式ドキュメント: https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-javascript-action

---

概要

JavaScript アクションは Node.js ランタイムで実行され、Linux、Windows、macOS の全ランナーで動作する。@actions/core や @actions/github などの公式ツールキットを使用して GitHub API と対話する。

---

プロジェクトセットアップ

mkdir my-action && cd my-action
npm init -y
npm install @actions/core @actions/github

---

action.yml メタデータ

name: 'My JavaScript Action'
description: 'Description of what this action does'
author: 'Your Name'

inputs:
  who-to-greet:
    description: 'Who to greet'
    required: true
    default: 'World'

outputs:
  time:
    description: 'The time we greeted you'

runs:
  using: 'node20'
  main: 'dist/index.js'

runs セクションのキー

---

@actions/core パッケージ

ワークフローコマンド、入出力変数、終了ステータス、デバッグメッセージへのインターフェース。

主要関数

import * as core from '@actions/core';

// 入力の取得
const name = core.getInput('who-to-greet');            // 必須入力
const debug = core.getInput('debug', { required: false }); // オプション入力
const list = core.getMultilineInput('items');           // 複数行入力

// 出力の設定
core.setOutput('time', new Date().toTimeString());

// ログ出力
core.debug('Debug message');      // デバッグ（ACTIONS_STEP_DEBUG=true 時のみ表示）
core.info('Info message');        // 情報
core.notice('Notice message');    // 通知（アノテーション）
core.warning('Warning message');  // 警告（アノテーション）
core.error('Error message');      // エラー（アノテーション）

// ログのグループ化
core.startGroup('Group name');
core.info('Grouped message');
core.endGroup();

// 環境変数の設定
core.exportVariable('MY_VAR', 'value');

// PATH への追加
core.addPath('/custom/path');

// シークレットのマスキング
core.setSecret('sensitive-value');

// 失敗の設定
core.setFailed('Action failed with error');

// 状態の保存（pre/post スクリプト間で共有）
core.saveState('key', 'value');
const state = core.getState('key');

---

@actions/github パッケージ

認証済み Octokit REST クライアントと GitHub Actions コンテキストへのアクセスを提供する。

import * as github from '@actions/github';

// コンテキストへのアクセス
const { context } = github;
console.log(context.repo);         // { owner: '...', repo: '...' }
console.log(context.sha);          // コミット SHA
console.log(context.ref);          // ref
console.log(context.actor);        // アクター
console.log(context.workflow);     // ワークフロー名
console.log(context.payload);      // webhook ペイロード
console.log(context.eventName);    // イベント名

// 認証済み Octokit クライアント
const octokit = github.getOctokit(core.getInput('github-token'));

// API 呼び出し例: Issue へのコメント
await octokit.rest.issues.createComment({
  ...context.repo,
  issue_number: context.issue.number,
  body: 'Hello from my action!',
});

// API 呼び出し例: PR のファイル一覧
const { data: files } = await octokit.rest.pulls.listFiles({
  ...context.repo,
  pull_number: context.payload.pull_request.number,
});

---

アクションコードの例

// src/index.js
import * as core from '@actions/core';
import * as github from '@actions/github';

try {
  // 入力の取得
  const nameToGreet = core.getInput('who-to-greet');
  core.info(`Hello ${nameToGreet}!`);

  // 出力の設定
  const time = new Date().toTimeString();
  core.setOutput('time', time);

  // webhook ペイロードの取得
  const payload = JSON.stringify(github.context.payload, undefined, 2);
  core.debug(`The event payload: ${payload}`);
} catch (error) {
  core.setFailed(error.message);
}

---

ビルドとバンドル

node_modules をコミットする代わりに、バンドラーを使用してアクションコードと依存関係を 1 つのファイルにまとめる。

Rollup を使用

npm install --save-dev rollup @rollup/plugin-commonjs @rollup/plugin-node-resolve

// rollup.config.js
import commonjs from '@rollup/plugin-commonjs';
import { nodeResolve } from '@rollup/plugin-node-resolve';

export default {
  input: 'src/index.js',
  output: {
    esModule: true,
    file: 'dist/index.js',
    format: 'es',
    sourcemap: true,
  },
  plugins: [commonjs(), nodeResolve({ preferBuiltins: true })],
};

npx rollup --config rollup.config.js

ncc を使用（代替）

npm install --save-dev @vercel/ncc
npx ncc build src/index.js -o dist

---

プロジェクト構造

my-action/
  action.yml
  src/
    index.js
  dist/
    index.js       # バンドル済み（コミットする）
  package.json
  package-lock.json
  rollup.config.js
  README.md

---

リリースとバージョニング

git add action.yml dist/ package.json package-lock.json
git commit -m "Initial release"
git tag -a v1.0.0 -m "Release v1.0.0"
git tag -fa v1 -m "Update v1 tag"   # メジャーバージョンタグを更新
git push origin main --follow-tags
git push origin v1 --force           # メジャーバージョンタグを強制更新

ユーザーは以下のように参照する:

• uses: owner/my-action@v1 -- メジャーバージョン（推奨）
• uses: owner/my-action@v1.0.0 -- 正確なバージョン
• uses: owner/my-action@abc123 -- コミット SHA（最も安全）

---

pre/post スクリプト

セットアップとクリーンアップの処理を分離できる。

runs:
  using: 'node20'
  pre: 'dist/setup.js'
  pre-if: runner.os == 'Linux'
  main: 'dist/index.js'
  post: 'dist/cleanup.js'
  post-if: always()

pre と post スクリプト間で状態を共有するには core.saveState() と core.getState() を使用する。

GitHub Actions -- カスタムアクション作成

カスタムアクション作成に関するガイドの目次。

複合アクションについては composite-actions.md を参照。

---

アクションの種類

---

配布方法

パブリックリポジトリ

独立したリポジトリで公開し、セマンティックバージョニングのタグで管理する。

# ユーザーがこのように参照
uses: owner/action-name@v1
uses: owner/action-name@v1.2.3
uses: owner/action-name@abc123  # コミット SHA

同一リポジトリ内

.github/actions/ ディレクトリに配置する。

# 同一リポジトリから参照
uses: ./.github/actions/my-action

GitHub Marketplace

パブリックリポジトリのアクションは GitHub Marketplace に公開可能。

GitHub Actions -- 環境変数

デフォルト環境変数とカスタム環境変数のリファレンス。

公式ドキュメント: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables

---

デフォルト環境変数

GitHub が全ワークフロー実行に自動的に設定する環境変数。

---

カスタム環境変数の設定

ワークフローレベル

全ジョブの全ステップで利用可能。

env:
  NODE_ENV: production
  API_URL: https://api.example.com

jobs:
  build:
    steps:
      - run: echo $NODE_ENV  # production

ジョブレベル

特定ジョブの全ステップで利用可能。ワークフローレベルの同名変数を上書きする。

jobs:
  build:
    env:
      BUILD_TYPE: release
    steps:
      - run: echo $BUILD_TYPE  # release

ステップレベル

特定ステップでのみ利用可能。ジョブ/ワークフローレベルの同名変数を上書きする。

steps:
  - run: echo $MY_VAR
    env:
      MY_VAR: step-specific-value

---

環境変数のアクセス方法

シェルコマンド内（run ステップ）

# Bash / Linux / macOS
- run: echo $MY_VAR

# PowerShell / Windows
- run: echo $env:MY_VAR
  shell: pwsh

# cmd.exe / Windows
- run: echo %MY_VAR%
  shell: cmd

コンテキスト経由（run ステップ外）

# if 条件やアクション入力で使用
- if: env.MY_VAR == 'expected'
  uses: some/action@v1
  with:
    input: ${{ env.MY_VAR }}

---

GITHUB_ENV ファイル（ステップ間の変数共有）

GITHUB_ENV ファイルに書き込むことで、後続のステップで利用可能な環境変数を設定する。

steps:
  # 変数を設定
  - run: echo "MY_VAR=hello" >> $GITHUB_ENV

  # 後続ステップで利用
  - run: echo $MY_VAR  # hello

複数行の値

デリミタ構文を使用する:

steps:
  - run: |
      {
        echo 'JSON_RESPONSE<<EOF'
        curl https://api.example.com/data
        echo EOF
      } >> $GITHUB_ENV

---

GITHUB_OUTPUT ファイル（ステップ出力）

GITHUB_OUTPUT ファイルに書き込むことで、他のステップやジョブから参照可能な出力を設定する。

steps:
  # 出力を設定
  - id: build
    run: echo "version=1.0.0" >> $GITHUB_OUTPUT

  # 同じジョブの後続ステップで参照
  - run: echo "Version is ${{ steps.build.outputs.version }}"

複数行の出力

steps:
  - id: generate
    run: |
      {
        echo 'result<<EOF'
        echo 'line 1'
        echo 'line 2'
        echo EOF
      } >> $GITHUB_OUTPUT

ジョブ間での出力共有

jobs:
  build:
    outputs:
      version: ${{ steps.ver.outputs.version }}
    steps:
      - id: ver
        run: echo "version=1.0.0" >> $GITHUB_OUTPUT

  deploy:
    needs: build
    steps:
      - run: echo "Deploying ${{ needs.build.outputs.version }}"

---

GITHUB_STEP_SUMMARY（ジョブサマリー）

GITHUB_STEP_SUMMARY ファイルに Markdown を書き込むことで、ワークフロー実行のサマリーページにカスタムコンテンツを表示する。

steps:
  - run: |
      echo "## Build Results" >> $GITHUB_STEP_SUMMARY
      echo "| Test | Result |" >> $GITHUB_STEP_SUMMARY
      echo "|------|--------|" >> $GITHUB_STEP_SUMMARY
      echo "| Unit | Pass |" >> $GITHUB_STEP_SUMMARY

---

GITHUB_PATH（PATH への追加）

GITHUB_PATH ファイルに書き込むことで、後続のステップのシステム PATH にディレクトリを追加する。

steps:
  - run: echo "$HOME/.local/bin" >> $GITHUB_PATH
  - run: my-custom-tool  # PATH に追加されたので直接実行可能

---

設定変数（vars コンテキスト）

リポジトリ、環境、Organization レベルで設定可能なカスタム設定変数。シークレットと異なり暗号化されない。

steps:
  - run: echo ${{ vars.DEPLOY_TARGET }}
  - if: vars.FEATURE_FLAG == 'true'
    run: echo "Feature enabled"

スコープの優先順位: 環境 > リポジトリ > Organization

GitHub Actions -- イベントとトリガー

ワークフローをトリガーする全イベントのリファレンス。

公式ドキュメント: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows

---

イベント設定構文

on:
  # 単一イベント
  push:

  # アクティビティタイプ指定
  issues:
    types: [opened, labeled]

  # ブランチ/パスフィルタ
  push:
    branches: [main, 'release/**']
    paths: ['src/**']

  # 複数イベント
  pull_request:
    branches: [main]
    types: [opened, synchronize]

---

フィルタパターン

ブランチ/タグフィルタ

on:
  push:
    branches:
      - main
      - 'release/**'
      - '!release/**-alpha'   # 除外パターン
    branches-ignore:
      - 'feature/**'
    tags:
      - 'v*'
    tags-ignore:
      - 'v*-rc*'

• branches と branches-ignore は同時に使用できない（! プレフィックスで除外を表現）
• tags と tags-ignore は同時に使用できない
• グロブパターン: *（単一レベル）, **（複数レベル）, ?, +, !

パスフィルタ

on:
  push:
    paths:
      - 'src/**'
      - '**.js'
    paths-ignore:
      - 'docs/**'
      - '**.md'

• paths と paths-ignore は同時に使用できない

---

全イベント一覧

branch_protection_rule

ブランチ保護ルールの変更時にトリガー。

• アクティビティタイプ: created, edited, deleted
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ
• ワークフローファイルはデフォルトブランチに必要

check_run

チェック実行のイベント。

• アクティビティタイプ: created, rerequested, completed, requested_action
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ
• GitHub Actions 自身からの再帰的トリガーを防止

check_suite

チェックスイートのイベント。

• アクティビティタイプ: completed
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ

create

ブランチまたはタグの作成時。

• アクティビティタイプ: なし
• GITHUB_SHA: 作成されたブランチ/タグの最新コミット
• GITHUB_REF: 作成されたブランチ/タグ
• 3つ以上のタグが同時に作成された場合はイベントが発生しない

delete

ブランチまたはタグの削除時。

• アクティビティタイプ: なし
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ

deployment

デプロイメントの作成時。

• アクティビティタイプ: なし
• GITHUB_SHA: デプロイ対象のコミット
• GITHUB_REF: デプロイ対象のブランチ/タグ

deployment_status

デプロイメントのステータス変更時。

• アクティビティタイプ: なし
• GITHUB_SHA: デプロイ対象のコミット
• GITHUB_REF: デプロイ対象のブランチ/タグ
• ステータスが inactive の場合はトリガーしない

discussion

ディスカッションのイベント。

• アクティビティタイプ: created, edited, deleted, transferred, pinned, unpinned, labeled, unlabeled, locked, unlocked, category_changed, answered, unanswered
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ

discussion_comment

ディスカッションコメントのイベント。

• アクティビティタイプ: created, edited, deleted
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ

fork

リポジトリのフォーク時。

• アクティビティタイプ: なし
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ

gollum

Wiki ページの作成または更新時。

• アクティビティタイプ: なし
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ

issue_comment

Issue またはプルリクエストのコメントイベント。

• アクティビティタイプ: created, edited, deleted
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ
• Issue と PR の両方でトリガーされる。区別には github.event.issue.pull_request を使用

issues

Issue のイベント。

• アクティビティタイプ: opened, edited, deleted, transferred, pinned, unpinned, closed, reopened, assigned, unassigned, labeled, unlabeled, locked, unlocked, milestoned, demilestoned, typed, untyped
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ

label

ラベルのイベント。

• アクティビティタイプ: created, edited, deleted
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ

merge_group

マージキューのチェック要求時。

• アクティビティタイプ: checks_requested
• GITHUB_SHA: マージグループの SHA
• GITHUB_REF: マージグループの ref

milestone

マイルストーンのイベント。

• アクティビティタイプ: created, closed, opened, edited, deleted
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ

page_build

GitHub Pages のビルド時。

• アクティビティタイプ: なし
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ

public

リポジトリがプライベートからパブリックに変更された時。

• アクティビティタイプ: なし
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ

pull_request

プルリクエストのイベント。

• アクティビティタイプ: assigned, unassigned, labeled, unlabeled, opened, edited, closed, reopened, synchronize, converted_to_draft, locked, unlocked, enqueued, dequeued, milestoned, demilestoned, ready_for_review, review_requested, review_request_removed, auto_merge_enabled, auto_merge_disabled
• デフォルトタイプ: opened, synchronize, reopened
• GITHUB_SHA: GITHUB_REF ブランチの最新マージコミット
• GITHUB_REF: refs/pull/NUMBER/merge
• フィルタ: branches, branches-ignore, paths, paths-ignore

on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]
    paths:
      - 'src/**'

注意事項:

• マージコンフリクトがある場合は実行されない
• フォークからの PR では GITHUB_TOKEN は読み取り専用
• HEAD コミット SHA は github.event.pull_request.head.sha で取得

pull_request_review

PR レビューのイベント。

• アクティビティタイプ: submitted, edited, dismissed
• GITHUB_SHA: GITHUB_REF ブランチの最新マージコミット
• GITHUB_REF: refs/pull/NUMBER/merge
• 承認状態は github.event.review.state で確認

pull_request_review_comment

PR の diff コメントのイベント。

• アクティビティタイプ: created, edited, deleted
• GITHUB_SHA: GITHUB_REF ブランチの最新マージコミット
• GITHUB_REF: refs/pull/NUMBER/merge

pull_request_target

PR イベント（ベースブランチのコンテキストで実行）。

• アクティビティタイプ: pull_request と同じ
• デフォルトタイプ: opened, synchronize, reopened
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ
• フィルタ: branches, branches-ignore, paths, paths-ignore
• セキュリティ注意: デフォルトブランチのコンテキストで実行されるため、信頼できないコードの実行に注意

push

コミットのプッシュ時。

• アクティビティタイプ: なし
• GITHUB_SHA: プッシュされた先端コミット
• GITHUB_REF: 更新された ref
• フィルタ: branches, branches-ignore, tags, tags-ignore, paths, paths-ignore

on:
  push:
    branches: [main, 'release/**']
    tags: ['v*']
    paths-ignore:
      - '**.md'

注意: 5,000 以上のブランチが同時にプッシュされた場合はイベントが発生しない

registry_package

パッケージの公開/更新時。

• アクティビティタイプ: published, updated
• GITHUB_SHA: 公開されたパッケージのコミット
• GITHUB_REF: パッケージのブランチ/タグ

release

リリースのイベント。

• アクティビティタイプ: published, unpublished, created, edited, deleted, prereleased, released
• GITHUB_SHA: タグ付きリリースの最新コミット
• GITHUB_REF: refs/tags/TAG_NAME
• ドラフトリリースは created/edited/deleted をトリガーしない
• 安定版とプレリリースの両方には published を使用

repository_dispatch

外部イベントによるトリガー。

• アクティビティタイプ: カスタム（ユーザー指定の event_type）
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ
• client_payload: 最大 10 個のトップレベルプロパティ、65,535 文字制限
• event_type: 100 文字制限

on:
  repository_dispatch:
    types: [deploy, rollback]

schedule

cron スケジュールによる定期実行。

on:
  schedule:
    - cron: '30 5 * * 1-5'   # 平日 5:30 UTC
    - cron: '0 0 * * 0'      # 毎週日曜 0:00 UTC

cron フィールド: 分 時 日 月 曜日

演算子: *（任意）, ,（リスト）, -（範囲）, /（ステップ）

• デフォルトブランチでのみ実行
• 最短間隔: 5 分
• 高負荷時は遅延する可能性がある
• パブリックリポジトリでは 60 日間アクティビティがないと自動無効化
• github.event.schedule でトリガーしたスケジュールにアクセス可能

status

コミットステータスの変更時。

• アクティビティタイプ: なし
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ
• 状態: error, failure, pending, success

watch

リポジトリがスターされた時。

• アクティビティタイプ: started
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ

workflow_call

再利用可能ワークフローとして呼び出された時。

• アクティビティタイプ: なし
• 呼び出し元ワークフローのコンテキストを継承

on:
  workflow_call:
    inputs:
      environment:
        type: string
        required: true
    secrets:
      deploy_key:
        required: true
    outputs:
      result:
        value: ${{ jobs.build.outputs.result }}

入力タイプ: boolean, number, string

詳細は reusable-workflows.md を参照。

workflow_dispatch

手動トリガー。

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deploy environment'
        required: true
        type: choice
        options:
          - staging
          - production
      dry_run:
        description: 'Dry run'
        type: boolean
        default: false

• 入力タイプ: string, boolean, choice, environment
• 最大 25 個のトップレベルプロパティ
• 65,535 文字のペイロード制限

workflow_run

他のワークフローの実行イベント。

• アクティビティタイプ: completed, requested, in_progress
• GITHUB_SHA: デフォルトブランチの最新コミット
• GITHUB_REF: デフォルトブランチ
• フィルタ: branches, branches-ignore
• 最大 3 レベルのワークフローチェーン
• トリガーワークフローのアーティファクトに REST API でアクセス可能

on:
  workflow_run:
    workflows: ["Build"]
    types: [completed]
    branches: [main]

GitHub Actions -- 式と関数

ワークフローで使用できる式、演算子、組み込み関数のリファレンス。

公式ドキュメント: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions

---

式の構文

式は ${{ }} で囲んで使用する。

env:
  MY_VAR: ${{ github.ref }}

steps:
  - if: ${{ github.ref == 'refs/heads/main' }}
    run: echo "On main branch"

if キーでは ${{ }} を省略できる:

  - if: github.ref == 'refs/heads/main'

---

リテラルとデータ型

---

演算子

重要な動作

• 文字列比較は大文字小文字を区別しない
• 型が異なる場合、自動的に数値に変換して比較する（緩い等価性）
• 配列やオブジェクトは参照でのみ比較

---

型変換ルール

比較時に型が一致しない場合、以下のルールで数値に変換される:

Falsy 値

以下の値は条件式で false に評価される: false, 0, -0, "", '', null

---

組み込み関数

文字列関数

contains(search, item)

search が item を含む場合 true を返す。文字列（部分文字列チェック）と配列（要素チェック）の両方で動作する。大文字小文字を区別しない。

if: contains('Hello world', 'llo')          # true
if: contains(github.event.issue.labels.*.name, 'bug')

startsWith(searchString, searchValue)

searchString が searchValue で始まる場合 true を返す。大文字小文字を区別しない。

if: startsWith(github.ref, 'refs/tags/')

endsWith(searchString, searchValue)

searchString が searchValue で終わる場合 true を返す。大文字小文字を区別しない。

if: endsWith(github.repository, '-api')

format(string, replaceValue0, replaceValue1, ..., replaceValueN)

{N} プレースホルダーを対応する値に置換する。リテラルの波括弧は {{ でエスケープする。

${{ format('Hello {0} {1}', 'Mona', 'Octocat') }}
# 結果: 'Hello Mona Octocat'

${{ format('{{Key}}: {0}', 'value') }}
# 結果: '{Key}: value'

join(array, optionalSeparator)

配列の要素を文字列に連結する。デフォルトのセパレータはカンマ。

${{ join(github.event.issue.labels.*.name, ', ') }}
# 結果: 'bug, help wanted'

データ変換関数

toJSON(value)

値の整形済み JSON 表現を返す。デバッグに有用。

- run: echo '${{ toJSON(github.event) }}'

fromJSON(value)

JSON 文字列をネイティブオブジェクト、配列、またはデータ型にパースする。ジョブ間で JSON マトリクスを渡したり、環境変数を適切な型に変換するのに使用。

# 動的マトリクスの生成
strategy:
  matrix: ${{ fromJSON(needs.setup.outputs.matrix) }}

# 環境変数の型変換
env:
  IS_ENABLED: ${{ fromJSON('true') }}  # boolean として扱われる

hashFiles(path)

グロブパターンに一致するファイルの SHA-256 ハッシュを計算する。パスは GITHUB_WORKSPACE からの相対パス。複数パターンをカンマ区切りで指定可能。

# 単一パターン
${{ hashFiles('**/package-lock.json') }}

# 複数パターン
${{ hashFiles('**/package-lock.json', '**/Gemfile.lock') }}

# 除外パターン
${{ hashFiles('/lib/**/*.rb', '!/lib/foo/*.rb') }}

一致するファイルがない場合は空文字列を返す。

条件関数

case(pred1, val1, pred2, val2, ..., default)

述語を順番に評価し、最初に true になった述語に対応する値を返す。一致しない場合はデフォルト値を返す。

${{ case(github.ref == 'refs/heads/main', 'production', 'development') }}

---

ステータスチェック関数

if 条件で使用する。これらの関数を使うとデフォルトの success() チェックが上書きされる。

success()

前の全ステップが成功した場合に true を返す。

if: success()

always()

ステップを常に実行し、キャンセルされても true を返す。

if: always()

注意: クリティカルなタスクには always() の代わりに !cancelled() を使用することが推奨される。

cancelled()

ワークフローがキャンセルされた場合に true を返す。

if: cancelled()

failure()

ジョブの前のステップのいずれかが失敗した場合に true を返す。

if: failure()
# 特定のステップの失敗を検出
if: failure() && steps.deploy.conclusion == 'failure'

---

オブジェクトフィルタ

* 構文でコレクションから全一致アイテムを選択する。

# 配列フィルタ: 全要素の name プロパティを抽出
github.event.issue.labels.*.name

# オブジェクトフィルタ: 全オブジェクトの特定プロパティを取得
vegetables.*.ediblePortions

結果は配列として返される。オブジェクトフィルタの順序は保証されない。

---

一般的な式パターン

# ブランチ名によるフィルタリング
if: github.ref == 'refs/heads/main'
if: startsWith(github.ref, 'refs/tags/v')

# イベントタイプによるフィルタリング
if: github.event_name == 'push'
if: github.event_name == 'pull_request'

# ラベルの存在チェック
if: contains(github.event.pull_request.labels.*.name, 'deploy')

# 複合条件
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
if: "!cancelled()"

# アクターによるフィルタリング
if: github.actor == 'dependabot[bot]'

# 変更ファイルの検出（別ステップの出力を利用）
if: steps.changes.outputs.src == 'true'

GitHub Actions -- GITHUB_TOKEN パーミッション

GITHUB_TOKEN の自動認証とパーミッションスコープのリファレンス。

公式ドキュメント: https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication

---

概要

GITHUB_TOKEN は各ワークフロー実行の開始時に自動生成されるトークン。ワークフロー内で GitHub API やリポジトリ操作に使用できる。ジョブ終了時に失効する。

アクセス方法:

• コンテキスト: ${{ secrets.GITHUB_TOKEN }} または ${{ github.token }}
• 環境変数: $GITHUB_TOKEN

---

パーミッションスコープ一覧

---

デフォルトパーミッション

リポジトリ設定の「Workflow permissions」で 2 つのデフォルトモードから選択可能:

Permissive（寛容）モード

contents: write を含む広いデフォルト権限。

Restricted（制限）モード（推奨）

contents: read と packages: read のみ。その他は none。

---

パーミッションの設定

ワークフローレベル

全ジョブに適用される。

permissions:
  contents: read
  issues: write
  pull-requests: write

ジョブレベル

特定ジョブのみに適用。ワークフローレベルの設定を上書きする。

jobs:
  deploy:
    permissions:
      contents: read
      deployments: write
    steps:
      - uses: actions/checkout@v4

一括設定

# 全スコープに読み取り権限
permissions: read-all

# 全スコープに書き込み権限
permissions: write-all

# 全権限を無効化（GITHUB_TOKEN は使用不可）
permissions: {}

重要な注意点

• ワークフローレベルで permissions を指定すると、明示的に記載されていないスコープは none に設定される
• ジョブレベルで permissions を指定すると、そのジョブでは明示的に記載されていないスコープは none に設定される
• 権限は昇格できない（再利用可能ワークフローチェーンでは維持または制限のみ可能）

---

フォークリポジトリの制限

フォークされたリポジトリからのプルリクエストでは、GITHUB_TOKEN に以下の制限がある:

• パブリックリポジトリのフォーク: デフォルトで読み取り専用
• プライベートリポジトリのフォーク: リポジトリ設定で制御可能
• フォーク PR では pull-requests: write 権限が制限される場合がある
• シークレット（GITHUB_TOKEN 以外）はフォーク PR のランナーに渡されない

---

イベントごとのデフォルト権限

特定のイベントでは、デフォルトの権限が異なる場合がある:

---

ベストプラクティス

1. 最小権限の原則: 必要なスコープのみを明示的に設定する 2. 制限モードをデフォルトに: リポジトリ設定で Restricted モードを選択する 3. ジョブレベルで設定: ワークフロー全体ではなくジョブ単位で権限を設定する 4. フォーク PR に注意: pull_request_target で信頼できないコードを実行しない 5. `id-token: write`: OIDC を使用する場合のみ設定する

# 推奨パターン
permissions:
  contents: read

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run lint

  deploy:
    needs: lint
    permissions:
      contents: read
      deployments: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh

GitHub Actions

GitHub Actions -- 再利用可能ワークフロー

ワークフローの再利用（workflow_call）のリファレンス。

公式ドキュメント: https://docs.github.com/en/actions/sharing-automations/reusing-workflows

---

概要

再利用可能ワークフローを使用すると、ワークフローの定義を共有し、重複を排除できる。.github/workflows/ ディレクトリに配置されたワークフローファイルを他のワークフローから呼び出す。

---

再利用可能ワークフローの定義

on: workflow_call トリガーを使用して再利用可能ワークフローを定義する。

# .github/workflows/reusable-deploy.yml
name: Reusable Deploy

on:
  workflow_call:
    inputs:
      environment:
        description: 'Deploy target environment'
        required: true
        type: string
      version:
        description: 'Version to deploy'
        required: false
        type: string
        default: 'latest'
    secrets:
      deploy_key:
        description: 'Deployment SSH key'
        required: true
    outputs:
      deploy_url:
        description: 'Deployed URL'
        value: ${{ jobs.deploy.outputs.url }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    outputs:
      url: ${{ steps.deploy.outputs.url }}
    steps:
      - uses: actions/checkout@v4
      - id: deploy
        run: |
          echo "Deploying ${{ inputs.version }} to ${{ inputs.environment }}"
          echo "url=https://${{ inputs.environment }}.example.com" >> $GITHUB_OUTPUT
        env:
          DEPLOY_KEY: ${{ secrets.deploy_key }}

---

入力（inputs）の定義

アクセス方法: ${{ inputs.input_name }}

---

シークレット（secrets）の定義

アクセス方法: ${{ secrets.secret_name }}

---

出力（outputs）の定義

再利用可能ワークフローの出力は、ジョブ出力からマッピングする必要がある。

on:
  workflow_call:
    outputs:
      result:
        description: 'Build result'
        value: ${{ jobs.build.outputs.result }}

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      result: ${{ steps.build.outputs.result }}
    steps:
      - id: build
        run: echo "result=success" >> $GITHUB_OUTPUT

出力の流れ: ステップ出力 -> ジョブ出力 -> ワークフロー出力

---

呼び出し構文

同一リポジトリ

jobs:
  deploy:
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: production
      version: '1.0.0'
    secrets:
      deploy_key: ${{ secrets.DEPLOY_KEY }}

• 呼び出し元と同じコミットのワークフローファイルを使用する
• コンテキストや式は使用できない

別リポジトリ

jobs:
  deploy:
    uses: org/repo/.github/workflows/reusable-deploy.yml@main
    with:
      environment: production
    secrets:
      deploy_key: ${{ secrets.DEPLOY_KEY }}

{owner}/{repo}/.github/workflows/{filename}@{ref} の形式で指定する。

{ref} に使用可能な値:

• ブランチ名: @main
• タグ名: @v1.0.0
• コミット SHA: @8e5e7e5ab8b370d6c329ec480221332ada57f0ab（最も安全）

注意: タグとブランチが同名の場合、タグが優先される。

---

シークレットの継承

同じ Organization/Enterprise 内のワークフローでは、secrets: inherit で全シークレットを一括で渡せる。

jobs:
  deploy:
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: production
    secrets: inherit  # 全シークレットを継承

---

呼び出し元での出力参照

jobs:
  build:
    uses: ./.github/workflows/reusable-build.yml

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploy URL is ${{ needs.build.outputs.deploy_url }}"

---

マトリクス戦略との組み合わせ

jobs:
  deploy:
    strategy:
      matrix:
        environment: [staging, production]
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: ${{ matrix.environment }}
    secrets: inherit

注意: マトリクス戦略を使用した場合、出力は最後に成功したワークフロー実行の値になる。

---

ネスト制限

---

制限事項

1. ワークフローファイルの配置: .github/workflows/ ディレクトリのルートに配置する必要がある（サブディレクトリは不可） 2. 環境シークレット: workflow_call 経由で環境シークレットを渡す場合、環境レベルのシークレットが呼び出し元のシークレットを上書きする 3. ステップ出力の公開: ステップ出力はジョブ出力にマッピングしてからワークフロー出力として公開する必要がある 4. `env` コンテキスト: 呼び出し元の env コンテキストは再利用可能ワークフローに伝播しない 5. 同時呼び出し: 1 つのワークフローから最大 20 個の再利用可能ワークフローを呼び出し可能

---

ベストプラクティス

1. コミット SHA での参照: 安定性とセキュリティのためにコミット SHA を使用する 2. 出力の適切なマッピング: ステップ -> ジョブ -> ワークフロー の出力マッピングを確実に行う 3. `secrets: inherit` の適切な使用: 信頼できるワークフローにのみ全シークレットを継承させる 4. ドキュメント化: 入力、シークレット、出力の description を記載する 5. バージョニング: メジャーバージョンタグ（@v1）を使用し、破壊的変更時にバージョンを上げる

GitHub Actions -- ランナー

GitHub ホステッドランナーとセルフホステッドランナーのリファレンス。

公式ドキュメント: https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners

---

GitHub ホステッドランナー

GitHub が管理するクラウドホスト型の仮想マシン。ワークフロー実行ごとにクリーンなインスタンスが提供される。

---

利用可能なランナーラベル

Linux ランナー

Windows ランナー

macOS ランナー

---

ハードウェアスペック

標準ランナー

ラージランナー（GitHub Team / Enterprise Cloud）

より多くの CPU コア、メモリ、ストレージを持つランナー。GPU ランナーも利用可能。

ラージランナーは runs-on にカスタムラベルを指定して使用する:

runs-on: ubuntu-latest-8-cores

---

プリインストールソフトウェア

ランナーには以下のカテゴリのツールがプリインストールされている:

• 言語ランタイム: Node.js, Python, Ruby, Go, Java, .NET, PHP, Rust 等
• パッケージマネージャ: npm, yarn, pip, gem, cargo, nuget 等
• ビルドツール: make, cmake, gradle, maven 等
• バージョン管理: git, gh (GitHub CLI)
• コンテナツール: Docker, docker-compose
• クラウド CLI: AWS CLI, Azure CLI, Google Cloud SDK
• ブラウザ: Chrome, Firefox（テスト用）
• その他: curl, wget, jq, zip/unzip 等

詳細なインストール済みソフトウェア一覧: https://github.com/actions/runner-images

注意: プリインストールソフトウェアは毎週更新される。特定のバージョンが必要な場合は setup-* アクションを使用することを推奨。

# バージョンを明示的に指定する推奨パターン
steps:
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
  - uses: actions/setup-python@v5
    with:
      python-version: '3.12'

---

ランナーの指定方法

単一ラベル

jobs:
  build:
    runs-on: ubuntu-latest

マトリクスによる複数 OS

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
runs-on: ${{ matrix.os }}

ラベルの配列（セルフホステッド用）

runs-on: [self-hosted, linux, x64]

---

セルフホステッドランナー

自前のインフラストラクチャでワークフローを実行するランナー。

主なユースケース

• カスタムハードウェア要件（GPU、大容量メモリ等）
• プライベートネットワーク内のリソースへのアクセス
• 特定の OS やソフトウェア環境の要件
• コスト最適化（大量のワークフロー実行時）

セットアップ

1. リポジトリ/Organization 設定の「Actions」->「Runners」からランナーを追加 2. ランナーアプリケーションをダウンロードしてインストール 3. ランナーをサービスとして構成・起動

ラベル

セルフホステッドランナーには自動的に以下のラベルが付与される:

• self-hosted
• OS ラベル: linux, windows, macos
• アーキテクチャラベル: x64, arm, arm64
• カスタムラベルの追加も可能

runs-on: [self-hosted, linux, x64, gpu]

セキュリティ上の注意

• パブリックリポジトリでのセルフホステッドランナーの使用は非推奨
• フォークからの PR がランナー上で任意のコードを実行できるリスクがある
• ランナーマシンは信頼できる環境に配置すること

---

---

Actions Runner Controller (ARC)

Kubernetes 上でセルフホステッドランナーをスケールセットとして管理する仕組み。

• Helm チャートでデプロイする
• RunnerScaleSet カスタムリソースでスケールアウト/インを自動制御
• GitHub Apps または PAT で認証する

# ワークフローでの使用例
runs-on:
  group: arc-runner-set

詳細: https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller

---

ネットワーク要件

GitHub ホステッドランナーの使用には、最低 70 kbps のアップロード/ダウンロード速度のネットワーク接続が必要。

GitHub Actions -- シークレット管理

ワークフローでのシークレット管理のリファレンス。

公式ドキュメント: https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions

---

概要

シークレットは暗号化された環境変数で、トークン、パスワード、API キー等の機密情報をワークフローに安全に渡すために使用する。

---

シークレットへのアクセス

secrets コンテキスト

steps:
  - name: アクションの入力として渡す
    uses: some/action@v1
    with:
      token: ${{ secrets.MY_TOKEN }}

  - name: 環境変数として渡す
    run: ./deploy.sh
    env:
      API_KEY: ${{ secrets.API_KEY }}

重要な制約

• `if:` 条件で直接参照できない: 環境変数経由で使用する

# NG: 直接参照
- if: secrets.MY_SECRET != ''  # 動作しない

# OK: 環境変数経由
jobs:
  example:
    env:
      HAS_SECRET: ${{ secrets.MY_SECRET != '' }}
    steps:
      - if: env.HAS_SECRET == 'true'
        run: echo "Secret is set"

---

シークレットの種類

リポジトリシークレット

特定のリポジトリのワークフローでのみ利用可能。

設定方法: 1. Settings -> Secrets and variables -> Actions -> Secrets タブ -> New repository secret 2. CLI: gh secret set SECRET_NAME

環境シークレット

特定のデプロイ環境に紐づくシークレット。環境の保護ルール（レビュー必須等）と組み合わせて使用可能。

設定方法: 1. Settings -> Environments -> 環境を選択 -> Environment secrets で追加 2. CLI: gh secret set --env ENV_NAME SECRET_NAME

jobs:
  deploy:
    environment: production  # この環境のシークレットが利用可能になる
    steps:
      - run: ./deploy.sh
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}

Organization シークレット

Organization 内の複数リポジトリで共有可能。アクセスポリシーで対象リポジトリを制御する。

設定方法: 1. Organization Settings -> Secrets and variables -> Actions -> New organization secret 2. CLI: gh secret set --org ORG_NAME SECRET_NAME

アクセスポリシー:

• 全リポジトリ（--visibility all）
• プライベートリポジトリのみ（--visibility private）
• 指定リポジトリのみ（--repos REPO1,REPO2）

注意: GitHub Free プランでは、Organization レベルのシークレットはプライベートリポジトリからアクセスできない。

---

GITHUB_TOKEN

全ワークフローで自動的に利用可能な特殊なシークレット。

steps:
  - uses: actions/checkout@v4
    with:
      token: ${{ secrets.GITHUB_TOKEN }}

  - run: gh pr comment --body "Deployed!"
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

詳細は permissions.md を参照。

---

名前付けルール

---

サイズと数の制限

---

大きなシークレットの取り扱い

48 KB を超えるシークレットには以下のワークアラウンドを使用する:

GPG 暗号化方式

1. シークレットファイルを GPG で暗号化する 2. パスフレーズをリポジトリシークレットとして保存する 3. 暗号化されたファイルをリポジトリにコミットする 4. ワークフロー内で復号する

steps:
  - uses: actions/checkout@v4
  - run: gpg --quiet --batch --yes --decrypt --passphrase="$PASSPHRASE" --output secret.json secret.json.gpg
    env:
      PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}

Base64 エンコード方式

バイナリデータの場合:

steps:
  - run: echo "$ENCODED_SECRET" | base64 --decode > secret.bin
    env:
      ENCODED_SECRET: ${{ secrets.BINARY_SECRET }}

注意: GitHub はこれらのワークアラウンドで使用する復号済みの値をログで自動マスクしない。

---

シークレットのマスキング

自動マスク

GitHub シークレットとして登録された値は、ログ出力時に自動的に *** でマスクされる。

手動マスク

GitHub シークレット以外の機密情報もマスクできる:

steps:
  - run: |
      TOKEN=$(generate-token)
      echo "::add-mask::$TOKEN"
      echo "Using token: $TOKEN"  # ログでは *** と表示される

---

フォークリポジトリとシークレット

• `GITHUB_TOKEN` 以外のシークレットはフォークからの PR のランナーに渡されない
• `GITHUB_TOKEN` はフォーク PR でも利用可能だが、読み取り専用（制限付き権限）
• pull_request_target イベントではデフォルトブランチのコンテキストで実行されるためシークレットにアクセスできるが、セキュリティリスクに注意

---

再利用可能ワークフローとシークレット

シークレットは再利用可能ワークフローに自動的に渡されない。明示的に渡す必要がある:

jobs:
  call-reusable:
    uses: ./.github/workflows/reusable.yml
    secrets:
      deploy_key: ${{ secrets.DEPLOY_KEY }}

    # または全シークレットを継承
    secrets: inherit

---

セキュリティベストプラクティス

1. 最小権限の原則: 必要なシークレットのみをワークフローに渡す 2. コマンドライン引数に渡さない: プロセスリストで公開される可能性がある。環境変数を使用する

# NG
- run: curl -H "Authorization: token ${{ secrets.TOKEN }}" https://api.example.com

# OK
- run: curl -H "Authorization: token $TOKEN" https://api.example.com
  env:
    TOKEN: ${{ secrets.TOKEN }}

3. 構造化データを避ける: JSON 等の構造化データ全体をシークレットにすると、マスキングが不完全になる場合がある 4. 定期的なローテーション: シークレットは定期的に更新する 5. シークレットの登録を確認: ::add-mask:: で手動マスクを追加して防御層を増やす 6. 監査ログを確認: Organization のシークレットアクセスを監査ログで監視する

GitHub Actions -- ワークフロー構文リファレンス

ワークフローファイル (.github/workflows/*.yml) で使用可能な全キーの網羅的リファレンス。

公式ドキュメント: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions

---

トップレベルキー

name

ワークフローの表示名。省略時はファイルパスが表示される。

name: CI Pipeline

run-name

個別のワークフロー実行に表示される名前。github および inputs コンテキストの式をサポート。

run-name: Deploy to ${{ inputs.deploy_target }} by @${{ github.actor }}

on

ワークフローをトリガーするイベントを定義する。

# 単一イベント
on: push

# 複数イベント
on: [push, pull_request]

# イベント設定付き
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

詳細は events-triggers.md を参照。

permissions

GITHUB_TOKEN のアクセスレベルを制御する。ワークフローレベルで設定すると全ジョブに適用される。

permissions:
  contents: read
  issues: write
  pull-requests: write

# 一括設定
permissions: read-all
permissions: write-all
permissions: {}  # 全権限を無効化

利用可能なスコープ: actions, artifact-metadata, attestations, checks, code-quality, contents, deployments, discussions, id-token, issues, models, packages, pages, pull-requests, repository-projects, security-events, statuses, vulnerability-alerts

各スコープの値: read, write, none

env

ワークフロー全体で利用できる環境変数のマップ。

env:
  NODE_ENV: production
  API_URL: https://api.example.com

注意: 同じ env マップ内で他の変数を参照することはできない。

defaults

全ジョブに適用されるデフォルト設定。

defaults:
  run:
    shell: bash
    working-directory: ./src

defaults.run

run ステップのデフォルト shell と working-directory を設定する。

対応シェル: bash, pwsh, python, sh, cmd, powershell

concurrency

同じ concurrency グループのジョブ/ワークフローが同時に1つだけ実行されるようにする。

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

• group: グループ名（大文字小文字を区別しない）
• cancel-in-progress: true にすると、同じグループの進行中のジョブをキャンセルする
• github, inputs, vars コンテキストの式をサポート

# pending キューを使う場合
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false  # キャンセルせず最大 100 件を待機させる

注意: cancel-in-progress を省略または false にした場合、同じグループの実行は最大 100 件まで待機キューに入る。それ以上は最古のペンディング実行がキャンセルされる。

jobs

ワークフロー内の全ジョブを定義するコンテナ。ジョブはデフォルトで並列実行される。

---

ジョブレベルキー (jobs.<job_id>)

<job_id> は英数字、-、_ で構成され、英字または _ で始まる必要がある。

jobs.<job_id>.name

UI に表示されるジョブの表示名。

jobs:
  build:
    name: Build Application

jobs.<job_id>.permissions

ジョブ固有のトークン権限。ワークフローレベルの設定を上書きする。

jobs:
  deploy:
    permissions:
      contents: read
      deployments: write

jobs.<job_id>.needs

このジョブの前に完了する必要があるジョブ ID のリスト。

jobs:
  test:
    needs: build
  deploy:
    needs: [build, test]

jobs.<job_id>.if

ジョブを実行するかどうかを決める条件式。

jobs:
  deploy:
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'

jobs.<job_id>.runs-on

ジョブを実行するランナー環境を指定する。

runs-on: ubuntu-latest
runs-on: [self-hosted, linux, x64]
runs-on: ${{ matrix.os }}

主なラベル: ubuntu-latest, ubuntu-24.04, ubuntu-22.04, windows-latest, windows-2022, macos-latest, macos-15, macos-14, macos-13

jobs.<job_id>.environment

デプロイジョブの環境名。URL の指定も可能。

environment:
  name: production
  url: https://example.com

jobs.<job_id>.concurrency

ジョブレベルの concurrency 制御。ワークフローレベルと同じ構文。

jobs.<job_id>.outputs

依存ジョブからアクセス可能な出力マップ。

jobs:
  build:
    outputs:
      artifact_url: ${{ steps.upload.outputs.url }}
  deploy:
    needs: build
    steps:
      - run: echo ${{ needs.build.outputs.artifact_url }}

jobs.<job_id>.env

ジョブレベルの環境変数。ワークフローレベルの env を上書きする。

jobs.<job_id>.defaults

ジョブレベルの run ステップのデフォルト設定。ワークフローレベルの設定を上書きする。

jobs.<job_id>.timeout-minutes

ジョブの最大実行時間（分）。デフォルトは 360 分（6 時間）。超過すると自動キャンセルされる。

jobs.<job_id>.strategy

ビルドマトリクスを定義し、ジョブのバリエーションを並列実行する。

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node-version: [18, 20, 22]
  fail-fast: false
  max-parallel: 2

• fail-fast: true（デフォルト）の場合、マトリクスジョブの1つが失敗すると残りもキャンセルされる
• max-parallel: 同時実行するマトリクスジョブの最大数

strategy.matrix の詳細

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [18, 20]
    # include で追加の組み合わせを定義
    include:
      - os: ubuntu-latest
        node: 22
        experimental: true
    # exclude で特定の組み合わせを除外
    exclude:
      - os: windows-latest
        node: 18

• include: マトリクスに組み合わせを追加、または既存の組み合わせにプロパティを追加
• exclude: マトリクスから特定の組み合わせを除外
• マトリクス値へのアクセス: ${{ matrix.os }}, ${{ matrix.node }}
• fromJSON() で動的マトリクスを生成可能

jobs.<job_id>.container

ジョブを Docker コンテナ内で実行する設定。

container:
  image: node:20
  env:
    NODE_ENV: production
  ports:
    - 80
  volumes:
    - my_docker_volume:/volume_mount
  options: --cpus 1
  credentials:
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

jobs.<job_id>.services

ジョブ実行中に利用可能なサービスコンテナ（データベース、キャッシュ等）を定義する。

services:
  postgres:
    image: postgres:15
    env:
      POSTGRES_PASSWORD: postgres
    ports:
      - 5432:5432
    options: >-
      --health-cmd pg_isready
      --health-interval 10s
      --health-timeout 5s
      --health-retries 5
  redis:
    image: redis:7
    ports:
      - 6379:6379

jobs.<job_id>.uses

再利用可能ワークフローを参照する。

jobs:
  call-reusable:
    uses: owner/repo/.github/workflows/reusable.yml@main
    # または同一リポジトリ
    uses: ./.github/workflows/reusable.yml

jobs.<job_id>.with

再利用可能ワークフローやアクションに入力を渡す。

jobs:
  call-reusable:
    uses: ./.github/workflows/reusable.yml
    with:
      environment: production
      version: 1.0.0

jobs.<job_id>.secrets

再利用可能ワークフローにシークレットを渡す。

jobs:
  call-reusable:
    uses: ./.github/workflows/reusable.yml
    secrets:
      deploy_key: ${{ secrets.DEPLOY_KEY }}
    # または全シークレットを継承
    secrets: inherit

---

ステップレベルキー (jobs.<job_id>.steps[*])

ステップはジョブ内で順番に実行される。各ステップはランナー上の独自のプロセスで実行される。

steps[*].id

ステップの一意識別子。後続のステップで出力を参照するために使用する。

steps:
  - id: build-step
    run: echo "version=1.0" >> $GITHUB_OUTPUT
  - run: echo ${{ steps.build-step.outputs.version }}

steps[*].if

条件付きでステップを実行する。ステータス関数やコンテキストを使用可能。

steps:
  - if: success()
    run: echo "Previous steps succeeded"
  - if: failure()
    run: echo "A previous step failed"
  - if: always()
    run: echo "Always runs"
  - if: cancelled()
    run: echo "Workflow was cancelled"
  - if: github.event_name == 'push'
    run: echo "Triggered by push"

steps[*].name

ログに表示されるステップの説明的な名前。

steps[*].uses

アクションまたは再利用可能ワークフローを実行する。

steps:
  # パブリックアクション（バージョン指定）
  - uses: actions/checkout@v4
  # パブリックアクション（SHA 指定）
  - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab
  # 同一リポジトリのアクション
  - uses: ./.github/actions/my-action
  # Docker Hub イメージ
  - uses: docker://alpine:3.18

steps[*].run

シェルコマンドを実行する。defaults.run.shell と defaults.run.working-directory の設定を継承する。

steps:
  - run: echo "Hello World"
  # 複数行コマンド
  - run: |
      echo "Line 1"
      echo "Line 2"

steps[*].working-directory

このステップのみのワーキングディレクトリを上書きする。

steps[*].shell

このステップのみのシェルを上書きする。

steps:
  - run: echo "Using PowerShell"
    shell: pwsh

対応シェル: bash, pwsh, python, sh, cmd, powershell

steps[*].with

アクションの入力パラメータ（キーバリューマップ）。

steps:
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'

steps[*].env

ステップレベルの環境変数。

steps:
  - run: echo $MY_VAR
    env:
      MY_VAR: hello

steps[*].continue-on-error

true に設定すると、ステップが失敗してもジョブの実行を継続する。

steps:
  - run: ./optional-check.sh
    continue-on-error: true

steps[*].timeout-minutes

ステップ固有の実行タイムアウト（分）。

---

条件式

if キーで使用される条件式の構文。

# コンテキスト参照
if: github.ref == 'refs/heads/main'

# 論理演算子
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
if: "!cancelled()"

# 関数
if: contains(github.event.pull_request.labels.*.name, 'deploy')
if: startsWith(github.ref, 'refs/tags/')
if: always()

詳細は expressions.md を参照。

---

制約事項

• ワークフローファイルは .github/workflows/ ディレクトリに .yml または .yaml 拡張子で配置する
• workflow_dispatch の入力は最大 25 個のトップレベルプロパティ
• パスフィルタリングの Git diff は 300 ファイルまで（超過時はワークフローが自動トリガーされない）
• concurrency グループ名は大文字小文字を区別しない
• スケジュールの最短間隔は 5 分

GitHub Apps 概要

GitHub Apps とは

GitHub Apps は GitHub の機能を拡張するための公式に推奨されるインテグレーション方式。細かい権限制御、リポジトリレベルのアクセス管理、短命トークンによる高いセキュリティを提供する。

App の種類

GitHub Apps（推奨）

• 細粒度の権限モデル
• ユーザーがアクセスを許可するリポジトリを制御可能
• 短命トークン（1 時間で失効）を使用
• ユーザーの介入なしに独立して動作可能
• Bot アカウントとして動作（Enterprise のシートを消費しない）

OAuth Apps

• ブロードなスコープベースの権限
• ユーザーのアクセス可能なすべてのリソースにアクセス
• トークンは取り消されるまで有効
• ユーザーコンテキストが常に必要
• 新規開発では GitHub Apps を推奨

ユースケース

GitHub 上の操作

• Issue の作成・コメント
• プルリクエストのレビュー・マージ
• プロジェクトの管理
• ブランチ保護ルールの設定
• コードの自動チェック・レビュー

外部サービスとの連携

• Issue 作成時に Slack 通知を送信
• CI/CD パイプラインのトリガー
• 外部イシュートラッカーとの同期
• デプロイメントの自動化

権限モデル

GitHub Apps は 3 つのカテゴリの権限を持つ。

各権限は以下のアクセスレベルを設定できる:

• No access: アクセスなし
• Read-only: 読み取りのみ
• Read & write: 読み書き

セキュリティ上の利点

公式ドキュメント

• About apps

GitHub App 認証フロー

3 つの認証方式

GitHub App は用途に応じて 3 つの認証方式を使い分ける。

1. App として認証（JWT）

用途

• App がインストールされているアカウントの一覧取得
• インストールアクセストークンの生成
• App 自体の管理操作

JWT の生成

JWT は以下の要素で構成される:

JWT 生成例

require 'openssl'
require 'jwt'

private_key = OpenSSL::PKey::RSA.new(File.read('private-key.pem'))

payload = {
  iat: Time.now.to_i - 60,        # 発行日時（60秒のクロックドリフト対策）
  exp: Time.now.to_i + (10 * 60), # 有効期限（10分後）
  iss: APP_ID                      # App ID
}

jwt = JWT.encode(payload, private_key, 'RS256')

使用方法

Authorization: Bearer JWT_TOKEN

2. インストールとして認証（IAT）

用途

• ユーザーの入力を伴わない自動化ワークフロー
• インストール先の Organization/ユーザーが所有するリソースへのアクセス
• Bot として操作を実行（例: @app-name[bot]）

インストールアクセストークンの生成

1. JWT で認証する 2. REST API でインストールアクセストークンを要求する

POST /app/installations/{installation_id}/access_tokens
Authorization: Bearer JWT_TOKEN

トークンの特徴

使用方法

Authorization: token INSTALLATION_ACCESS_TOKEN

リポジトリ・権限の絞り込み

トークン生成時にリポジトリと権限を限定できる:

{
  "repositories": ["repo-name"],
  "permissions": {
    "issues": "write",
    "contents": "read"
  }
}

3. ユーザーとして認証（UAT）

用途

• ユーザーの代理としてアクションを実行
• ユーザーの権限に基づいたアクセスの確保
• 操作をユーザーに帰属させる

OAuth フロー（Web Application Flow）

1. ユーザーを GitHub の認証ページにリダイレクト

GET https://github.com/login/oauth/authorize
  ?client_id=CLIENT_ID
  &redirect_uri=CALLBACK_URL
  &state=RANDOM_STATE

2. ユーザーが認証を承認すると、code パラメータ付きでコールバック URL にリダイレクトされる

3. code をアクセストークンに交換

POST https://github.com/login/oauth/access_token
  client_id=CLIENT_ID
  &client_secret=CLIENT_SECRET
  &code=CODE

4. アクセストークンを使用して API を呼び出す

Authorization: token USER_ACCESS_TOKEN

デバイスフロー

ブラウザアクセスが制限される環境（CLI、IoT など）で使用する。

1. デバイスコードをリクエスト

POST https://github.com/login/device/code
  client_id=CLIENT_ID
  scope=SCOPE

2. ユーザーに user_code を表示し、verification_uri にアクセスしてコードを入力するよう指示する

3. ポーリングでトークンを取得

POST https://github.com/login/oauth/access_token
  client_id=CLIENT_ID
  device_code=DEVICE_CODE
  grant_type=urn:ietf:params:oauth:grant-type:device_code

トークンの有効期限

• GitHub はユーザーアクセストークンの有効期限設定を強く推奨
• 有効期限切れのトークンはリフレッシュトークンで更新可能

認証方式の選択ガイド

公式ドキュメント

• About authentication with a GitHub App

apps

Authentication

CLI