actions/checkoutとは｜リポジトリ取得の仕組みと使い方

GitHub Actions のワークフロー YAML を書くとき、ほぼ最初に登場するステップが uses: actions/checkout@v4 や uses: actions/checkout@v7 といった行です。テンプレートからコピーして深く考えずに使っている方も少なくないかもしれません。

しかし、この 1 行が担う責務は決して小さくありません。ランナー上にリポジトリのコードを取り込み、認証情報を持ち回り、post-job で削除します。さらに v7 では、pull_request_target トリガー時にフォーク PR のコードを既定でチェックアウトしないという、セキュリティ既定値の大きな変更が入りました。

無自覚に使っていると、fetch-depth の指定不足で git describe が期待通り動かない、サブモジュールが取れずビルドが失敗する、あるいは fork PR 対応で意図せず脆弱なワークフローを組んでしまう、といった落とし穴に気づかないまま本番運用してしまう可能性があります。

本記事では、GitHub Actions 公式が提供する actions/checkout について、リポジトリ取得の内部的な仕組み、主要な入力パラメータの意味と典型的な使い方、v4 から v7 までの変更点、v7 で導入された fork PR 保護、そして類似アクションとの差分までをドキュメントベースで整理します。

対象は、GitHub Actions を新規導入する方、あるいは既存ワークフローの見直しをしている方です。読み終える頃には、自プロジェクトで採用すべきバージョン・オプション・セキュリティ設計を、根拠を持って選べる状態を目指します。

actions/checkoutとは

actions/checkout は、GitHub 公式（actions 組織）が提供する GitHub Actions 用の公式アクションで、ワークフロー実行時にリポジトリのコードをランナーへチェックアウトするために使われます。GitHub 上の説明では「Action for checking out a repo」と一行で紹介されており、GitHub Actions の事実上ほぼすべてのワークフローで最初に呼び出される標準的なステップです（actions/checkout - GitHub）。

リポジトリの役割

このアクションは、実行された時点で $GITHUB_WORKSPACE 環境変数が指すディレクトリに、対象リポジトリのコードを取り込みます。以降のステップ（ビルド・テスト・デプロイ等）は、この $GITHUB_WORKSPACE 配下のファイルを前提に動作します。actions/checkout を呼ばずに git clone を自前で行うことも技術的には可能ですが、認証トークンの受け渡しや post-job での認証情報削除といった処理を自前で実装する必要が生じます。

基本メタデータ

公開されている GitHub 上のメタデータを整理すると次のとおりです。

出典: actions/checkout - GitHub（2026 年 7 月時点の GitHub API メタデータに基づく）

「ユーティリティ系公式アクション」のスター数として 8,511 は非常に高く、GitHub Actions Marketplace で最も参照されているアクションの 1 つと言えます。ライセンスは MIT で、社内・商用プロジェクトを含め幅広い用途で利用しやすい条件が整っています。

なお README 冒頭には、現在このリポジトリへの外部コントリビュートは受け付けておらず、セキュリティ更新と重大なバグ修正のみに絞って対応が続けられている旨が明記されています。逆に言えば、機能追加は限定的でも、公式によるセキュリティ更新は継続して提供されるアクションだと理解できます。

公式リポジトリへのリンク

一次情報は必ず公式リポジトリを参照するのが確実です。README・Releases・Issues のいずれも次の URL から辿れます。

• 公式リポジトリ: https://github.com/actions/checkout

リポジトリ取得の仕組み

actions/checkout を 1 行書いたときに、内部で何が起きているのかを理解しておくと、パラメータ設計の判断が段違いにやりやすくなります。README の記載を基に、デフォルト動作・認証・フォールバックの 3 点を整理します（出典: actions/checkout - README）。

デフォルト動作: 単一コミット fetch

デフォルトでは、actions/checkout はワークフローをトリガーしたイベントの ref / SHA に対して、単一コミットのみを fetch します。fetch-depth: 1 相当の動作で、履歴を辿らない浅いクローンです。

そのため、git describe --tags や git log のように過去履歴に依存するコマンドは、デフォルト設定では意図した結果を返さないことがあります。全履歴が必要な場合は後述する fetch-depth: 0 を指定します。

チェックアウト先の ref はイベントに応じて自動的に決まります。GitHub Actions のトリガーイベントごとにどの ref・SHA が使われるかは、GitHub Actions の公式ドキュメントに整理されています（Events that trigger workflows - GitHub Docs）。

認証（token / SSH key）とクレデンシャルの持ち回り

actions/checkout は既定でワークフロー実行に紐づく github.token（GITHUB_TOKEN）を使って認証します。認証情報は git config に保持され、後続の git fetch / git push などが同一ワークスペース内で追加の認証設定なしに動作するようになっています。

保持されたクレデンシャルはジョブ終了時の post-job フェーズで削除されます。v6 以降ではこの保持先が .git/config から $RUNNER_TEMP 配下の別ファイルに変更され、クレデンシャルの分離がより強化されています（README の「Checkout v6」セクションを参照）。

トークンを明示的に指定したい場合は token 入力に PAT（Personal Access Token）や secrets.GH_PAT を渡します。SSH 鍵での認証を使いたい場合は ssh-key 入力を使うことで、リポジトリ URL が自動的に SSH 形式に変換されます。

Git 2.18+ が無いときの REST API フォールバック

actions/checkout は基本的にランナー上の git コマンドを利用して動作しますが、PATH 上に Git 2.18 以上が見つからない環境では、GitHub の REST API 経由でファイルを取得するフォールバックが実装されています。GitHub がホストするランナーには基本的に十分なバージョンの Git が同梱されているため、これは主に self-hosted runner でシンプルなイメージを使うケースを想定した挙動です。

主な入力パラメータと典型的な使い方

actions/checkout は多数の入力パラメータを持ちます。README の Usage セクション末尾に全項目が並んでいますが、その中で頻出のものを抜粋します（出典: actions/checkout - Usage / Scenarios）。

主要パラメータ一覧

以下、代表的なシナリオを README の記述に沿って整理します。

全履歴を取得したい（fetch-depth: 0）

git describe や過去差分を扱いたい場合、fetch-depth を 0 にして全履歴を取得します。README の Scenarios セクションに次の例が示されています。

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

出典: actions/checkout - Scenarios（Fetch all history for all tags and branches）

タグ情報も明示的に取りたい場合は fetch-tags: true を併用します。取得サイズは増えるため、履歴を必要としないビルドではデフォルトの 1 のままにするのが原則です。

サブモジュールを含めたい（submodules: true / recursive）

サブモジュールを持つリポジトリでは、submodules 入力を指定しない限りサブモジュールがチェックアウトされません。次のように書きます。

- uses: actions/checkout@v4
  with:
    submodules: true

出典: actions/checkout - Scenarios（Checkout submodules）

true は直下のサブモジュールのみを、recursive はネストされたサブモジュールも含めて取得します。プライベートなサブモジュールを含む場合、github.token の権限では取得できないケースがあり、その場合は ssh-key を指定するか、サブモジュール取得に必要な権限を持つ PAT を token に渡します。

部分取得したい（sparse-checkout）

モノレポの一部だけを取得したい場合、sparse-checkout にパターンを列挙します。README には次の例が示されています。

- uses: actions/checkout@v4
  with:
    sparse-checkout: |
      cmd
      pkg

出典: actions/checkout - Scenarios（Sparse checkout only specific directories）

sparse-checkout-cone-mode の既定値は true で、Git のスパースチェックアウトの cone-mode に沿った挙動になります。より柔軟な部分クローンを行いたい場合は filter 入力（部分クローンの --filter オプション相当）も検討候補になります。

複数リポジトリを並列 checkout（path）

異なるリポジトリを同じジョブ内でチェックアウトしたい場合、path 入力で $GITHUB_WORKSPACE 配下の相対ディレクトリを分けます。README の Scenarios セクションに以下の例があります。

- uses: actions/checkout@v4
  with:
    path: main

- uses: actions/checkout@v4
  with:
    repository: my-org/my-tools
    path: my-tools

出典: actions/checkout - Scenarios（Checkout multiple repos (side by side)）

main と my-tools という 2 つのディレクトリに、それぞれ別のリポジトリがチェックアウトされます。プライベートリポジトリを追加でチェックアウトする場合は、token に必要な権限を持つ PAT を渡します。

v4 → v7 の主要な変更点とバージョン選択の判断軸

actions/checkout は、破壊的変更を含む場合にメジャーバージョンを引き上げる運用が続いています。ここでは README と Releases の記載を基に v4 から v7 までの変更点をまとめます（一次ソース: actions/checkout - Releases）。

v4（現行系の直前系列）

• リポジトリを $GITHUB_WORKSPACE にチェックアウトする、現行の挙動を確立したメジャーバージョン
• デフォルトで単一コミットのみを fetch し、fetch-depth: 0 で全履歴を取得
• 認証トークンはローカル git config に保持され、post-job で削除
• Git 2.18+ が PATH にない場合は REST API 経由のフォールバックが動作します

出典: README「Checkout v4」セクション（actions/checkout）

v5（node24 ランタイム化・最小 Runner バージョン）

• Node.js ランタイムを node24 に更新
• 最小 Actions Runner バージョンとして v2.327.1 以上が必要

Node.js 実装のアクションはランナー内蔵の Node.js で動作します。ランナーが古すぎると v5 が想定する node24 が使えないため、Runner バージョンの前提が引き上げられています。self-hosted runner を使っている環境では、Runner のバージョンを事前に確認する必要があります。

出典: README「Checkout v5」セクション

v6（persist-credentials の $RUNNER_TEMP 分離）

• 認証情報の格納先を .git/config から $RUNNER_TEMP 配下の別ファイルに変更
• ワークフロー側の変更は不要で、git fetch / git push 等は従来通り動作します
• Docker コンテナアクション内から認証付き git コマンドを実行する場合、Actions Runner v2.329.0 以上が必要

これはセキュリティ観点の内部変更で、既存の YAML を触らずに恩恵を受けられる系のアップデートです。ただしコンテナ内から git 認証を使う特殊構成では Runner バージョンの前提が変わるため、そのようなワークフローを持っている場合は Runner 更新を確認します。

出典: README「Checkout v6」セクション

v7（fork PR チェックアウトのデフォルト拒否・ESM 化）

• pull_request_target トリガーおよび workflow_run トリガー時、フォーク PR のコードをデフォルトで checkout しません
• オプトイン用に allow-unsafe-pr-checkout: true を新設
• 依存関係の ESM 化を含むセキュリティ更新

これは、これまで多くのプロジェクトで問題視されてきた「pwn request」型の脆弱性への正面対応です。詳細は次の章で扱います。

出典: README「Checkout v7」セクション

採用時のバージョン固定戦略

actions/checkout に限らず、GitHub Actions を安全に運用するうえで、バージョンをどう固定するかは避けて通れない設計判断です。主に 3 つの選択肢があります。

• メジャータグ固定（例: actions/checkout@v4）: 記述が簡潔で、公式のセキュリティ更新を自動的に取り込めます。ただし、そのメジャーの範囲内で挙動が変わるリスクは常に存在します
• SHA 固定（例: actions/checkout@a5ac7e...）: 完全に不変。第三者による Git タグの再付与などのリスクを排除できますが、更新は明示的に SHA を書き換える必要があります
• Dependabot による自動更新: GitHub の Dependabot をリポジトリで有効化すれば、actions/checkout を含む GitHub Actions の更新 PR が自動で作成されます。SHA 固定と組み合わせるのが定石

セキュリティ要件が厳しいプロジェクトでは SHA 固定 + Dependabot、比較的緩やかなプロジェクトではメジャータグ固定、というのが典型的な運用です。いずれの場合も、Releases ページで v4 → v7 の差分と自プロジェクトへの影響を確認したうえでバージョンを選ぶことをおすすめします。

セキュリティ設計と fork PR 保護

v7 で導入された「フォーク PR のデフォルト拒否」は、actions/checkout の設計思想を大きく前進させる変更です。この背景と、オプトインする場合の判断軸を整理します。

なぜ fork PR コード実行が危険か（pwn request の要点）

pull_request トリガーは、フォーク元の書き込み権限を持たない環境で動くため比較的安全です。一方 pull_request_target と workflow_run は、ベースリポジトリ（元リポジトリ）側の権限で動作するトリガーです。ワークフローには GITHUB_TOKEN の書き込み権限やリポジトリシークレットへのアクセスが与えられます。

ここでフォーク PR のコードを何気なくチェックアウトして実行すると、フォーク側の任意の攻撃コードがベースリポジトリの権限で動くことになります。これが俗に「pwn request」と呼ばれる脆弱性パターンです。詳細は GitHub 公式の解説記事に整理されています（Keeping your GitHub Actions and workflows secure Part 1: Preventing pwn requests）。

pull_request_target / workflow_run の既定挙動（v7 以降）

v7 以降、actions/checkout は pull_request_target および workflow_run トリガー配下で走ったときに、フォーク PR のコードを既定ではチェックアウトしません。これにより、危険な挙動を「明示的に許可しないと発生しない」状態に反転させています。安全側のデフォルト設計です。

pull_request トリガーは影響を受けません。同じリポジトリ内のブランチ間 PR も、フォーク由来ではないため従来通りの挙動になります。

オプトインする場合の要件と代替設計

どうしてもフォーク PR のコードを取得して何らかの処理を行いたい場合、allow-unsafe-pr-checkout: true を明示的に指定します。名前のとおり「unsafe」と冠されており、公式が安易な有効化を推奨していないことは明らかです。

オプトインを検討する前に、次のような代替設計を検討することを強くおすすめします。

• ワークフロー分離: 権限を必要とする処理は pull_request_target のジョブで実施し、フォーク PR のコード実行はしません。あるいは、フォーク PR のコード実行は pull_request トリガー側の（権限が絞られた）ジョブに閉じ込めます
• シークレット・トークンの最小権限化: どうしてもフォーク PR のコードを扱うワークフローでは、permissions: を最小限に絞り、シークレットを渡しません
• 手動承認ゲート: environments の必須レビュアー機能などを併用し、フォーク PR で権限を持つジョブが走る前にメンテナのレビューを挟みます

参考ガイド: https://gh.io/securely-using-pull_request_target

推奨パーミッション contents: read

README の末尾では、多くのユースケースにおいて contents: read パーミッションのみで actions/checkout が動作すると案内されています。ジョブレベルで permissions: を明示すると、意図しない書き込み権限の付与を防げます。

permissions:
  contents: read

出典: actions/checkout - README（Recommended permissions）

類似アクションとの比較と選び方

actions/checkout にはいくつかの類似・代替アクションが存在します。どのような状況で本家以外を検討すべきかを整理します。

比較表

参考:

• actions/checkout
• taiki-e/checkout-action

actions/checkout を選ぶべきケース

• GitHub ホスト型ランナー（ubuntu-latest 等）を使う標準的な CI/CD
• サブモジュール・LFS・sparse-checkout など、幅広い機能を必要とする場合
• fork PR の安全な扱いなど、セキュリティ既定値を公式のアップデートに委ねたい場合
• 情報量の多さ・トラブルシューティングの容易さを重視する場合

つまり、特別な理由がなければ本家 actions/checkout を選ぶのが原則です。GitHub Actions Marketplace で最も広く使われているアクションであり、日本語・英語ともに事例が豊富で、公式によるセキュリティ更新の継続提供もアナウンスされています。

taiki-e/checkout-action を検討すべきケース

• Node.js インタプリタが利用できない self-hosted runner（例: Node.js を含まない最小構成のコンテナ）
• 認証トークンをディスクに書き込まない設計を強く求めるコンプライアンス要件がある場合
• 本家 actions/checkout の高機能なオプション（LFS・sparse・submodules 等）を必要とせず、最小限の checkout で足りる場合

同様に myci-actions/checkout などのコンポジット実装も、「Node.js に依存しない」という一点でメリットがあります。ただし、機能範囲は本家に大きく劣り、fork PR 保護のようなセキュリティ既定値も公式のアップデートに追随するとは限りません。総合的には「特殊環境向けの代替」という位置づけになります。

採用判断のポイント

ここまで整理した内容を踏まえて、自プロジェクトで actions/checkout を採用する際に確認すべきチェック項目をまとめます。裏テーマは「初見エンジニアの意思決定支援」であり、無自覚なコピペではなく根拠のある選択を目指します。

採用チェックリスト

これらを一つずつ埋めていけば、少なくとも「なぜこのバージョン・このオプションを選んだのか」を後から説明できる状態になります。

どういう場合に代替を検討するか

以下のいずれかに当てはまる場合は、taiki-e/checkout-action のような代替を検討する価値があります。

• Node.js ランタイムを持たない特殊なコンテナで CI を走らせる必要があります
• 認証情報を一切ディスクに書き込まない要件が明示されています
• 本家の高機能オプションが不要で、最小の checkout だけあれば十分

逆に、標準的な GitHub ホスト型ランナー、あるいは通常の self-hosted runner を使う限り、代替を積極的に選ぶ理由は多くありません。

まとめ

本記事では、GitHub Actions の公式アクション actions/checkout について、ドキュメントベースで次の観点を整理しました。

• 役割: $GITHUB_WORKSPACE へリポジトリのコードを取り込み、認証情報を持ち回り、post-job で削除する標準ステップ。TypeScript で実装され、MIT ライセンスで公開されています（スター数 8,511・フォーク数 2,606・最終更新 2026-07-17 時点。archived=false / fork=false の GitHub 公式本家リポジトリ）
• 仕組み: デフォルトで単一コミット fetch。fetch-depth: 0 で全履歴。Git 2.18+ が無ければ REST API フォールバック
• 主要パラメータ: ref / fetch-depth / submodules / sparse-checkout / path / token / ssh-key / allow-unsafe-pr-checkout など。README の Usage / Scenarios に典型例がまとまっています
• v4 → v7 の変更点: v5 は node24 化、v6 はクレデンシャルの $RUNNER_TEMP 分離、v7 は fork PR のデフォルト拒否と ESM 化。バージョン固定はメジャータグまたは SHA + Dependabot が定石
• セキュリティ: pull_request_target / workflow_run × フォーク PR は要注意。v7 のデフォルト拒否を活かし、allow-unsafe-pr-checkout の有効化は代替設計を尽くしたうえで判断します
• 代替: taiki-e/checkout-action などは Node.js を持たない環境や、認証情報の残存を極力避けたい場合の選択肢。通常は本家 actions/checkout が第一候補

一次情報は常に公式リポジトリと GitHub Actions 公式ドキュメントを参照するのが確実です。

• 公式リポジトリ: https://github.com/actions/checkout
• Releases（v4 〜 v7 の差分の一次ソース）: https://github.com/actions/checkout/releases
• GitHub Actions 公式ドキュメント（トリガーイベント）: https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
• pull_request_target の安全な利用ガイド: https://gh.io/securely-using-pull_request_target

ワークフロー YAML の先頭に uses: actions/checkout@... と書くとき、そこには「どのバージョンを固定し、どのオプションを有効化し、fork PR をどう扱うか」という一連の意思決定が含まれています。本記事の観点整理が、その判断を自プロジェクトの文脈で行うための土台になれば幸いです。