【2026年】Woodpecker CI セルフホスト構築ガイド｜Drone のコミュニティフォーク

本格的な運用を想定する場合は、PostgreSQL または MySQL のようなクライアントサーバー型の RDBMS を使用することを強く推奨します。これらは高い並行処理能力を持ち、大量のビルド履歴やログ情報を効率的に管理できます。特に PostgreSQL は、拡張機能の豊富さとデータ整合性の厳密さにおいて優れており、Woodpecker 公式もこれを推奨しています。設定においては、外部データベースサーバーを構築し、そのエンドポイントを Woodpecker のバックエンドコンテナから参照する形式となります。セキュリティ面では、データベースへの接続に TLS を強制したり、強力なパスワードポリシーを適用したりすることが重要です。

Docker Compose と Helm によるデプロイ手法の詳細解説

Woodpecker CI の導入方法として、最も一般的で手軽なのは Docker Compose を用いたセットアップです。これは、コンテナ化された各コンポーネント（Web UI、バックエンド、エージェントなど）を一つの docker-compose.yml ファイルで定義し、単一のコマンドで起動・停止・管理できる利点があります。2026 年 4 月時点の Woodpecker CI 3.x 以降では、公式提供される Docker Compose テンプレートがさらに洗練されており、セキュリティ設定やネットワーク構成が最適化されています。

Docker Compose を使用する場合、まず Woodpecker のコンテナイメージを指定する必要があります。バックエンドには woodpeckerci/woodpecker-server、Web UI には woodpeckerci/woodpecker-web、そして実行エージェントには woodpeckerci/woodpecker-agent というイメージがそれぞれ用意されています。これらを Docker Compose で定義する際、重要な点はボリューム（Volume）の管理です。データベースファイルやトークン情報、パイプライン設定ファイルを永続化するために、ホスト側のディレクトリをコンテナ内部にマウントします。例えば、バックエンドの設定ファイルは /etc/woodpecker、データベースファイルは /var/lib/data などのパスを用いてマウントするのが一般的です。

大規模な展開やクラウド環境（AWS EKS や Google Kubernetes Engine など）においては、Docker Compose よりも Helm Chart を使用したデプロイが好まれます。Helm は Kubernetes パッケージマネージャーであり、複雑な構成をテンプレート化して管理することを可能にします。公式の Woodpecker Helm Chart を利用することで、自動スケーリング（HPA）、設定値のカスタマイズ、そしてアップグレード管理が容易になります。例えば、エージェント数を負荷に応じて自動的に増減させる設定や、データベースへの接続プールサイズを調整するパラメータを YAML ファイル上で一貫して定義できます。Helm を使うことで、複数の環境（開発、ステージング、本番）間での構成の差分管理も格段に楽になります。

オープンソース認証と OAuth プロバイダーの設定方法

Woodpecker CI を実運用に移す際、ユーザー認証をどのように行うかはセキュリティと利便性の面で極めて重要です。初期状態ではローカルなアカウント機能もありますが、企業環境や大規模チームにおいては、既存のエンタープライズシステムや Git プロバイダーとの連携が必須となります。Woodpecker は OAuth 2.0 / OIDC（OpenID Connect）プロトコルを標準サポートしており、GitHub、GitLab、Gitea、Forgejo、Bitbucket など主要なプラットフォームとシームレスに連携できます。

設定においては、まず Woodpecker の管理画面から「OAuth アプリケーション」の登録手順に従います。例えば GitHub を利用する場合は、GitHub 側の Settings > Developer settings > OAuth Apps から新しいアプリケーションを作成し、コールバック URL として Woodpecker インスタンスの Web UI エンドポイントを指定します。これにより、ユーザーは GitHub アカウントで Woodpecker にログインできるようになります。この際、取得したクライアント ID とシークレットを Woodpecker の環境変数（WOODPECKER_GITHUB_CLIENTID など）に設定する必要があります。環境変数の管理には、Docker 実行時の -e オプションや Helm の values.yaml を用いるのが一般的です。

2026 年時点では、セキュリティの観点から OAuth プロトコルにおける暗黙的なフローの廃止が主流となっており、Woodpecker もこの標準に準拠しています。また、複数認証プロバイダーを同時に有効化することも可能です。例えば、社外ユーザーには GitHub を、社内管理者には LDAP または SSO（Single Sign-On）連携を用いるといった使い分けが可能です。ただし、複数の OAuth プロバイダーを混在させる場合は、ユーザー ID の衝突回避や権限の一元管理に注意が必要です。また、認証情報のトークン保存やリフレッシュに関する設定も、セキュリティポリシーに従って適切に調整する必要があります。

エージェントの種類と実行環境の選定基準

Woodpecker CI におけるパイプラインの実行は、エージェント（Agent）というコンポーネントが担います。エージェントは、バックエンドから受け取ったビルドタスクを実際に処理する「職人」のような存在であり、その種類によってインストール方法や動作特性が異なります。2026 年現在、サポートされている主なエージェントの種類には、Docker エージェント、ローカル（Native）エージェント、Kubernetes エージェント、SSH エージェントがあります。それぞれに明確なメリット・デメリットが存在するため、インフラの状況に合わせて慎重に選定する必要があります。

最も一般的な Docker エージェントは、コンテナ内でビルドを実行します。これにより、各ビルドがクリーンな環境で実行され、依存関係の問題や汚染を防ぐことができます。設定も比較的簡単で、エージェントコンテナをホスト上で起動し、Docker Daemon のソケット（/var/run/docker.sock）へのアクセス権限を与えれば動作します。ただし、ホスト側の Docker 設定に深く干渉するため、セキュリティ上の観点から Docker socket を直接マウントする際のリスク管理が求められます。また、ビルドのコンテナイメージサイズや実行時間の制限を自分で設定する必要があるため、リソース管理は運用側に委ねられます。

ローカルエージェントは、ホスト OS 上に直接ツールチェーン（Go, Rust, Node.js など）がインストールされている場合に有効です。Docker のオーバーヘッドがないため、一部のビルドにおいてパフォーマンスが向上することがあります。また、複雑なファイルシステム操作が必要な特殊なケースでは、コンテナ化された環境よりも柔軟に対応できます。一方で、各ホストの環境統一を運用側で行う必要があるため、スケーラビリティの観点からは不利です。Kubernetes エージェントは、クラスタ内でのスケジューリングにより実行され、リソース制限やポッドの自動再起動が Kubernetes の機能によって管理される点が特徴です。大規模な分散システムにおいては、このエージェントタイプが最も効率的に動作します。

パイプライン記述とプラグイン活用の実践テクニック

Woodpecker CI の真価は、.woodpecker.yml ファイルという YAML 形式のパイプライン定義にあります。Drone CI や GitHub Actions との構文類似性により学習コストが低いですが、独自機能も豊富に用意されています。このファイルはリポジトリルートまたは .woodpecker/ ディレクトリ内に配置し、Woodpecker が自動的に検出・実行します。基本的な構造は steps（ステップ）と services（サービスコンテナ）で構成され、それぞれがビルドの異なるフェーズを処理します。

パイプライン記述において特に強力なのが、条件分岐 (when) と行列展開 (matrix) の機能です。例えば、ブランチ名によって実行するコマンドを変更したり、複数の OS バージョンや言語バージョンに対して並列にテストを実行したりできます。when 構文では branch: [main, develop] のように配列を指定し、特定のブランチでのみステップを実行させることができます。また、matrix を使用すると、例えば Go バージョン v1.20 と v1.21、または Linux と macOS などの組み合わせを自動生成してテストケースを増やすことが可能になり、網羅的な品質検証を実現します。

プラグイン機能は Woodpecker の拡張性を支える重要な要素です。公式およびコミュニティ製のプラグインが多数用意されており、Git クローン、Docker ビルド・プッシュ、Slack 通知、AWS S3 アップロードなど多岐にわたります。プラグインを使用する際は、uses: docker/hub.docker.com/repo/image:tag という形式で指定します。2026 年時点では、セキュリティ向上のため、非公式のプラグインを利用する際にも署名検証や SBOM（ソフトウェア材料表）の確認が推奨されています。また、独自プラグインの開発も比較的容易で、Docker イメージとして公開することで自社のワークフローに特化した機能を追加できます。

シークレット管理とセキュリティ強化のベストプラクティス

CI/CD 環境におけるシークレット管理は、セキュリティリスクを最小化するために最も重要な要素の一つです。Woodpecker CI では、API キー、データベースパスワード、クラウドプロバイダーの認証情報などをパイプライン内で安全に扱うための仕組みが提供されています。これらは Woodpecker の Web UI や CLI を通じて登録・管理され、環境変数としてビルドプロセスに注入されますが、ログ出力やエラーメッセージへの漏洩を防止する設計となっています。

基本的な運用では、Web UI から「Secrets」セクションにてシークレット名と値を入力し、特定のリポジトリまたは全プロジェクトに対して適用範囲を設定します。CLI を用いる場合は woodpecker secret add コマンドが利用可能です。重要なのは、シークレットを YAML ファイル内に直接記述しないことです。.woodpipecer.yml 内で ${SECRET_NAME} のように参照することで、ソースコード管理システムに機密情報が残ることを防ぎます。また、Woodpecker はデータベース上でシークレット値を暗号化して保存する機能を提供しており、外部からの窃取リスクを軽減しています。

セキュリティ強化の一環として、エージェントへのアクセス制御も重要です。SSH エージェントやローカルエージェントを使用する場合、認証鍵の管理が厳密に行われる必要があります。また、ネットワークレベルでの制限も有効です。Woodpecker はリバースプロキシ（Caddy や Traefik）を介して Web UI を公開するのが一般的ですが、内部ネットワークからのみアクセス可能なようにファイアウォールで制限をかけます。さらに、2026 年時点では OIDC トークンによるワークフロー間認証が推奨されており、外部のサービスとの連携時にハードコードされたシークレットを使用しないアプローチがより一層重要視されています。

Drone CI からの移行戦略と互換性への対応

多くのユーザーが Woodpecker を検討する動機は、Drone CI のサポート終了やメンテナンス体制の変化に対する懸念です。Woodpecker は Drone CI と高い互換性を維持しているため、移行は比較的スムーズに行えます。ただし、完全な 100% の互換性があるわけではなく、いくつかの注意点と調整が必要な箇所が存在します。特に、Drone CI 2.x から Woodpecker 3.x への移行においては、パイプライン記述の一部変更や設定ファイル名の整理が必要になる場合があります。

まず、Drone の .drone.yml ファイルをそのまま Woodpecker で読み込むことができますが、Woodpecker 独自の構文拡張（例：services の扱いや when 条件の厳密化）により動作が変わる可能性があります。移行作業では、既存のパイプラインをまずテスト環境で実行し、エラーが発生する箇所を特定してから本番環境へ適用するのが安全です。また、Drone の設定ファイルである .drone.yml を Woodpecker では .woodpipecer.yml または drone.yml として認識させる設定が可能ですが、一貫性のために拡張子を変更して管理することをお勧めします。

移行プロセスにおける重要なステップとして、バックエンドデータの引き継ぎがあります。Drone のデータベース構造と Woodpecker のものは完全に同一ではないため、単純なマイグレーションツールは存在しません。そのため、既存のビルド履歴や設定を完全に移行するのではなく、新規に Woodpecker を立ち上げ、プロジェクトごとのパイプライン定義を手動またはスクリプトで再登録していくアプローチが一般的です。その際、Drone で使用していたシークレットも Woodpecker へ移設する必要があります。この作業は自動化ツール（drone2woodpecker など）を用いることで時間を短縮できますが、最終的な検証は手動で行うことが不可欠です。

他 CI ツールとの比較と Apache 2.0 ライセンスの利点

Woodpecker CI を選択する際の判断材料として、他の主要な CI/CD ツールとの比較検討は欠かせません。GitHub Actions、Jenkins、Forgejo Actions（旧 Gitea Actions）などとの機能性や運用コストを比較することで、自社の開発体制に最も適したツールを見極めることができます。特に、Open Source プロジェクトへの対応やオンプレミスでの運用可否、学習コストの高低といった観点から評価を行います。

GitHub Actions はクラウドベースであり、設定が簡単でエコシステムが充実していますが、コストとデータ管理の制限があります。一方、Jenkins は強力なカスタマイズ性を持ちますが、プラグインの管理やサーバー維持に手間がかかります。Woodpecker CI はこれらの中道を行く存在であり、軽量ながらドキュメントも整備されており、セルフホストでも GitHub Actions 並みの利便性を提供します。特に Apache 2.0 ライセンスは、商用利用や派生作品の開発に対する制限が極めて緩く、企業内でのツール開発や再配布の障壁を低く抑えています。

以下に主要 CI ツールとの機能比較を表に示しました。これにより各ツールの特徴が一目でわかります。

この比較から、Woodpecker は GitHub Actions の利便性と Jenkins のセルフホスト能力を兼ね備えていることがわかります。また、Forgejo Actions との比較では、Apache 2.0 ライセンスが Woodpecker の強みとなります。Forgejo Actions は GPL-3.0 であるため、派生プロジェクトへの利用制限があります。Woodpecker はこの点でより柔軟な活用が可能であり、特にエンタープライズ環境や SaaS 提供を想定したカスタマイズにおいて大きなメリットを発揮します。

リバースプロキシと監視システムの実装ガイド

Production Environment（本番環境）での運用においては、単に Woodpecker を起動するだけでなく、セキュリティや可用性の担保が求められます。そのために不可欠なのがリバースプロキシの導入です。Woodpecker は SSL/TLS 通信をサポートしていますが、直接公開するよりも Caddy や Traefik を介して管理することが推奨されます。Caddy を使用する場合、自動 SSL 発行機能が強く、設定ファイルがシンプルで済みます。

Caddy の設定例として、Caddyfile に Woodpecker のエンドポイントを指定し、TLS 証明書の取得を自動化します。これにより、ユーザーは HTTPS で安全にアクセスでき、中間者攻撃のリスクを排除できます。また、Traefik を使用する場合、Kubernetes の Ingress Resource と連携することで、動的なルーティングや Load Balancing が可能です。2026 年時点では、Let's Encrypt 以外の証明書管理システム（DigiCert など）との連携も標準サポートされており、企業ポリシーに合わせた設定が可能です。

監視とメトリクス収集についても同様に重要です。Woodpecker は Prometheus との連携を標準でサポートしており、ビルド成功率、平均実行時間、キューイング時間などの重要な指標がexporter として公開されています。これらメトリクスを Grafana に可視化することで、システム全体の健全性をリアルタイムに把握できます。例えば、エージェントの CPU 使用率が一定値を超えた場合にアラートを送信する設定を行うことで、ボトルネックを早期に発見し、リソースの最適化につながります。ログ収集については、ELK Stack や Loki との連携も可能であり、ビルドエラー時のデバッグ時に強力な支援ツールとなります。

よくある質問（FAQ）

Q1. Woodpecker CI の導入にはどの程度のサーバーリソースが必要ですか？ A. 最小構成では CPU 2 コア、メモリ 4GB で動作可能です。ただし、これはテスト環境や小規模プロジェクト向けです。本番運用では、バックエンドデータベースの負荷を考慮し、CPU 4 コア以上、メモリ 8GB 以上の推奨スペックがあります。エージェント数は並行実行するビルド数に応じて動的に増減させるため、ホスト側のリソースは負荷に応じてスケールできるように設計することが重要です。また、ディスク領域については、ログやビルドアートを保存するため、少なくとも 50GB の空き容量を確保しておくことをお勧めします。

Q2. SQLite と PostgreSQL ではどちらを選ぶべきでしょうか？ A. 小規模な個人プロジェクトやテスト環境であれば SQLite で十分です。設定が簡単でコストもかからないため、まずは SQLite から始めるのが推奨されます。しかし、本番運用では同時書き込みの制限やデータ整合性の観点から PostgreSQL を強く推奨します。特にビルド履歴が膨大になる場合や、高頻度でアクセスが発生する環境では、PostgreSQL のパフォーマンスと信頼性が Woodpecker の円滑な稼働を保証します。移行も比較的容易なため、将来的な拡張性を考慮して最初から PostgreSQL を選定するのが安全です。

Q3. GitHub Actions との違いは何ですか？ A. 最大の差異はセルフホスト能力にあります。GitHub Actions はクラウドベースのため、設定が簡単でリソース管理不要ですが、コストとデータ管理の制限があります。一方、Woodpecker CI は完全に自社サーバー上で完結するため、機密情報の外部流出リスクを排除できます。また、Apache 2.0 ライセンスにより、ツール自体のカスタマイズや再配布に制限がありません。学習コストは GitHub Actions と同程度ですが、インフラ管理の責任がある分、運用側の負荷は Woodpecker の方が高いと言えます。

Q4. Docker エージェントとローカルエージェントの違いは何ですか？ A. Docker エージェントはコンテナ内でビルドを実行するため、環境がクリーンで依存関係の問題が少ないのが利点です。一方、ローカルエージェントはホスト OS 上に直接ツールチェーンをインストールして実行します。Docker エージェントの方がセキュリティ隔離やスケーリングの面で優れており、2026 年現在では主流です。ただし、特殊なファイルシステム操作や Docker 非対応の特定のライブラリが必要な場合は、ローカルエージェントの方が適しています。

Q5. シークレットはどのように保存されていますか？ A. Woodpecker はデータベース内でシークレット値を暗号化して保存します。Web UI や CLI を通じて登録された情報は、ログ出力やエラーメッセージには含まれないように設計されており、ビルドプロセス内の環境変数としてのみ利用可能です。また、アクセス権限管理により、許可されたユーザーまたはプロジェクトのみがシークレットを取得できます。セキュリティ強化のため、定期的なキーローテーションや、OIDC トークンによる動的認証の併用も検討してください。

Q6. Kubernetes 環境でのデプロイは難しいですか？ A. Helm Chart を使用すれば比較的容易です。公式チャートには基本的な設定値が用意されており、values.yaml を編集してリソース制限や接続情報を指定するだけでデプロイできます。ただし、Kubernetes の理解が必要です。ネットワークポリシーや Ingress の設定、PersistentVolume の確保など、クラスタ固有の設定が必要になります。慣れているチームであれば数時間以内に導入可能ですが、未熟な場合は [Docker Compose](/glossary/pose-context-window-extension) からスタートし、徐々に移行することをお勧めします。

Q7. Drone CI からの完全移行は可能ですか？ A. はい、可能です。パイプライン定義の互換性が高いため、.drone.yml をそのまま使用できるケースが大半です。ただし、Drone の一部独自機能や設定項目は Woodpecker にないため、エラーメッセージを確認して修正が必要です。また、バックエンドデータの完全な移行ツールは存在しないため、パイプライン定義の再登録とシークレットの移設作業が必要になります。テスト環境で並行運用し、問題がなければ本番へ切り替える段階的な移行が安全です。

Q8. オフラインで使用することはできますか？ A. はい、可能です。Woodpecker はオフライン環境でも動作するように設計されています。ただし、Docker イメージのプルが必要なため、CI サーバー上または内部 Docker Registry に必要なイメージを事前にキャッシュしておく必要があります。また、プラグインを使用する場合も、同様に公式レジストリへのアクセスがないとエラーになります。社内ネットワーク内にプライベートなパッケージレポジトリやミラーリング環境を整備することで、完全なオフライン稼働が可能となります。

Q9. 外部の Git プロバイダー（Bitbucket や Azure DevOps）とも連携できますか？ A. はい、可能です。Woodpecker は [OAuth 2](/glossary/oauth-2).0 / OIDC をサポートしているため、多くの主要な Git ホスティングサービスと連携できます。Bitbucket については公式サポートが強化されており、Woodpecker の設定画面から選択して認証フローを完了させるだけで利用可能です。Azure DevOps についても同様に連携可能ですが、OAuth アプリケーションの登録手順や権限設定に注意が必要です。

Q10. Apache 2.0 ライセンスの具体的な利点は何ですか？ A. Apache 2.0 は非常に寛容なライセンスであり、商用利用や派生作品の開発に対する制限が極めて少ないです。これにより、企業内ツールとしてカスタマイズしたり、Woodpecker をベースにした有料サポートサービスを提供したりする自由があります。また、特許訴訟に関する条項も含まれており、プロジェクトの安全性を担保しています。GPL などのコピーレフトライセンスに比べて、ビジネス上のリスクが低く、組織にとって導入の心理的障壁を下げます。

まとめ

以上、Woodpecker CI のセルフホスト構築ガイドとして、インストールから運用までを詳細に解説しました。要点をまとめると以下のようになります。

• Drone からの進化: Woodpecker は Drone CI のコミュニティフォークですが、2026 年現在ではマイクロサービスアーキテクチャと Apache 2.0 ライセンスにより、より堅牢で柔軟なツールへと進化しています。
• バックエンド選定: 小規模なら SQLite、本番運用には [PostgreSQL を推奨し、データの整合性とパフォーマンスを確保します。
• エージェントの柔軟性: Docker エージェントが主流ですが、ローカルや Kubernetes エージェントも用途に応じて選択可能です。分散実行によるスケーラビリティを実現できます。
• セキュリティと認証: OAuth プロバイダー連携により安全な認証を実現し、シークレット管理機能で機密情報を保護します。オフライン対応も可能です。
• 運用の最適化: Helm Chart による Kubernetes 展開や Prometheus を用いた監視システムの実装が、大規模環境での安定稼働に不可欠です。

Woodpecker CI は、開発チームが自社のインフラを完全にコントロールしながら、現代的な CI/CD の恩恵を受けるための優れたソリューションです。本ガイドが読者の環境構築の成功に貢献することを願っています。

自宅サーバーでCI/CDパイプラインを構築する方法を解説。GitHub Actions Self-Hosted Runner・Drone CI・Jenkinsの比較。