🐙

GitHub Actionsで「特定のタグをプッシュした時」をトリガーにしてCI/CDを動かす

に公開
Git
GitHub
GitHub Actions
tech

GitHub Actionsで「特定のタグをプッシュした時」をトリガーにしてCI/CDを動かすのは、リリース自動化の王道パターンです。

一般的には、**セマンティックバージョニング（v1.0.0など）**のタグをトリガーにすることが多いです。以下に、GitHub Actionsの設定例と、それに対応するGitコマンドをまとめました。

1. GitHub Actionsの設定（YAML）

まず、.github/workflows/release.yml などに、タグがプッシュされた時のみ実行されるトリガーを記述します。

name: Release CI/CD

on:
  push:
    tags:
      - 'v*' # "v"から始まるタグ（v1.0, v2.1.0など）がプッシュされた時に実行

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build and Deploy
        run: |
          echo "Deploying version ${GITHUB_REF_NAME}"
          # ここにビルドやデプロイのコマンドを書く

2. 実行するためのGitコマンド例

ローカルで作業が終わった後、タグを付けてGitHubに送信する手順です。

基本的な流れ

最も一般的な「軽量タグ（Lightweight tag）」を使用する方法です。

# 1. 変更をコミットする
git add .
git commit -m "Release version 1.0.0"

# 2. タグを付ける（例: v1.0.0）
git tag v1.0.0

# 3. タグをGitHubにプッシュする（これがActionを起動させます）
git push origin v1.0.0

注釈付きタグ（推奨）

リリースノートなどの情報をタグに含めたい場合は「注釈付きタグ（Annotated tag）」を使います。

# メッセージ付きでタグを作成
git tag -a v1.0.0 -m "Release 1.0.0: Update new features"

# プッシュ
git push origin v1.0.0

3. よく使う便利なコマンド

操作 コマンド
全てのタグを一括プッシュ git push origin --tags
タグを間違えたので削除（ローカル） git tag -d v1.0.0
タグを間違えたので削除（リモート） git push origin :v1.0.0
タグの一覧を確認 git tag

💡 ヒント

注意点

**「git push origin [タグ名] だけを実行した場合、タグが指しているコミット自体はリモートに送られますが、ブランチ（mainなど）のポインタは進まない」**という挙動です。

少し紛らわしい部分ですので、整理して解説しますね。

1. コミット（データ）はプッシュされる

Gitのタグは特定のコミットに対する「別名（しおり）」のようなものです。
git push origin v1.0.0 を実行すると、Gitは以下のものをセットで送信します。

  • タグそのもの
  • そのタグが指し示しているコミット内容（ファイルの実体や履歴）

そのため、GitHub Actions側で actions/checkout を使えば、そのタグ時点のコードを正しく取得してビルドやデプロイを行うことができます。

2. 「ブランチの更新」はされない

ここが混乱しやすいポイントです。
git push origin v1.0.0 をしても、GitHub上の main ブランチなどの先頭（HEAD）は更新されません。

図解イメージ

  • ローカル: main ブランチが コミットA を指していて、そこに v1.0.0 タグを付けた。
  • タグのみプッシュ: GitHub上では v1.0.0 というタグから コミットA の中身は見れるが、main ブランチはまだ古いコミットを指したままになる。

3. 推奨されるワークフロー

CI/CDを確実に、かつ履歴を綺麗に管理するためには、以下の2ステップでプッシュするのが一般的です。

# 1. まずブランチの変更をプッシュ（mainブランチを最新にする）
git push origin main

# 2. 次にタグをプッシュ（これでCI/CDがトリガーされる）
git push origin v1.0.0

なぜこの順番が良いのか？

GitHub Actionsでデプロイが走った際、そのコードが「どのブランチに含まれているものか」が明確になっていないと、後から履歴を追うのが難しくなるためです。

まとめ

  • コミット内容: プッシュされる（Actionsは動く）。
  • ブランチの先頭: 更新されない（GitHub上のブランチ表示は古いまま）。

Discussion