golang-continuous-integration

ペルソナ： Go の DevOps エンジニアです。CI を品質ゲートとして捉え、パイプラインの判断はすべて、ビルド速度、シグナルの信頼性、セキュリティ態勢を基準に評価します。

モード：

• セットアップ — プロジェクトに初めて CI を追加する場合：まずクイックリファレンス表を確認し、次の順序でワークフローを生成します：テスト → リント → セキュリティ → リリース。各 GitHub Action では、最新の安定したメジャーバージョンを優先します。
• 改善 — 既存のパイプラインを監査または拡張する場合：まず現在のワークフローファイルを読み、クイックリファレンス表と照らし合わせて不足点を特定してから、既存のステップと重複しない、対象を絞った追加を提案します。

依存関係：

• goreleaser：go install github.com/goreleaser/goreleaser/v2@latest
• gh：brew install gh

Go の継続的インテグレーション

GitHub Actions を使用して、Go プロジェクト向けの本番環境に対応した CI/CD パイプラインを構築します。

アクションのバージョン

以下の例に記載されているバージョンは参考用であり、古くなっている可能性があります。GitHub Actions は頻繁にリリースされるため、各アクション（actions/checkout、actions/setup-go、golangci/golangci-lint-action、codecov/codecov-action、goreleaser/goreleaser-action など）の現在のメジャーバージョンは、ここに記載されているものと異なる場合があります。

クイックリファレンス

ステージ	ツール	目的
テスト	go test -race	単体テスト＋データ競合検出
カバレッジ	codecov/codecov-action	カバレッジのレポート
リント	golangci-lint	包括的なリント
Vet	go vet	組み込みの静的解析
SAST	gosec、CodeQL、Bearer	セキュリティ静的解析
脆弱性スキャン	govulncheck	既知の脆弱性の検出
Docker	docker/build-push-action	マルチプラットフォームのイメージビルド
依存関係	Dependabot / Renovate	依存関係の自動更新
リリース	GoReleaser	バイナリの自動リリース
AI レビュー	Claude Code / Copilot	AI による PR レビュー

---

テスト

.github/workflows/test.yml — test.yml を参照

Go のバージョンマトリックスは go.mod に合わせて調整します。

go 1.23   → matrix: ["1.23", "1.24", "1.25", "1.26", "1.27", "stable"]
go 1.24   → matrix: ["1.24", "1.25", "1.26", "1.27", "stable"]
go 1.25   → matrix: ["1.25", "1.26", "1.27", "stable"]
go 1.26   → matrix: ["1.26", "1.27", "stable"]
go 1.27   → matrix: ["1.27", "stable"]

ある Go バージョンで失敗しても、ほかのバージョンの実行がキャンセルされないように、fail-fast: false を使用します。

Go 1.27 では、Darwin の最小対応バージョンが macOS 13（Ventura）に引き上げられます。macos-latest／macos-14 以降のランナーには影響しません。プロジェクトで引き続き必要な場合に限り、古い macos-12 ランナーを固定してください。その場合、Go 1.27 のツールチェーンではビルドできなくなることに注意してください。

テストフラグ：

• -race：CI では、必ず -race フラグを付けてテストを実行します（データ競合を検出します。Go では未定義動作につながります）。
• -shuffle=on：テストの実行順序をランダム化して、テスト間の依存関係を検出します。
• -coverprofile：カバレッジデータを生成します。
• git diff --exit-code：go mod tidy によって変更が生じた場合に失敗します。

カバレッジの設定

CI ではコードカバレッジのしきい値を適用することが推奨されます。リポジトリのルートにある codecov.yml でしきい値を設定してください。codecov.yml を参照してください。

---

統合テスト

.github/workflows/integration.yml — integration.yml を参照

テストキャッシュを無効にするには -count=1 を使用します。キャッシュされた結果によって、不安定なサービスとのやり取りが見過ごされる可能性があります。

---

リント

golangci-lint は、すべての PR で CI 内で必ず実行します。.github/workflows/lint.yml — lint.yml を参照してください。

golangci-lint の設定

プロジェクトのルートに .golangci.yml を作成します。推奨設定については、samber/cc-skills-golang@golang-lint スキルを参照してください。

---

セキュリティと SAST

.github/workflows/security.yml — security.yml を参照

CI では govulncheck を必ず実行してください。汎用的な CVE スキャナーとは異なり、プロジェクトが実際に呼び出すコードパスにある脆弱性のみを報告します。

• CodeQL の結果は、リポジトリの Security タブに表示されます。
• Bearer は、機密データのフローに関する問題の検出に優れています。

CodeQL の設定

.github/codeql/codeql-config.yml を作成して、拡張セキュリティクエリスイートを使用します — codeql-config.yml を参照してください

利用可能なクエリスイート:

• default: 標準のセキュリティクエリ
• security-extended: 精度がやや低い追加のセキュリティクエリ
• security-and-quality: セキュリティクエリに加えて、保守性と信頼性のチェック

コンテナイメージのスキャン

プロジェクトが Docker イメージを生成する場合、Trivy によるコンテナスキャンが Docker ワークフローに含まれています — docker.yml を参照してください

---

依存関係の管理

Dependabot

.github/dependabot.yml — dependabot.yml を参照してください

マイナー/パッチ更新は 1 つの PR にグループ化されます。メジャー更新は破壊的変更を含む可能性があるため、個別の PR になります。

Dependabot の自動マージ

.github/workflows/dependabot-auto-merge.yml — dependabot-auto-merge.yml を参照してください

セキュリティ警告: このワークフローには contents: write と pull-requests: write が必要です — これらは PR のマージやリポジトリの内容の変更を可能にする昇格された権限です。if: github.actor == 'dependabot[bot]' ガードにより、実行は Dependabot のみに制限されます。このガードを削除しないでください。github.actor のチェックは完全に偽装不可能ではないことに注意してください — ブランチ保護ルールが真の安全網です。ブランチ保護が設定されていることを確認してください（リポジトリのセキュリティ設定を参照）。必須のステータスチェックと必須の承認を設定することで、ワークフローをトリガーしたのが誰であっても、すべてのチェックが通過した後にのみ自動マージが成功するようになります。

Renovate (代替)

Renovate は Dependabot よりも成熟した、設定可能な代替手段です。自動マージ、グループ化、スケジューリング、正規表現マネージャー、モノレポを意識した更新をネイティブにサポートしています。Dependabot が制限的すぎると感じる場合、Renovate が最適な選択肢です。

Renovate GitHub App をインストールし、リポジトリのルートに renovate.json を作成します — renovate.json を参照してください

Dependabot に対する主な利点:

• gomodTidy: 更新後に自動的に go mod tidy を実行します
• ネイティブな自動マージ: 別途ワークフローは不要です
• 優れたグループ化: PR をグループ化するためのより柔軟なルール
• 正規表現マネージャー: Dockerfile や Makefile などのバージョンを更新できます
• モノレポのサポート: Go ワークスペースとマルチモジュールリポジトリを処理します

---

リリースの自動化

GoReleaser はバイナリのビルド、チェックサム、GitHub Releases を自動化します。設定はプロジェクトの種類によって大きく異なります。

リリースワークフロー

.github/workflows/release.yml — release.yml を参照してください

セキュリティ警告: このワークフローには GitHub Releases を作成するために contents: write が必要です。タグのプッシュ（tags: ["v*"]）に制限されているため、プルリクエストやブランチのプッシュによってトリガーされることはありません。リポジトリへのプッシュアクセスを持つユーザーのみがタグを作成できます。

CLI/プログラム向けの GoReleaser

プログラムにはクロスコンパイルされたバイナリ、アーカイブ、およびオプションで Docker イメージが必要です。

.goreleaser.yml — goreleaser-cli.yml を参照してください

ライブラリ向けの GoReleaser

ライブラリはバイナリを生成しません — 変更履歴を含む GitHub Release のみが必要です。ビルドをスキップする最小限の設定を使用します。

.goreleaser.yml — goreleaser-lib.yml を参照してください

ライブラリの場合、GoReleaser は必要ないかもしれません — UI または gh release create で作成するシンプルな GitHub Release で多くの場合十分です。

モノレポ/マルチバイナリ向けの GoReleaser

リポジトリに複数のコマンド（例: cmd/api/、cmd/worker/）が含まれる場合。

.goreleaser.yml — goreleaser-monorepo.yml を参照してください

Docker のビルドとプッシュ

Docker イメージを生成するプロジェクト向けです。このワークフローはマルチプラットフォームイメージをビルドし、SBOM と来歴の証明書を生成して、GitHub Container Registry（GHCR）と Docker Hub の両方にプッシュします。また、Trivy によるコンテナスキャンも含まれます。

.github/workflows/docker.yml — docker.yml を参照してください

セキュリティに関する警告： 権限はジョブごとに設定されています。container-scan ジョブに付与されるのは contents: read と security-events: write のみです。一方、docker ジョブには（GHCR へのプッシュ用の）packages: write と、（来歴／SBOM の署名用の）attestations: write および id-token: write が付与されます。これにより、スキャンジョブが侵害されてもイメージをプッシュできないようにしています。プルリクエストでは push フラグが false に設定されるため、信頼できないコードがイメージを公開することはありません。DOCKERHUB_USERNAME と DOCKERHUB_TOKEN のシークレットは、リポジトリのシークレット設定で構成する必要があります。認証情報をハードコードしないでください。

主な詳細：

• QEMU + Buildx：マルチプラットフォームビルド（linux/amd64,linux/arm64）に必要です。不要なプラットフォームは削除してください。
• PR での push: false：プルリクエストではイメージをビルドしますが、プッシュはしません。これにより、信頼できないコードを公開せずに Dockerfile を検証できます。
• メタデータアクション：セマンティックバージョンタグ（v1.2.3 → 1.2.3、1.2、1）、ブランチタグ（main）、SHA タグを自動的に生成します。
• 来歴 + SBOM：provenance: mode=max と sbom: true により、サプライチェーンの証明書を生成します。これには attestations: write と id-token: write の権限が必要です。
• 2 つのレジストリ：GHCR には GITHUB_TOKEN を使ってプッシュします（追加のシークレットは不要）。Docker Hub には DOCKERHUB_USERNAME と DOCKERHUB_TOKEN のシークレットが必要です。不要な場合は、Docker Hub のログイン処理とイメージの行を削除してください。
• Trivy：ビルドしたイメージを CRITICAL および HIGH の脆弱性についてスキャンし、結果を Security タブにアップロードします。
• イメージ名とレジストリはプロジェクトに合わせて変更してください。GHCR のみを使用する場合は、Docker Hub のログイン手順と images: から docker.io/ の行を削除してください。

---

リポジトリのセキュリティ設定

リポジトリのセキュリティ設定（ブランチ保護、ワークフローの権限、シークレット、環境）は CI パイプラインのセキュリティ基盤となります。詳しくは repo-security.md に記載されています。

---

AI 主導のコードレビュー

従来の静的解析に加えて、AI エージェントを PR のレビュアーとして追加します。このスキルプラグインを読み込むと、エージェントはレビュー領域に応じた Go スキルを適用し、リンターでは検出できないアーキテクチャの逸脱、ロジックのバグ、エラーコンテキストの不足、並行処理の危険性を検出します。

コストに関する注意： AI レビューエージェントは PR ごとに並行して実行されます。コストを抑えるには、不要なジョブを削除するか、PR のトリガーフィルターを特定のブランチのみに絞ってください。

以下の各小節は、特定のレビュアーを対象とした生成アーティファクトです。リンク先のアセットファイルは開発者のローカルハーネスではなく CI ランナー上で実行されるため、ツール名と権限フラグは、機能を説明する文章ではなく、意図的に文字どおりに記述されています。

Claude Code

.github/workflows/ai-review.yml — claude-code-review.yml を参照してください

このワークフローは並列ジョブを実行します。各ジョブは、レビュー領域と優先度のセットに応じて範囲が設定されています。

ジョブ	領域	優先度
quality	コードスタイル、命名、ドキュメント、デザインパターン	提案優先
correctness	エラー処理、コードの安全性、並行処理	ブロック優先
security	セキュリティ、依存関係	ブロック優先
quality-depth	テスト、パフォーマンス、オブザーバビリティ、モダナイズ	混合

プロジェクトによっては、追加で次のスキルも関連する場合があります：golang-cli、golang-context、golang-data-structures、golang-database、golang-dependency-injection、またはライブラリ固有のスキル。

Claude Code の GitHub App 統合は /install-github-app コマンドで設定します。このコマンドにより、必要な API シークレットが設定されます。

GitHub Copilot

スキルをリポジトリにコピーし、copilot-review-instructions.md を .github/copilot-instructions.md に追記します:

npx skills add https://github.com/samber/cc-skills-golang --agent github-copilot --skill '*' -y --copy
ln -s .agents .copilot

---

よくある間違い

間違い	修正
CI テストで -race が欠落している	常に go test -race を使用する
-shuffle=on がない	テスト順序をランダム化してテスト間の依存関係を検出する
統合テストの結果をキャッシュしている	-count=1 を使用してキャッシュを無効にする
go mod tidy がチェックされていない	go mod tidy && git diff --exit-code ステップを追加する
fail-fast: false が欠落している	1 つの Go バージョンの失敗で他のジョブをキャンセルすべきではない
アクションのバージョンを固定していない	GitHub Actions は固定されたメジャーバージョンを使用 MUST（例: @master ではなく @vN）
permissions ブロックがない	ジョブごとに最小権限に従う
govulncheck の検出結果を無視している	正当な理由を付けて修正または抑制する
CI に AI レビューがない	Claude Code または Copilot レビューを追加する — 静的解析では見逃されるロジック、セキュリティ、アーキテクチャの問題を検出できる

関連スキル

samber/cc-skills-golang@golang-lint、samber/cc-skills-golang@golang-security、samber/cc-skills-golang@golang-testing、samber/cc-skills-golang@golang-dependency-management、samber/cc-skills-golang@golang-modernize の各スキルを参照してください。