【Git】タグ完全ガイド｜SemVer設計・GPG署名・git describe・GitHub Actions自動リリース・semantic-release・モノレポ戦略まで

# 軽量タグの場合（コミットそのものが返る）
$ git cat-file -t v0.1-light
commit

# 注釈付きタグの場合（tagオブジェクトが独立で存在）
$ git cat-file -t v1.0.0
tag

# 注釈付きタグのメタ情報
$ git cat-file -p v1.0.0
object 3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b
type commit
tag v1.0.0
tagger Taro Yamada <taro@example.com> 1737859200 +0900

Release 1.0.0 - 初回リリース

# 現在のHEADに注釈付きタグ
git tag -a v1.0.0 -m "Release 1.0.0"

# 過去の特定コミットにタグ
git tag -a v0.9.0 3a8b2c1 -m "Beta release"

# タグメッセージを外部エディタで書く
git tag -a v1.0.0

# GPG署名タグ（推奨）
git tag -s v1.0.0 -m "Signed release 1.0.0"

# 既存タグを強制上書き（非推奨／注意）
git tag -f v1.0.0

# 軽量タグ（ブックマーク用途）
git tag nightly-2026-04-21

# 全タグ
git tag

# パターン指定
git tag -l "v1.*"
git tag -l "v1.0.*"
git tag -l "*-rc.*"     # pre-releaseのみ

# バージョン順で並べる
git tag -l --sort=-v:refname | head -10    # 新しい順

# タグの詳細一覧（メッセージ付き）
git tag -n5

# 含まれるコミットを元にフィルタ
git tag --contains a1b2c3d          # 該当コミットを含むタグ
git tag --no-contains a1b2c3d       # 含まないタグ

# タグ同士の差分
git diff v1.0.0..v1.1.0
git log v1.0.0..v1.1.0 --oneline    # コミット一覧（リリースノート元ネタ）

# タグの全情報（タグメッセージ＋コミット＋diff）
git show v1.0.0

# タグを含むログ表示
git log --tags --oneline --graph

# 特定タグから現在までのコミット
git log v1.0.0..HEAD --oneline

# 2つのタグ間の変更ファイル一覧
git diff --name-only v1.0.0 v1.1.0

# 特定タグだけpush（推奨：意図が明確）
git push origin v1.0.0

# 全タグpush（大規模リポジトリでは避ける）
git push origin --tags

# pushの際にタグも自動でpushする設定
git config --global push.followTags true
# → git pushすると関連タグも自動送信される

# リモートのタグを全部取得
git fetch --tags

# リモートに存在しないローカルタグを削除（整理）
git fetch --prune --prune-tags

# エラー例（リモートのタグとローカルのタグが別物）
$ git fetch
! [rejected]        v1.0.0 -> v1.0.0  (would clobber existing tag)

# 解決：強制的にリモートのタグで上書き
git fetch --tags --force

# または該当タグだけ削除して再取得
git tag -d v1.0.0
git fetch origin tag v1.0.0

# ローカルで削除
git tag -d v1.0.0

# リモートで削除（新しい書き方）
git push origin --delete v1.0.0

# リモートで削除（昔の書き方・現役で動く）
git push origin :refs/tags/v1.0.0

# 両方一気に
git tag -d v1.0.0 && git push origin --delete v1.0.0

# 同じ名前で別コミットに作り直す（ローカル）
git tag -f v1.0.0 a1b2c3d

# リモートに強制push（--forceが必須）
git push origin v1.0.0 --force

# ローカルのreflogから探す
git reflog --all | grep v1.0.0

# コミットハッシュが分かれば復元
git tag -a v1.0.0 a1b2c3d -m "Restore v1.0.0"

# リモートに残っていればfetchで戻る
git fetch origin tag v1.0.0

v<MAJOR>.<MINOR>.<PATCH>

例: v1.2.3
    │ │ └── PATCH : 後方互換のバグ修正
    │ └──── MINOR : 後方互換の機能追加
    └────── MAJOR : 破壊的変更（API互換性が壊れる）

v1.0.0-alpha.1        # アルファ版
v1.0.0-beta.2         # ベータ版
v1.0.0-rc.1           # リリース候補
v1.0.0                # 正式リリース
v1.0.0+20260421       # ビルドメタデータ（順序に影響しない）
v1.0.0-rc.1+exp.sha.5114f85  # pre-release + メタ複合

# SemVerでの並び順
# 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0

# 年.月.パッチ
2026.04.1
v2026.04.1

# 年.リリース番号
2026.3

# Ubuntu風 (YY.MM)
26.04

# 鍵を生成（対話式）
gpg --full-generate-key
# RSA/ED25519 → 4096 → 無期限 or 2年 → 名前・メール入力

# 鍵IDを確認
gpg --list-secret-keys --keyid-format=long
# sec  ed25519/AB12CD34EF567890 ...

# Gitに署名鍵を登録
git config --global user.signingkey AB12CD34EF567890
git config --global tag.gpgSign true  # デフォルトで署名

# 公開鍵をエクスポート（GitHub/GitLabに登録）
gpg --armor --export AB12CD34EF567890

# 署名タグ作成
git tag -s v1.0.0 -m "Signed release 1.0.0"

# 署名付きかどうか確認
git tag -v v1.0.0
# gpg: Good signature from "Your Name <you@example.com>"

# 署名が無いタグは弾く（厳格なリリース時）
if ! git tag -v v1.0.0 2>/dev/null; then
  echo "ERROR: v1.0.0 is not signed" >&2
  exit 1
fi

# 最も近い注釈付きタグを取得
$ git describe
v1.0.0

# タグ以降にコミットがある場合
$ git describe
v1.0.0-3-ga1b2c3d
#  └────┘ └─┘ └───────┘
#   タグ  差分  shortハッシュ

# 軽量タグも対象にする
git describe --tags

# dirty（未コミット変更あり）時は-dirtyを付与
git describe --dirty
# → v1.0.0-3-ga1b2c3d-dirty

# 最初に見つかるタグのみ（matchパターン）
git describe --match "v*" --tags
git describe --exclude "*-rc.*"    # RCを除外

# タグ完全一致（タグが付いていないコミットはエラー）
git describe --exact-match

# Makefile
VERSION := $(shell git describe --tags --always --dirty)

build:
	go build -ldflags "-X main.version=$(VERSION)" ./cmd/myapp

# 実行時確認
$ ./myapp --version
myapp v1.0.0-3-ga1b2c3d-dirty

# package.json scripts
{
  "scripts": {
    "version": "git describe --tags --always > src/version.txt"
  }
}

# または環境変数
VITE_APP_VERSION=$(git describe --tags --always) npm run build

# タグを作ってpush
git tag -a v1.0.0 -m "Release 1.0.0"
git push origin v1.0.0

# GitHubでReleaseを作成（メモを自動生成）
gh release create v1.0.0 --generate-notes

# タイトル・本文を指定
gh release create v1.0.0 \
  --title "v1.0.0 - 初回リリース" \
  --notes "主な変更点..."

# アセットをアップロード
gh release create v1.0.0 \
  --generate-notes \
  dist/myapp-linux-amd64.tar.gz \
  dist/myapp-windows-amd64.zip

# pre-release（RC/ベータ）
gh release create v1.0.0-rc.1 --prerelease --generate-notes

# 下書き
gh release create v1.0.0 --draft

# .github/release.yml
changelog:
  exclude:
    labels:
      - ignore-for-release
  categories:
    - title: "新機能"
      labels:
        - enhancement
    - title: "バグ修正"
      labels:
        - bug
    - title: "その他"
      labels:
        - "*"

name: Release

on:
  push:
    tags:
      - 'v*.*.*'
      - '!v*.*.*-*'   # pre-releaseは別jobで

permissions:
  contents: write   # gh release createに必要

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0      # git describeのためタグ含め全履歴取得

      - name: Get version
        id: version
        run: echo "tag=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT

      - name: Verify signed tag
        run: git tag -v ${{ steps.version.outputs.tag }}

      - name: Build
        run: |
          npm ci
          npm run build

      - name: Create GitHub Release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh release create "${{ steps.version.outputs.tag }}" \
            --generate-notes \
            dist/*.tar.gz

on:
  push:
    tags:
      - 'v*.*.*-rc.*'
      - 'v*.*.*-beta.*'

jobs:
  prerelease:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Create prerelease
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh release create "${GITHUB_REF_NAME}" \
            --prerelease \
            --generate-notes

feat: 新機能を追加            → MINORアップ
fix: バグを修正               → PATCHアップ
docs: ドキュメント変更のみ    → バージョン据え置き
chore: ビルド雑務など         → バージョン据え置き
refactor: リファクタ          → バージョン据え置き

# 破壊的変更（MAJORアップ）
feat!: 新認証方式に変更

feat: 認証を刷新

BREAKING CHANGE: 認証方式を OAuth2 に統一

{
  "scripts": {
    "release": "semantic-release"
  },
  "release": {
    "branches": ["main", { "name": "beta", "prerelease": true }],
    "plugins": [
      "@semantic-release/commit-analyzer",
      "@semantic-release/release-notes-generator",
      "@semantic-release/changelog",
      "@semantic-release/npm",
      "@semantic-release/github",
      [
        "@semantic-release/git",
        {
          "assets": ["CHANGELOG.md", "package.json"],
          "message": "chore(release): ${nextRelease.version} [skip ci]"
        }
      ]
    ]
  }
}

name: Semantic Release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

# Lerna／Changesets系
@myorg/core@1.2.0
@myorg/cli@0.5.3
@myorg/ui@2.0.0-beta.1

# プレフィックスだけ
core-v1.2.0
cli-v0.5.3

# フラット運用（全パッケージ同期）
v2.0.0   # 全パッケージが2.0.0にそろう

# @myorg/core のタグ履歴
git tag -l "@myorg/core@*"

# 最新タグ
git tag -l "@myorg/core@*" --sort=-v:refname | head -1

# describe でcore専用の最近タグ
git describe --match "@myorg/core@*" --tags

# 保護パターン例
v*.*.*           # 全SemVerタグ
v*.*.* & !*-rc.*  # rc除くすべての正式版

# 保護されると:
# - タグの作成は指定ロールのみ
# - タグの削除・force pushが禁止

# Settings → Repository → Protected tags
Tag: v*
Allowed to create: Maintainers

# ダメな例：コミットと一緒にpushしたつもり
git commit -am "Release 1.0.0"
git tag v1.0.0
git push          # ← タグはpushされない！

# 正しい方法
git push origin v1.0.0
# または push.followTagsを有効化しておく
git config --global push.followTags true

# タグをcheckoutするとdetached HEAD
git switch --detach v1.0.0
# → HEAD is now at a1b2c3d Release 1.0.0

# この状態でコミットするとどのブランチにも紐づかない
# → hotfix/パッチリリースしたい場合はブランチを切る
git switch -c hotfix/v1.0.1 v1.0.0

# v1.00 → v1.0.0 に改名したい
# 1) 新しいタグを同じコミットに付ける
git tag -a v1.0.0 v1.00 -m "Release 1.0.0"

# 2) 旧タグをローカル・リモート両方削除
git tag -d v1.00
git push origin --delete v1.00

# 3) 新タグをpush
git push origin v1.0.0

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