Tips - ワークフローの"実行"をコントロールする

Posted at 2025-12-23

Tips - ワークフローの"実行"をコントロールする

GitHub Actionsのワークフロー実行管理機能は、CI/CDパイプラインを効率的に運用するための強力なツールセットです。本記事では、公式ドキュメントをもとに、実務で活用できる機能を体系的に解説します。

1. キャッシュ管理

依存関係のキャッシュは、ワークフローの実行時間を大幅に短縮します。GitHub Actionsでは、Web UI、REST API、GitHub CLIの3つの方法でキャッシュを管理できます。

1.1 キャッシュエントリの表示

リポジトリのActionsタブから、Managementセクションの「Caches」を選択すると、キャッシュ一覧が表示されます。各エントリには以下の情報が含まれます。

ディスク使用量
作成日時
最終使用日時

ブランチやキーでのフィルタリングも可能です。特定のキーで検索する場合は、key: key-nameという構文を使用します。

1.2 キャッシュの削除

書き込み権限を持つユーザーは、Web UIから個別のキャッシュエントリを削除できます。キャッシュエントリの右側にあるゴミ箱アイコンをクリックするだけです。

1.3 強制削除の実装

キャッシュにはブランチスコープ制限があり、特定のブランチに限定されたキャッシュが大量に存在すると、デフォルトブランチのキャッシュが頻繁に作成・削除される問題が発生します。

この問題を解決するため、プルリクエストのクローズ時にキャッシュを自動削除するワークフローを設定できます。

name: プルリクエストクローズ時のキャッシュクリーンアップ
on:
  pull_request:
    types:
      - closed

jobs:
  cleanup:
    runs-on: ubuntu-latest
    permissions:
      actions: write
    steps:
      - name: クリーンアップ
        run: |
          echo "キャッシュキーのリストを取得中"
          cacheKeysForPR=$(gh cache list --ref $BRANCH --limit 100 --json id --jq '.[].id')

          # キャッシュキー削除時にワークフローを失敗させないための設定
          set +e
          echo "キャッシュを削除中..."
          for cacheKey in $cacheKeysForPR
          do
              gh cache delete $cacheKey
          done
          echo "完了"
        env:
          GH_TOKEN: ${{ github.token }}
          GH_REPO: ${{ github.repository }}
          BRANCH: refs/pull/${{ github.event.pull_request.number }}/merge

クロスリポジトリのプルリクエストやフォークからのプルリクエストに対応する場合は、pull_request_targetイベントを使用しますが、セキュリティ上の考慮事項があるため注意が必要です。

2. ワークフローの手動実行

workflow_dispatchイベントを使用すると、必要なタイミングでワークフローを手動実行できます。これは、定期実行とは別に緊急でデプロイやテストを実行したい場合に有効です。

2.1 設定要件

ワークフローファイルでworkflow_dispatchイベントを設定する必要があります
デフォルトブランチにワークフローファイルが存在する必要があります
リポジトリへの書き込み権限が必要です

2.2 実行方法

Web UIから実行する場合：

リポジトリのActionsタブを開く
左サイドバーから実行したいワークフローを選択
「Run workflow」ボタンをクリック
ブランチを選択
必要に応じて入力パラメータを設定
「Run workflow」を実行

REST APIを使用する場合、inputsとrefをリクエストボディパラメータとして設定します。入力が省略された場合は、ワークフローファイルで定義されたデフォルト値が使用されます。

注意点として、workflow_dispatchイベントには最大25個のinputsを定義できます。

3. ワークフローの再実行

ワークフロー実行は、初回実行から30日以内であれば再実行できます。これは、一時的なネットワークエラーや外部サービスの障害による失敗を簡単にリカバリするための機能です。

3.1 重要な仕様

再実行時の権限とコンテキストには注意が必要です。

再実行を開始したユーザーではなく、最初にワークフローをトリガーしたユーザーの権限が使用されます
元のイベントと同じGITHUB_SHA（コミットSHA）とGITHUB_REF（gitリファレンス）が使用されます

3.2 再実行のパターン

全ジョブの再実行

Actionsタブから対象ワークフローを選択
ワークフロー実行のサマリーを表示
右上の「Re-run jobs」ドロップダウンから「Re-run all jobs」を選択
必要に応じて「Enable debug logging」を有効化
「Re-run jobs」を実行

失敗したジョブのみ再実行

失敗したジョブがある場合、ドロップダウンメニューから「Re-run failed jobs」を選択できます。これにより、成功したジョブは再実行されず、時間とリソースを節約できます。

特定ジョブの再実行

ワークフロー実行サマリーのJobsセクションで対象ジョブを選択
ジョブ名の横にあるアイコンをクリック
必要に応じてデバッグログを有効化
「Re-run jobs」を実行

3.3 以前の実行結果の確認

ワークフローが複数回再実行された場合、実行名の右側にある「Latest」ドロップダウンメニューから、以前の実行結果を確認できます。

4. ワークフローのキャンセルと無効化

4.1 ワークフローのキャンセル

実行中のワークフローは、いつでもキャンセルできます。これは、誤ってワークフローをトリガーしたり、実行中に問題に気づいたりした場合に有効です。

キャンセル方法：

Actionsタブからワークフローを選択
queuedまたはin progress状態の実行をクリック
右上の「Cancel workflow」をクリック

4.2 ワークフローの無効化

ワークフローを一時的に停止したい場合、ファイルを削除せずに無効化できます。これは以下のような場面で有効です。

外部サービスに影響を与える不具合があるワークフロー
アカウントの実行時間を過度に消費する非クリティカルなワークフロー
ダウンしているサービスにリクエストを送るワークフロー
フォークリポジトリで不要なワークフロー（スケジュール実行など）

自動無効化の仕組み

パブリックリポジトリでは、以下の条件でワークフローが自動的に無効化されます。

フォークされたリポジトリでは、スケジュール実行のワークフローがデフォルトで無効
60日間リポジトリに活動がない場合、スケジュール実行のワークフローが自動無効化

無効化と有効化の手順

無効化：

Actionsタブから対象ワークフローを選択
メニューアイコンをクリックしてドロップダウンを表示
「Disable workflow」を選択

有効化：

Actionsタブから対象ワークフローを選択
「Enable workflow」をクリック

5. ワークフロー実行のスキップ

pushおよびpull_requestイベントによってトリガーされるワークフローは、コミットメッセージに特定の文字列を含めることでスキップできます。

5.1 スキップ指示の方法

コミットメッセージに以下のいずれかを含める：

[skip ci]
[ci skip]
[no ci]
[skip actions]
[actions skip]

または、コミットメッセージの末尾にトレーラーセクションを追加：

skip-checks:true
skip-checks: true

トレーラーセクションは、コミットメッセージの最後に配置し、2つの空行を前に置く必要があります。他のトレーラーがある場合、skip-checksは最後に記述します。

5.2 重要な注意事項

パスフィルタリング、ブランチフィルタリング、またはコミットメッセージによってワークフローがスキップされた場合、関連するチェックは「Pending」状態のままになります
これらのチェックの成功を必要とするプルリクエストは、マージがブロックされます
スキップ指示はpushとpull_requestイベントにのみ適用され、pull_request_targetなどの他のイベントには適用されません
スキップ指示は、その指示を含むコミットによってトリガーされるワークフロー実行にのみ適用されます

5.3 Gitの設定

デフォルトでは、Gitは連続する改行を自動的に削除します。コミットメッセージを入力したとおりに保持するには、--cleanup=verbatimオプションを使用します。

git commit --cleanup=verbatim -m "変更内容

skip-checks: true"

5.4 マージの注意点

リポジトリが特定のチェックの合格を必須としている場合、スキップ指示を含むコミットではプルリクエストをマージできません。マージするには、スキップ指示を含まない新しいコミットをプッシュする必要があります。

6. アーティファクト管理

ワークフローで生成されたアーティファクト（ビルド成果物、ログ、テスト結果など）は、GitHubによって自動的に保存されます。

6.1 保存期間とカスタマイズ

デフォルトでは、ビルドログとアーティファクトは90日間保存されます。この保存期間は、リポジトリの種類に応じてカスタマイズできます。

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

サインイン済みで、リポジトリへの読み取り権限を持つユーザーは、アーティファクトをダウンロードできます。

手順：

Actionsタブから対象ワークフローを選択
ワークフロー実行の一覧から、目的の実行をクリック
サマリーページの「Artifacts」セクションで、ダウンロードしたいアーティファクトをクリック

6.3 アーティファクトの削除

書き込み権限を持つユーザーは、有効期限前にアーティファクトを削除してストレージを解放できます。

削除方法：

Actionsタブから対象ワークフローを選択
ワークフロー実行の一覧から、目的の実行をクリック
「Artifacts」セクションで、削除したいアーティファクトの横にあるアイコンをクリック

警告: 一度削除したアーティファクトは復元できません。

6.4 個別アーティファクトの保存期間設定

- name: アーティファクトをアップロード
  uses: actions/upload-artifact@v4
  with:
    name: ビルド結果
    path: ./dist
    retention-days: 5

アーティファクトの有効期限確認

APIを使用して、アーティファクトの削除予定日を確認できます。REST APIから返されるexpires_at値を参照してください。

ワークフロー実行削除時の動作

ワークフロー実行を削除すると、関連するすべてのアーティファクトもストレージから削除されます。

7. フォークからのワークフロー承認

パブリックフォークからのプルリクエストによってトリガーされたワークフロー実行は、書き込み権限を持つメンテナーによる手動承認が必要な場合があります。承認要件は、リポジトリ、組織、エンタープライズレベルで設定できます。

7.1 自動削除のルール

30日間承認を待っているワークフロー実行は、自動的に削除されます。

7.2 承認手順

書き込み権限を持つリポジトリメンテナーは、以下の手順でワークフローを承認できます。

リポジトリ名の下にある「Pull requests」タブをクリック
プルリクエスト一覧から、レビューしたいプルリクエストを選択
「Files changed」タブをクリック
プルリクエストで提案された変更内容を検査し、プルリクエストブランチでワークフローを実行しても問題ないか確認
- 特に.github/workflows/ディレクトリ内のワークフローファイルへの変更には注意が必要
ワークフローを実行しても問題ないと判断したら、「Conversation」タブに戻る
「n workflow(s) awaiting approval」セクションで「Approve workflows to run」をクリック

7.3 セキュリティ上の考慮事項

フォークからのプルリクエストは、悪意のある変更を含む可能性があるため、ワークフローファイルの変更内容を慎重にレビューする必要があります。特に以下の点に注意してください。

シークレットへのアクセス
外部サービスへのリクエスト
リポジトリへの書き込み操作
サードパーティアクションの追加や変更

8. まとめ

GitHub Actionsのワークフロー実行管理機能は、CI/CDパイプラインを効率的かつ安全に運用するための包括的なツールセットを提供します。

機能の使い分け

キャッシュ管理: ビルド時間の短縮とストレージコストの最適化
手動実行: 緊急デプロイやアドホックなテスト実行
再実行: 一時的な障害からの迅速なリカバリ
キャンセルと無効化: リソースの無駄な消費を防止
スキップ: ドキュメント更新など、CI/CDが不要な変更への対応
アーティファクト管理: ストレージの効率的な利用
フォーク承認: セキュリティを保ちながらOSSへの貢献を促進

これらの機能を適切に組み合わせることで、チームの生産性を向上させながら、セキュリティとコスト効率を両立できます。Web UI、GitHub CLI、REST APIの3つのインターフェースから操作できるため、自動化スクリプトへの組み込みも容易です。

実務では、まず基本的なワークフロー実行管理から始め、徐々にキャッシュの最適化やアーティファクト管理の自動化を導入していくアプローチが効果的です。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

Tips - ワークフローの"実行"をコントロールする

Tips - ワークフローの"実行"をコントロールする

目次

1. キャッシュ管理

1.1 キャッシュエントリの表示

1.2 キャッシュの削除

1.3 強制削除の実装

2. ワークフローの手動実行

2.1 設定要件

2.2 実行方法

3. ワークフローの再実行

3.1 重要な仕様

3.2 再実行のパターン

3.3 以前の実行結果の確認

4. ワークフローのキャンセルと無効化

4.1 ワークフローのキャンセル

4.2 ワークフローの無効化

5. ワークフロー実行のスキップ

5.1 スキップ指示の方法

5.2 重要な注意事項

5.3 Gitの設定

5.4 マージの注意点

6. アーティファクト管理

6.1 保存期間とカスタマイズ

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

6.3 アーティファクトの削除

6.4 個別アーティファクトの保存期間設定

アーティファクトの有効期限確認

ワークフロー実行削除時の動作

7. フォークからのワークフロー承認

7.1 自動削除のルール

7.2 承認手順

7.3 セキュリティ上の考慮事項

8. まとめ