woodpecker-ci

Woodpecker CI

このスキルは運用プレイブックとして使用し、インストールされているメジャーバージョンのドキュメントを確認する代わりにしないでください。明示的な SemVer イメージタグを優先し、サービスの起動前に解決済みの設定を確認し、変更のたびに実行時の正常性を確認してください。

対象範囲： このスキルでは Woodpecker CI（サーバー、エージェント、ワークフロー、統合機能）を設定・運用します。Forgejo/Gitea 自体のインストールや管理、および Forgejo Actions ランナーの設定は対象外です。タスクで Forgejo に言及されている場合、明示的に Forge の管理を依頼されていない限り、Woodpecker が接続する Forge として扱ってください。

運用ループ

1. Woodpecker のメジャーバージョン、Forge、バックエンド、デプロイファイル、データベース、公開 URL、およびタスクがセットアップ、パイプライン、インシデントのどれに該当するかを特定します。
2. 設定を変更する前に、以下の該当するリファレンスを読みます。
3. サーバーまたはエージェントを起動する前に、設定をレンダリングしてリントします。
4. 問題を担当するレイヤー（Forge/OAuth、サーバー、エージェント/バックエンド、リポジトリのワークフロー）のうち、最小限の変更を行います。
5. 次の境界で結果を確認します。サーバーの正常性、エージェントの接続状態、リポジトリの Webhook、パイプラインのスケジュール、ステップログ、外部デプロイのエンドポイントを確認してください。
6. シークレット値は記録せず、正確なバージョンと関連する環境変数を記録します。

エントリーポイントを選ぶ

タスクの内容	ここから開始
新しいサーバー/エージェント、または Forge への接続	references/setup.md
ワークフロー YAML、サービス、条件、シークレット、プラグイン	references/pipeline-syntax.md
アップグレード、バックアップ、メトリクス、CLI、容量	references/operations.md および references/advanced-patterns.md
ログイン、キューに入ったパイプライン、クローン、ステップ、バックエンドの失敗	references/troubleshooting.md および references/failure-signatures.md
信頼性またはマルチテナントに関する判断	references/security.md および references/setup.md のバックエンドのセクション
ローカルでのリント/実行、または CLI のインストール	references/cli.md

バージョンに依存するコマンドや変数の確認が必要な場合は、続いて references/source-index.md を読み込みます。

クイックコマンドカード

# Generate a shared server/agent secret
openssl rand -hex 32

# Compose Woodpecker server + agent (not Forgejo itself)
cp templates/docker-compose.yml compose.yaml
cp templates/forgejo.env.example .env
# edit .env, then:
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs -f --tail=100 woodpecker-server woodpecker-agent

# Local workflow checks
woodpecker-cli lint .woodpecker.yml
woodpecker-cli exec .woodpecker.yml

# Pipeline and secret administration
woodpecker-cli repo info --repository OWNER/REPO
woodpecker-cli repo secret add --repository OWNER/REPO --name NAME --value @/path/to/value

woodpecker-cli exec はローカルでのコマンドとメタデータの確認に便利ですが、サーバー実行の完全な代替にはなりません。サーバー管理のシークレットや Forge のイベントをローカルで利用できない場合があります。

コアのデフォルト

• 分離されたコンテナステップには Docker バックエンドを使用します。Docker ソケットは強力な権限を持つため、エージェントホストを CI の信頼境界として扱ってください。
• ステップごとの Pod 分離とクラスターのスケジューリングには Kubernetes バックエンドを使用します。リポジトリの作成者にバックエンドのオプション設定を許可する前に、サービスアカウント、名前空間の境界、プルシークレット、PVC／ストレージ、リソースリクエストを確認してください。

マルチテナント環境でのデフォルト： 信頼できないリポジトリでは、クラスターがすでにセキュリティ境界として運用されている場合、名前空間／RBAC／ServiceAccount による制御を備えた Kubernetes を優先してください。Docker は、専用エージェントと信頼レベルの分離がある場合に限り、よりシンプルなデフォルトとして有効です。Docker ソケットはホストのデーモンを制御するためです。信頼できないリポジトリには、Local バックエンドを絶対に使用しないでください。

• エージェントには WOODPECKER_SERVER と、サーバーと同じ WOODPECKER_AGENT_SECRET が必要です。サーバーは初回接続時にエージェントを登録します。生成された ID が再起動後も維持されるよう、エージェントの設定ファイルを永続化してください。
• オープン登録が意図的な場合を除き、WOODPECKER_OPEN=false を維持してください。管理者アクセスは明示的に付与し、OAuth クライアントシークレットとエージェントシークレットを保護してください。
• デフォルトでは、信頼できないプルリクエストにシークレットを公開しないでください。そこでシークレットを利用できるようにする必要がある場合は、そのイベントとプラグインイメージを制限し、脅威モデルを文書化してください。
• depends_on はワークフローの順序付けと並列実行のためのものであり、サービスコンテナの準備完了チェックではありません。データベースやキャッシュには、実際の待機／バックオフ処理またはヘルスプローブを追加してください。
• ステップの when リストは、各項目の間は OR、各項目内は AND で評価されます。ブランチフィルターはプルリクエストのターゲットブランチにも適用されます。ブランチへのプッシュのみを対象とする場合は、event と branch を組み合わせてください。
• docker compose config または CLI のリントが成功しても、構文／モデルの妥当性が確認できるだけです。エージェントが Forge に到達できること、イメージをプルできること、パイプラインが安全であることは証明されません。

参照先の案内

読み込むタイミング	参照先
Docker Compose によるインストール、Forgejo／Gitea の設定、またはバックエンドの選択	references/setup.md
ワークフロー YAML、イベント、条件、マトリックス、サービス、プラグイン、または複数ワークフローのプロジェクトを記述するとき	references/pipeline-syntax.md
並列ワークフロー、同時実行、キャッシュ、レジストリ、再利用可能な YAML、または自動スケーリングを設計するとき	references/advanced-patterns.md
シークレット、レジストリ、CLI 操作、アップグレード、バックアップ、メトリクスを管理するとき	references/operations.md
パイプライン、クローン、エージェント、OAuth、Docker、または Kubernetes の実行に失敗したとき	references/troubleshooting.md
インシデント対応中に、症状と証拠を簡潔に対応付けた一覧が必要なとき	references/failure-signatures.md
信頼境界、プルリクエスト、プラグイン、ローカルバックエンド、または Kubernetes の権限を確認するとき	references/security.md
woodpecker-cli を使用またはインストールするとき	references/cli.md
ソース URL とバージョンに左右される記述を確認するとき	references/source-index.md

同梱されている成果物

• templates/docker-compose.yml — サーバーと Docker エージェントをデプロイするための最小構成。
• templates/woodpecker.yml — 保守的なビルド／テスト／デプロイのワークフローのひな形。
• templates/forgejo.env.example — Forgejo 用のプレースホルダー環境変数の定義。
• assets/troubleshooting-checklist.md — インシデント引き継ぎ用チェックリスト。
• scripts/woodpecker-doctor.py — テキストまたは JSON で出力する、依存関係不要の接続／設定プローブ。

利用可能なスクリプト

スクリプト	目的	実行方法
scripts/woodpecker-doctor.py	Woodpecker デプロイメント用の、依存関係不要の接続／設定プローブです。サーバーの HTTP URL とエージェントの gRPC エンドポイントを確認し、テキストまたは JSON で出力します。「CI の問題か、自分の問題か」を診断する際の最初のステップとして、デプロイ後の変更による健全性の確認として、また詳細なトラブルシューティングを始める前に実行してください。	python3 scripts/woodpecker-doctor.py --url https://ci.example.com --server agent-host:9000 --json

前提条件

• プローブの実行元から Woodpecker サーバーの URL へネットワーク接続できること。エージェントを確認する場合は、エージェントの gRPC ホストとポートにも接続できること。
• Python 3 のみが必要です。プローブは標準ライブラリを使用し、サードパーティ製パッケージは不要です。また、Woodpecker インスタンスを変更することはありません。
• プローブ以外の実際の管理（compatibility に記載）には、使用するバックエンドに応じて、Woodpecker インスタンスへのアクセスと Docker Compose、Kubernetes、または woodpecker-cli が必要です。references/setup.md と references/cli.md を参照してください。

制限事項

• doctor プローブが報告するのは接続性と設定に関するシグナルのみです。プローブの結果が正常でも、forge OAuth の動作、パイプラインのスケジュール、ステップによるイメージのプルを保証するものではありません。それぞれの境界で個別に確認してください（「よくある失敗の境界」を参照）。
• リポジトリレベルの状態（Webhook、シークレット、キューの深さ）は読み取りません。サーバーの API／UI と references/troubleshooting.md を使用してください。
• このスキルが記載するのは運用パターンであり、特定のバージョンに固定されたものではありません。バージョンに依存するコマンドや変数は、references/source-index.md を参照して、インストール済みのメジャーバージョンに対して必ず確認してください。

よくある失敗の境界

• サーバーは起動するものの、リポジトリが表示されない場合：パイプライン YAML を変更する前に、forge OAuth の URL、コールバック URL、スコープ、サーバーログを確認してください。プッシュしてもパイプラインが実行されない場合は、まず Forgejo リポジトリの 設定 → Webhook → 最近の配信 を確認し、配信ステータスを記録してください。
• エージェントは接続されているものの、作業をまったく開始しない場合：ラベル／バックエンド、ワークフローの最大数、リポジトリの公開範囲／信頼設定、エージェントログを比較してください。
• クローンに失敗する場合：まず、意図的に一時停止したステップからネットワーク／DNS と認証情報をテストしてください。チェックアウトが成功するまで、アプリケーションのコマンドをデバッグしないでください。
• サービスは稼働しているものの、テストが接続できない場合：サービスのホスト名とコンテナのポートを使用し、その後、準備完了を待つ処理を追加してください。
• シークレットが空の場合：シークレットのスコープ、イベントフィルター、プラグインイメージのフィルター、式のエスケープ（Woodpecker からシェルへ変数を渡す場合は $${NAME}）を確認してください。

使用しない場合

Forgejo／Gitea 自体のインストールや管理には forge 固有のスキルを、クラスターのライフサイクル管理には Kubernetes 運用スキルを、ホストの強化には Docker セキュリティスキルを使用してください。このスキルの対象は、Woodpecker の統合ポイントと CI の動作です。