GitHub Actionsでorphanブランチを使ってファイルを保存・取得する方法

本記事は、GitHub Actions Advent Calendar 2025の19日目の記事です。

はじめに

GitHub Actionsで生成されたファイルを保存する代表的な手段として、GitHub ActionsのArtifactsや、S3などの外部ストレージサービスの利用が挙げられます。しかし、Artifactsや外部ストレージには、用途によってはいくつかの制約や不便さを感じる場面があります。

そこで本記事では、orphanブランチを利用してファイルを保存・取得するというアプローチと、それをGitHub Actionsから利用する方法を紹介します。

親を持たないorphanブランチ

Gitでは git switch --orphan <branch-name> などのコマンドを使うことで、親を持たない空のブランチ（orphanブランチ）を作成できます。

通常のブランチとは異なり、履歴が完全に分離されているのが特徴です。そのため、GitHubにorphanブランチをプッシュしていたとしても、後でブランチを削除すれば、その履歴ごとリポジトリから取り除かれます。これにより、不要になった生成物をリポジトリから取り除き肥大化を防ぐことができます¹。

この性質を利用することで、orphanブランチを生成物の保存場所として扱えます。

ファイル管理にorphanブランチを使う利点と欠点

Artifacts機能は手軽で便利ですが、ワークフロー実行単位で管理されるため、ワークフローをまたいでファイルを参照することが難しいという側面があります。また、保存期間にも制限があります。さらに、プルリクエストの説明文などからファイルを直接参照することはできません。

外部ストレージサービスを利用する場合、費用面や認証情報の管理が課題になることがあります。利用する用途や環境によっては、やや大げさに感じられることもあります。また、GitHubだけで完結しない点もデメリットです。

これらと比べると、orphanブランチはGitHub上で完結し、ワークフローに依存せずにファイルを管理できます。また、保存期間に制限がない点も利点です。さらに、通常のブランチと同様に raw.githubusercontent.com や raw=true を利用してファイルを参照できるため、プルリクエストの説明文に直接画像を埋め込むことも可能です。

一方で、orphanブランチを利用する場合、ブランチの管理は利用者側で行う必要があります。ブランチ数が増えるとリポジトリの管理が煩雑になり、不要なブランチを削除し忘れると、結果としてリポジトリが肥大化する恐れがあります。また、大容量ファイルの保存には適していません。

例えば、実装前と実装後のUIのスクリーンショットをorphanブランチに保存し、プルリクエストの説明文で比較表示するといった使い方が考えられます。スクリーンショットに限らず、実装前後のカバレッジやパフォーマンスレポートなどを保存・比較する用途にも適しています。

作成したGitHub Actionsの紹介

ファイルの保存・取得・削除を行うたびに、git switch --orphan や git add、git commit、git push といったコマンドをワークフローに記述するのは手間がかかります。

そこで、これらの処理をまとめて行うGitHub Actionsを作成しました。

daiji256/upload-to-orphan-branch

ワークフロー内で生成されたファイルを、指定したorphanブランチにコミットしてプッシュするActionです。

以下は、outputs-branch-name というorphanブランチに、**/bar を除いた dir 配下のファイルを保存する例です。

- uses: daiji256/upload-to-orphan-branch@v1
  with:
    branch: outputs-branch-name
    path: |
      dir
      !**/bar

daiji256/download-from-orphan-branch

指定したブランチからファイルを取得するActionです。別のワークフローで事前に保存したファイルを再利用できます。

以下は、outputs-branch-name というブランチからファイルを取得し、dir に展開する例です。

- uses: daiji256/download-from-orphan-branch@v1
  with:
    branch: outputs-branch-name
    path: dir

daiji256/delete-orphan-branch

不要になったorphanブランチを削除するためのActionです。前述のリポジトリ肥大化を防ぐためにも、生成物ごとにブランチを作成する運用では、定期的なクリーンアップが重要です。

以下は、orphan-output- で始まるブランチのうち、7日以上前に作成されたものを削除する例です。

- uses: daiji256/delete-orphan-branch@v1
  with:
    branch-regex: orphan-output-.*
    older-than-seconds: 604800 # 7 days

現状の課題と今後の改善

現状の実装にはいくつか課題があります。Linux環境での動作確認に留まっている点や、gitコマンド失敗時などのエラーハンドリングが十分ではありません。

今後、TypeScriptでの再実装や、macOS・Windowsを含めた環境での動作確認、エラーハンドリングおよびログ出力の強化を進めていきたいと考えています²。

おわりに

GitHub Actionsの中だけで生成物を扱い、後から参照できる形で残したい場合には、orphanブランチを利用する方法は有効な選択肢です。

用途と制約を理解した上で、orphanブランチを活用したファイル管理を検討してみてください。また、今回紹介したGitHub Actionsも、その一助になれば幸いです。

参考文献

• Git - git-switch Documentation
• GitHub Actions documentation - GitHub Docs
• daiji256/upload-to-orphan-branch
• daiji256/download-from-orphan-branch
• daiji256/delete-orphan-branch
• Orphan Branch Upload / Download / Delete Examples
• Daiji256/android-showcase/.github/workflows/unit-test.yml

1. ブランチ削除後すぐに完全に消えるわけではなく、git gc が実行されるまでは内部にデータが残ります。頻繁に大容量ファイルを追加・削除する運用では注意が必要です。 ↩

2. やる気と時間があれば、という意味です。 ↩