CI/CDDevOps【免費下載鏈接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.項目地址https://gitcode.com/gh_mirrors/wo/woodpecker點擊查看免費下載本篇指南以 Woodpecker CI/CD 引擎當前文檔對應 v2.8 版本線內(nèi)置的 Forge代碼托管平臺驅動體系為線索系統(tǒng)講解如何將 Woodpecker Server 與 GitHub、Gitea、Forgejo、GitLab、Bitbucket Cloud、Bitbucket Datacenter 六類 Forge 對接從 OAuth 應用注冊、環(huán)境變量配置到各平臺能力差異矩陣。讀完本文你將能按需為實例選擇并配置正確的 Forge 驅動理解 Webhook 回環(huán)、Agent 網(wǎng)絡連通性等關鍵坑點并了解如何通過 Addon Forge 擴展官方未覆蓋的平臺。Forge 在 Woodpecker 中的角色Woodpecker 是采用Server / Agent 分離架構的 CI/CD 引擎Server 負責與代碼托管平臺Forge通信、接收 Webhook、調(diào)度流水線Agent 負責實際執(zhí)行構建。這里所說的 Forge指的就是 Server 對接的代碼托管平臺——它是 Woodpecker 感知推送到倉庫、創(chuàng)建 PR、打 Tag、發(fā)布 Release等事件并觸發(fā)流水線的唯一入口。Woodpecker 內(nèi)置了六類 Forge 驅動官方管理文檔集中在docs/versioned_docs/version-2.8/30-administration/11-forges/目錄驅動說明GitHub支持 GitHub 與 GitHub EnterpriseGitea支持自托管 GiteaForgejoForgejo 支持仍處于實驗階段GitLab支持 GitLab 8.2 及以上版本Bitbucket支持 Bitbucket CloudBitbucket Datacenter支持 Bitbucket Datacenter / Server原 Atlassian Stash實驗階段若以上平臺均不滿足需求還可以編寫 Addon Forge 擴展后文有專門小節(jié)說明。Forge 功能對比矩陣不同 Forge 對 Woodpecker 功能特性的支持程度并不一致。官方在 11-overview.md 中給出了完整的支持矩陣這是選型時必須先看的表FeatureGitHubGiteaForgejoGitlabBitbucketBitbucket DatacenterEvent: Push??????Event: Tag??????Event: Pull-Request??????Event: Release??????Event: Deploy??????Multiple workflows??????when.path filter??????幾點解讀事件支持六類 Forge 都支持 Push、Tag、Pull-Request 三種基礎事件Release 事件僅在 GitHub、Gitea、Forgejo、GitLab 上可用Deploy 事件是 GitHub 獨有能力Gitea、Forgejo、GitLab、Bitbucket 系均不支持。多工作流所有 Forge 均支持 Multiple workflows。when.path過濾GitHub、Gitea、Forgejo、GitLab 支持按變更文件路徑過濾流水線Bitbucket Cloud 與 Bitbucket Datacenter 不支持詳見 workflow syntax 中的 path 一節(jié)。官方在 Bitbucket 文檔中明確表示歡迎社區(qū)提交補丁補齊該功能。對接前的通用認知OAuth 與回調(diào)地址六類 Forge 的對接方式高度一致先在平臺側注冊一個OAuth 應用拿到client id部分平臺叫 Key與client secret再通過環(huán)境變量注入 Woodpecker Server 容器。所有平臺的Authorization callback URL 均統(tǒng)一為https://your-woodpecker-instance/authorize回調(diào)路徑/authorize是 Woodpecker Server 內(nèi)置的 OAuth 回調(diào)端點。注冊時必須保證回調(diào) URL 的 http(s) scheme 與主機名和真實訪問地址完全一致否則授權流程會失敗。以下各節(jié)按官方文檔順序給出每個平臺的完整配置清單。對接 GitHub 與 GitHub EnterpriseWoodpecker 內(nèi)置對 GitHub 與 GitHub Enterprise 的支持。為 Server 組件設置以下環(huán)境變量即可啟用WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_CLIENTYOUR_GITHUB_CLIENT_ID WOODPECKER_GITHUB_SECRETYOUR_GITHUB_CLIENT_SECRET注冊 OAuth 應用Client ID 與 Client Secret 來自 GitHub 的 OAuth 應用注冊進入Settings - Developer Settings - GitHub Apps - New Oauth2 App創(chuàng)建。關鍵字段Name任意應用名稱Homepage URL你的 Woodpecker 實例地址Callback URLhttps://your-woodpecker-instance/authorize可選上傳 Woodpecker Logo 作為應用圖標。創(chuàng)建完成后在應用詳情頁生成Client Secret將該值填入WOODPECKER_GITHUB_SECRET。重要警告不要用 GitHub App 代替 OAuth2 App——GitHub App 目前無法與 Woodpecker 正確協(xié)同其用戶訪問令牌不會自動刷新。GitHub 完整配置項環(huán)境變量默認值作用WOODPECKER_GITHUBfalse啟用 GitHub 驅動WOODPECKER_GITHUB_URLhttps://github.com配置 GitHub 服務器地址自建 GitHub Enterprise 時改為企業(yè)實例地址WOODPECKER_GITHUB_CLIENT空GitHub OAuth client id用于授權訪問WOODPECKER_GITHUB_CLIENT_FILE空從指定文件路徑讀取WOODPECKER_GITHUB_CLIENT的值適合密鑰文件掛載場景WOODPECKER_GITHUB_SECRET空GitHub OAuth client secret用于授權訪問WOODPECKER_GITHUB_SECRET_FILE空從指定文件路徑讀取WOODPECKER_GITHUB_SECRET的值WOODPECKER_GITHUB_MERGE_REFtrue是否使用 merge ref合并引用觸發(fā)構建WOODPECKER_GITHUB_SKIP_VERIFYfalse是否跳過 SSL 證書校驗自簽名證書場景WOODPECKER_GITHUB_PUBLIC_ONLYfalse僅申請可管理公共倉庫的 OAuth token其中WOODPECKER_GITHUB_MERGE_REF與WOODPECKER_GITHUB_PUBLIC_ONLY兩個選項在源碼裝配層面對應github.Opts中的MergeRef與OnlyPublic字段見 server/forge/setup/setup.go#L143-L168默認均按false處理。對接 Gitea啟用 Gitea 需要如下環(huán)境變量WOODPECKER_GITEAtrue WOODPECKER_GITEA_URLYOUR_GITEA_URL WOODPECKER_GITEA_CLIENTYOUR_GITEA_CLIENT WOODPECKER_GITEA_SECRETYOUR_GITEA_CLIENT_SECRETGitea 與容器同主機時的網(wǎng)絡配置若 Gitea 與 Woodpecker Agent 運行在同一臺宿主機的容器中必須保證 Agent 能訪問到 Gitea。Agent 使用Gitea 通過 API 上報的克隆 URL來拉取代碼因此最穩(wěn)妥的做法是把 Woodpecker Agent 加入 Gitea 所在的 Docker 網(wǎng)絡否則通信需經(jīng)docker0網(wǎng)關通常是172.17.0.1。若網(wǎng)絡名為gitea在 docker-compose 中為 agent 增加version: 3 services: [...] woodpecker-agent: [...] environment: - [...] - WOODPECKER_BACKEND_DOCKER_NETWORKgitea注冊 OAuth 應用在 Gitea 的https://gitea.host/user/settings/中找到 OAuth applications 設置并注冊應用?；卣{(diào) URL 必須與 http(s) scheme、主機名完全一致路徑為https://host/authorize。如果 Woodpecker Server 與 Gitea 同主機運行自 Giteav1.16起還需在 Gitea 配置中允許本地連接通常位于/etc/gitea/conf/app.ini否則 Webhook 會發(fā)送失敗[webhook] ALLOWED_HOST_LISTexternal,loopbackGitea 完整配置項環(huán)境變量默認值作用WOODPECKER_GITEAfalse啟用 Gitea 驅動WOODPECKER_GITEA_URLhttps://try.gitea.io配置 Gitea 服務器地址WOODPECKER_GITEA_CLIENT空Gitea OAuth client id用于授權訪問WOODPECKER_GITEA_CLIENT_FILE空從文件讀取WOODPECKER_GITEA_CLIENT的值WOODPECKER_GITEA_SECRET空Gitea OAuth client secret用于授權訪問WOODPECKER_GITEA_SECRET_FILE空從文件讀取WOODPECKER_GITEA_SECRET的值WOODPECKER_GITEA_SKIP_VERIFYfalse是否跳過 SSL 校驗高級選項環(huán)境變量默認值作用WOODPECKER_DEV_GITEA_OAUTH_URLWOODPECKER_GITEA_URL的值配置面向用戶的 Gitea 地址。當WOODPECKER_GITEA_URL指向僅用于 API 請求的內(nèi)網(wǎng)地址時使用后一個選項在源碼中對應gitea.Opts的OAuthHost字段見 server/forge/setup/setup.go#L70-L95實現(xiàn)API 走內(nèi)網(wǎng)、用戶授權跳轉走公網(wǎng)的分離。對接 ForgejoForgejo 支持當前仍標記為experimental實驗性。啟用方式與 Gitea 幾乎一致WOODPECKER_FORGEJOtrue WOODPECKER_FORGEJO_URLYOUR_FORGEJO_URL WOODPECKER_FORGEJO_CLIENTYOUR_FORGEJO_CLIENT WOODPECKER_FORGEJO_SECRETYOUR_FORGEJO_CLIENT_SECRET容器同主機時的網(wǎng)絡配置、注冊步驟與 Webhook 回環(huán)放行邏輯與 Gitea 相同把 Agent 加入 Forgejo 所在 Docker 網(wǎng)絡并在 Forgejo 配置通常/etc/forgejo/conf/app.ini中允許本地 Webhook[webhook] ALLOWED_HOST_LISTexternal,loopbackForgejo 完整配置項環(huán)境變量默認值作用WOODPECKER_FORGEJOfalse啟用 Forgejo 驅動WOODPECKER_FORGEJO_URLhttps://next.forgejo.org配置 Forgejo 服務器地址WOODPECKER_FORGEJO_CLIENT空Forgejo OAuth client idWOODPECKER_FORGEJO_CLIENT_FILE空從文件讀取 client idWOODPECKER_FORGEJO_SECRET空Forgejo OAuth client secretWOODPECKER_FORGEJO_SECRET_FILE空從文件讀取 client secretWOODPECKER_FORGEJO_SKIP_VERIFYfalse是否跳過 SSL 校驗對接 GitLabWoodpecker 支持GitLab 8.2 及以上版本。啟用配置示例WOODPECKER_GITLABtrue WOODPECKER_GITLAB_URLhttp://gitlab.mycompany.com WOODPECKER_GITLAB_CLIENT95c0282573633eb25e82 WOODPECKER_GITLAB_SECRET30f5064039e6b359e075注冊應用與授權范圍在 GitLab 賬戶設置中選擇Applications點擊New Application創(chuàng)建應用Authorization callback URLhttp://woodpecker.mycompany.com/authorize與實例實際地址一致Scope授權范圍必須授予api。私有網(wǎng)絡場景的額外配置若 Woodpecker Server 運行在私有 IPRFC1918 地址上或 GitLab 使用了非標準 TLD如.local、.internGitLab 默認會拒絕來自本地網(wǎng)絡的 API 請求。此時需進入 GitLab Admin 面板的Settings Network Outbound requests開啟Allow requests to the local network from web hooks and services。GitLab 完整配置項環(huán)境變量默認值作用WOODPECKER_GITLABfalse啟用 GitLab 驅動WOODPECKER_GITLAB_URLhttps://gitlab.com配置 GitLab 服務器地址自托管實例改為內(nèi)部地址WOODPECKER_GITLAB_CLIENT空GitLab OAuth client idWOODPECKER_GITLAB_CLIENT_FILE空從文件讀取 client idWOODPECKER_GITLAB_SECRET空GitLab OAuth client secretWOODPECKER_GITLAB_SECRET_FILE空從文件讀取 client secretWOODPECKER_GITLAB_SKIP_VERIFYfalse是否跳過 SSL 校驗對接 Bitbucket Cloud啟用 Bitbucket Cloud 需要WOODPECKER_BITBUCKETtrue WOODPECKER_BITBUCKET_CLIENT... # 在 Bitbucket 中稱為 Key WOODPECKER_BITBUCKET_SECRET...注冊 OAuth Consumer在 Bitbucket 的 workspace settings 中選擇OAuth consumers點擊Add Consumer地址形如https://bitbucket.org/[your-project-name]/workspace/settings/api。設置名稱與回調(diào)地址https://your-woodpecker-address/authorize必須勾選的權限請務必為 Consumer 勾選以下權限否則 Woodpecker 無法完整讀取倉庫信息與接收 WebhookAccountEmail、ReadWorkspace membershipReadProjectsReadRepositoriesReadPull requestsReadWebhooksRead and WriteBitbucket Cloud 完整配置項環(huán)境變量默認值作用WOODPECKER_BITBUCKETfalse啟用 Bitbucket 驅動WOODPECKER_BITBUCKET_CLIENT空Bitbucket OAuth client key即 Consumer KeyWOODPECKER_BITBUCKET_CLIENT_FILE空從文件讀取 client keyWOODPECKER_BITBUCKET_SECRET空Bitbucket OAuth client secretWOODPECKER_BITBUCKET_SECRET_FILE空從文件讀取 client secret已知缺失功能Bitbucket 目前不支持 PR 的 path 過濾即when.path對 Pull Request 場景無效。官方歡迎社區(qū)提交補丁補齊該能力。對接 Bitbucket Datacenter / ServerBitbucket Datacenter / Server原 Atlassian Stash支持同樣標記為experimental。在 docker-compose 中通過以下環(huán)境變量啟用注意變量名帶_DC后綴且多了 Git 賬號配置version: 3 services: woodpecker-server: [...] environment: - [...] - WOODPECKER_BITBUCKET_DCtrue - WOODPECKER_BITBUCKET_DC_GIT_USERNAMEfoo - WOODPECKER_BITBUCKET_DC_GIT_PASSWORDbar - WOODPECKER_BITBUCKET_DC_CLIENT_IDxxx - WOODPECKER_BITBUCKET_DC_CLIENT_SECRETyyy - WOODPECKER_BITBUCKET_DC_URLhttp://stash.mycompany.com woodpecker-agent: [...]服務賬號Service Account機制Woodpecker 使用githttps協(xié)議克隆倉庫而Bitbucket Server 目前不支持用 OAuth token 克隆倉庫。因此必須創(chuàng)建一個服務賬號Service Account將其用戶名與密碼交給 Woodpecker用于克隆私有倉庫時認證。這正是WOODPECKER_BITBUCKET_DC_GIT_USERNAME/WOODPECKER_BITBUCKET_DC_GIT_PASSWORD存在的意義缺少任一值驅動裝配會直接報錯源碼中分別以missing git-username、missing git-password返回錯誤見 server/forge/setup/setup.go#L170-L178。注冊 Incoming Link在 Bitbucket Datacenter / Server 的管理后臺選擇Application Links點擊Create link將 Woodpecker 登記為External Application方向direction設為Incomming。記下注冊生成的 client id 與 client secret填入 Woodpecker 配置。Bitbucket Datacenter 完整配置項環(huán)境變量默認值作用WOODPECKER_BITBUCKET_DCfalse啟用 Bitbucket Server 驅動WOODPECKER_BITBUCKET_DC_URL空配置 Bitbucket Server 地址WOODPECKER_BITBUCKET_DC_CLIENT_ID空Bitbucket Server OAuth 2.0 client idWOODPECKER_BITBUCKET_DC_CLIENT_SECRET空Bitbucket Server OAuth 2.0 client secretWOODPECKER_BITBUCKET_DC_GIT_USERNAME空用于認證并克隆所有私有倉庫的用戶名WOODPECKER_BITBUCKET_DC_GIT_USERNAME_FILE空從文件讀取 git 用戶名WOODPECKER_BITBUCKET_DC_GIT_PASSWORD空用于認證并克隆所有私有倉庫的密碼WOODPECKER_BITBUCKET_DC_GIT_PASSWORD_FILE空從文件讀取 git 密碼WOODPECKER_BITBUCKET_DC_SKIP_VERIFYfalse是否跳過 SSL 校驗從源碼看 Forge 驅動如何被裝配閱讀當前倉庫源碼 server/forge/setup/setup.go 可以印證上述配置的真實裝配邏輯。該文件是 Server 側 Forge 驅動的統(tǒng)一工廠入口Forge()函數(shù)根據(jù)model.Forge的類型字段做分發(fā)switch forge.Type { case model.ForgeTypeAddon: return setupAddon(forge) case model.ForgeTypeGithub: return setupGitHub(forge) case model.ForgeTypeGitlab: return setupGitLab(forge) case model.ForgeTypeBitbucket: return setupBitbucket(forge) case model.ForgeTypeGitea: return setupGitea(forge) case model.ForgeTypeForgejo: return setupForgejo(forge) case model.ForgeTypeBitbucketDatacenter: return setupBitbucketDatacenter(forge) default: return nil, fmt.Errorf(forge not configured) }從中可以確認幾個實現(xiàn)細節(jié)Gitea / Forgejo 的 URL 必填校驗setupGitea與setupForgejo在URL為空時會分別返回WOODPECKER_GITEA_URL must be set、WOODPECKER_FORGEJO_URL must be set錯誤setup.go#L83-L84、setup.go#L110-L111因此這兩個平臺即使使用默認公共實例也建議顯式設置 URL。URL 規(guī)范化Gitea / Forgejo 的 URL 會經(jīng)url.Parse并TrimRight(/)去除尾部斜杠后再傳給驅動。GitHub 的兩個布爾選項merge-ref與public-only從AdditionalOptions中讀取并映射到github.Opts.MergeRef/OnlyPublic對應環(huán)境變量WOODPECKER_GITHUB_MERGE_REF與WOODPECKER_GITHUB_PUBLIC_ONLY。Bitbucket DC 的強校驗git-username、git-password、oauth-enable-project-admin-scope三個附加選項缺失或類型錯誤時直接裝配失敗說明該驅動對服務賬號的依賴是硬性的。調(diào)試日志每個驅動裝配都會輸出包含url、oauth-host、skip-verify、oauth-client-id-set、oauth-client-secret-set等字段的 Debug 日志排查對接問題時可通過這些日志判斷憑據(jù)是否成功注入。注意當前倉庫源碼基于更新的 v3 模塊路徑go.woodpecker-ci.org/woodpecker/v3變量語義與本文檔v2.8 文檔線保持一致部署時請以你所安裝版本的官方文檔為準。擴展為未覆蓋的平臺編寫 Addon Forge如果所用平臺不符合 Woodpecker 的 Forge 要求如平臺能力過于特殊或你的場景過于定制化可以編寫Addon Forge接入配置方式下載與版本匹配的 addon 二進制設置WOODPECKER_ADDON_FORGE/path/to/your/addon/forge/file容器場景建議將 addon 掛載到/opt/addons/。通信機制Addon 通過RPC與 Server 通信底層基于go-plugin庫實現(xiàn)官方文檔給出的是外部鏈接這里僅引用其機制描述。實現(xiàn)方式直接引入 Woodpecker 的 Go 包go.woodpecker-ci.org/woodpecker/woodpecker/v2讓config類型實現(xiàn)server/forge包的Forge接口然后在main中調(diào)用go.woodpecker-ci.org/woodpecker/v2/server/forge/addon.Serve由它負責與 Server 建連package main import ( context net/http go.woodpecker-ci.org/woodpecker/v2/server/forge/addon forgeTypes go.woodpecker-ci.org/woodpecker/v2/server/forge/types go.woodpecker-ci.org/woodpecker/v2/server/model ) func main() { addon.Serve(config{}) } type config struct { }兩點重要提醒摘自官方文檔原文Addon Forge 仍為實驗性實現(xiàn)可能隨時變更必須信任所使用 addon 的作者——它能夠接觸授權碼等敏感信息Bug 排查時先看日志區(qū)分責任組件addon 的日志帶有特殊字段addon值為其文件名若問題出在 addon應到獨立的 addon 倉庫提 issue而不是主倉庫。常見問題與排錯要點匯總官方文檔中反復強調(diào)的幾個坑供對接時對照檢查回調(diào) URL 不一致/authorize路徑前的 scheme 與主機名必須與用戶實際訪問 Woodpecker 的地址完全一致否則 OAuth 授權失敗。Webhook 發(fā)不出去同主機部署Giteav1.16與 Forgejo在app.ini的[webhook]段設置ALLOWED_HOST_LISTexternal,loopbackGitLab私有 IP / 非標準 TLD 場景下在 Admin 的Settings Network Outbound requests開啟允許本地網(wǎng)絡請求。Agent 克隆不到代碼容器同主機將 Agent 加入 Forge 所在 Docker 網(wǎng)絡WOODPECKER_BACKEND_DOCKER_NETWORKnetwork否則通信只能繞行docker0網(wǎng)關。Bitbucket DC 克隆失敗確認已配置服務賬號WOODPECKER_BITBUCKET_DC_GIT_USERNAME/WOODPECKER_BITBUCKET_DC_GIT_PASSWORD因為 Bitbucket Server 不接受 OAuth token 克隆。憑據(jù)泄露風險*_FILE系列變量如WOODPECKER_GITHUB_SECRET_FILE允許將 client secret 從外部文件讀取適合容器密鑰掛載場景避免把敏感值寫死在環(huán)境變量里。小結Woodpecker 通過統(tǒng)一的環(huán)境變量約定和一致的/authorize回調(diào)機制讓 GitHub、Gitea、Forgejo、GitLab、Bitbucket Cloud、Bitbucket Datacenter 六類代碼托管平臺都能在數(shù)分鐘內(nèi)完成對接。選型時應優(yōu)先核對功能對比矩陣Release / Deploy 事件、when.path過濾是主要差異點部署時重點檢查 OAuth 回調(diào)一致性、Webhook 回環(huán)放行與 Agent 網(wǎng)絡連通性三個環(huán)節(jié)。深入 server/forge/setup/setup.go 的裝配邏輯還能在出現(xiàn) forge not configured 或missing git-username這類報錯時快速定位根因。贊分享CI/CDDevOps【免費下載鏈接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.項目地址https://gitcode.com/gh_mirrors/wo/woodpecker點擊查看免費下載相關推薦Sourcebot配置教程連接GitHub、GitLab等代碼托管平臺的完整指南Sourcebot配置教程連接GitHub、GitLab等代碼托管平臺的完整指南 想要在多個代碼倉庫中快速搜索代碼Sourcebot作為開源的SourcegOneDev vs GitLab輕量級自托管DevOps平臺性能對比與選型指南OneDev vs GitLab輕量級自托管DevOps平臺性能對比與選型指南 在當今DevOps工具選擇中OneDev和GitLab都是優(yōu)秀的自托管解決方后端開發(fā)工具DevOps代碼托管CI/CD研發(fā)協(xié)作項目管理Soft Serve vs GitLab vs Gitea終極自托管Git服務器對比指南Soft Serve vs GitLab vs Gitea終極自托管Git服務器對比指南 在當今軟件開發(fā)領域選擇合適的自托管Git服務器至關重要。Soft代碼托管后端上一篇JSX-Email最佳實踐性能優(yōu)化、可訪問性與安全考量下一篇RVC 語音轉換完整教程用 10 分鐘音頻訓練可用音色克隆模型創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考