CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载Woodpecker CI 内置了对 GitHub 与 GitHub Enterprise 的官方支持Forge 驱动通过 OAuth 2.0 协议完成用户登录、仓库授权与 Webhook 事件接收。本文以 Woodpecker 2.8 版本官方文档为核心结合仓库源码逐项讲解 GitHub Forge 的完整配置流程、全部环境变量语义及其在底层驱动中的真实作用读者按本文操作即可完成 Woodpecker 与 GitHub 的对接并理解每一个配置项背后的实现原理。一、前置条件与工作原理要让 Woodpecker 与 GitHub 协同工作需要先在 GitHub 侧注册一个OAuth 2.0 应用OAuth App再在 Woodpecker 服务端server 组件通过环境变量启用 GitHub 驱动。整体链路如下用户在 Woodpecker 页面点击登录服务端构造 GitHub OAuth 授权链接并跳转用户在 GitHub 完成授权后GitHub 回调 Woodpecker 的/authorize端点并携带授权码Woodpecker 服务端用授权码换取访问令牌Access Token并调用 GitHub API 拉取用户信息、邮箱、组织与仓库列表之后 GitHub 的 push、PR、tag 等 Webhook 事件被推送到 Woodpecker触发流水线执行。在仓库源码中这一驱动位于 server/forge/github 目录核心实现为 github.go。驱动结构体client保存了 URL、OAuth Client ID/Secret、SkipVerify、MergeRef、OnlyPublic等全部配置并通过New(id, opts)工厂函数创建实例见 github.go#L53-L96。:::warning 重要提示不要使用 GitHub App 代替 OAuth 2.0 App。目前 GitHub App 与 Woodpecker 配合存在缺陷——因为其用户访问令牌不会自动刷新user access tokens are not being refreshed automatically会导致长时间运行的任务或后续 API 调用因令牌过期而失败。请务必在 GitHub 中创建OAuth AppOAuth 2.0 Application。 :::二、注册 GitHub OAuth 应用2.1 创建入口在 GitHub 中按以下路径进入创建页面Settings设置 - Developer Settings开发者设置 - GitHub Apps - New OAuth2 App注意此处创建的应是 OAuth2 App而不是 GitHub App二者入口在 GitHub 界面中同属于 GitHub Apps 板块但类型不同。2.2 应用设置字段创建或编辑OAuth App 时需要填写以下字段字段填写内容Name应用名称任意名称例如Woodpecker将展示给授权用户Homepage URL主页 URL你的 Woodpecker 实例地址例如https://ci.example.comCallback URL授权回调 URLhttps://your-woodpecker-instance/authorizeApplication description可选应用描述选填可选应用 Logo可上传 Woodpecker 官方 Logo其中Callback URL 必须严格为https://your-woodpecker-instance/authorize。在源码中OAuth 配置的RedirectURL正是由fmt.Sprintf(%s/authorize, server.Config.Server.OAuthHost)生成的见 github.go#L503即 Woodpecker 服务端配置的对外地址OAuth Host拼接/authorize路径与文档要求完全一致。2.3 生成 Client Secret应用创建完成后在 GitHub 应用详情页生成client secret客户端密钥。该密钥与 Client ID 一起用于 OAuth 授权流程其中 Client Secret 应填入 Woodpecker 服务端的WOODPECKER_GITHUB_SECRET环境变量或WOODPECKER_GITHUB_SECRET_FILE指向的密钥文件。三、服务端环境变量配置在 Woodpecker server 组件的环境中设置以下三个核心变量即可启用 GitHub 驱动WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_CLIENTYOUR_GITHUB_CLIENT_ID WOODPECKER_GITHUB_SECRETYOUR_GITHUB_CLIENT_SECRETWOODPECKER_GITHUB_CLIENT与WOODPECKER_GITHUB_SECRET分别对应 GitHub OAuth 应用页面的Client ID与Client secret由于这两个值属于敏感凭据生产环境建议使用_FILE后缀变量从挂载的密钥文件读取见下文 4.4、4.5 小节。在源码中这些环境变量在 cmd/server/flags.go 中注册为 CLI 标志并绑定环境变量来源github、github-merge-ref、github-public-only等标志见 flags.go#L559-L577。此外GitHub 的 Client ID/Secret 也纳入WOODPECKER_FORGE_CLIENT/WOODPECKER_FORGE_SECRET这一通用回退链当未设置 GitHub 专属变量时会依次回退到WOODPECKER_FORGE_*系列通用 Forge 配置见 flags.go#L483-L532便于多 Forge 场景下统一管理。四、全部配置项详解以下为 GitHub 驱动支持的完整配置项。多数选项带有合理的默认值适用于大多数安装场景仅在需要特殊行为时才需要显式调整。4.1WOODPECKER_GITHUB默认值false启用 GitHub 驱动driver的开关。设置为true后服务端才会加载并注册 GitHub Forge 实现。对应源码中githubCLI 标志见 flags.go#L561-L565。4.2WOODPECKER_GITHUB_URL默认值https://github.comGitHub 服务器地址。默认指向 GitHub Cloud当对接GitHub EnterpriseGitHub Enterprise ServerGHES时应将其设置为你的企业实例地址例如https://github.example.com。源码层面的实现细节见 github.go#L78-L81当WOODPECKER_GITHUB_URL与默认值不同时驱动会去除 URL 末尾的/并把 API 地址拼接为url/api/v3/默认情况下 API 地址固定为https://api.github.com/GitHub Cloud 专用 API 域名。也就是说只要配置了自定义WOODPECKER_GITHUB_URL驱动会自动切换到对应企业实例的 REST API v3 地址无需单独配置 API 端点。4.3WOODPECKER_GITHUB_CLIENT默认值空GitHub OAuth Client ID用于 OAuth 授权流程的身份标识。在 OAuth 授权配置中作为oauth2.Config.ClientID使用见 github.go#L495-L504。4.4WOODPECKER_GITHUB_CLIENT_FILE默认值空指定一个文件路径从该文件内容读取WOODPECKER_GITHUB_CLIENT的值。适用于将 Client ID 以文件形式如 Kubernetes Secret 挂载、Docker 密钥文件提供给容器的场景。源码中该文件源被纳入forge-oauth-client标志的ValueSourceChain首选位置见 flags.go#L484-L493即优先从文件读取其次才回退到环境变量。4.5WOODPECKER_GITHUB_SECRET默认值空GitHub OAuth Client Secret用于换取访问令牌时向 GitHub 证明应用身份是授权访问的关键凭据。对应oauth2.Config.ClientSecret见 github.go#L496。4.6WOODPECKER_GITHUB_SECRET_FILE默认值空与WOODPECKER_GITHUB_CLIENT_FILE同理从指定文件路径读取WOODPECKER_GITHUB_SECRET的值文件内容优先级高于环境变量见 flags.go#L509-L518。4.7WOODPECKER_GITHUB_MERGE_REF默认值true控制 GitHub 拉取请求Pull Request事件流水线使用 merge ref合并引用作为克隆与构建的提交还是使用 PR 分支自身的 head commit。对应源码中github-merge-ref布尔标志默认开启见 flags.go#L566-L571。在 Hook 解析流程中parseHook(r, c.MergeRef)会将该配置作为参数传入见 github.go#L682从而决定 PR 事件最终解析出的 commit SHA 来源。启用时流水线验证的是合并进目标分支之后的代码状态更接近真实合并结果关闭时则直接基于 PR 源分支的最新提交。4.8WOODPECKER_GITHUB_SKIP_VERIFY默认值false是否跳过 SSL/TLS 证书校验。当 GitHub Enterprise 使用自签名证书或内部 CA 时可设为true以关闭 TLS 验证。源码中该配置直接影响 OAuth 上下文与 API 客户端的 HTTP Transport 构造当SkipVerify为真时驱动会构造带InsecureSkipVerify: true的tls.Config同时保留代理设置见 github.go#L467-L478 与 github.go#L523-L530。:::warning 安全提示 仅在内网、可信网络且确需自签名证书时开启WOODPECKER_GITHUB_SKIP_VERIFY切勿在公网环境随意关闭 TLS 校验。 :::4.9WOODPECKER_GITHUB_PUBLIC_ONLY默认值false配置 OAuth 授权时仅申请可管理公开仓库的令牌不授予对私有仓库的访问权限。适合只运行公开项目流水线的安全场景。其作用在 OAuth Scope 构造处体现得最直接见 github.go#L482-L488基础 Scope 始终包含user:email读取已验证邮箱与read:org读取组织成员信息当OnlyPublic为false默认时追加repoScope令牌可读写私有仓库、管理 Webhook当OnlyPublic为true时改为追加admin:repo_hook与repo:status令牌只能管理公开仓库的 Hook 与提交状态无法访问私有仓库内容。五、常见配置场景与扩展要点5.1 GitHub Cloud 标准配置WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_CLIENTxxxxxxxxxxxxxxxx WOODPECKER_GITHUB_SECRETyyyyyyyyyyyyyyyy这是最常见的场景三个核心变量即可WOODPECKER_GITHUB_URL保持默认的https://github.comAPI 自动指向https://api.github.com/。5.2 GitHub EnterpriseGHES配置WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_URLhttps://github.example.com WOODPECKER_GITHUB_CLIENTxxxxxxxxxxxxxxxx WOODPECKER_GITHUB_SECRETyyyyyyyyyyyyyyyy设置WOODPECKER_GITHUB_URL后驱动会把 API 自动切换为https://github.example.com/api/v3/。若企业实例使用自签名证书再补充WOODPECKER_GITHUB_SKIP_VERIFYtrue5.3 密钥文件化容器/编排环境WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_CLIENT_FILE/run/secrets/github_client WOODPECKER_GITHUB_SECRET_FILE/run/secrets/github_secret将敏感凭据以文件方式注入容器避免出现在环境变量明文或镜像配置中文件读取优先级高于同名环境变量。5.4 仅公开仓库模式WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_PUBLIC_ONLYtrue此时 OAuth 令牌仅携带user:email、read:org、admin:repo_hook、repo:status四个 Scope无repo权限适合公开开源项目的 CI 场景遵循最小权限原则。六、底层驱动工作原理源码佐证GitHub 驱动的工作流可归纳为以下三个关键环节均能在 server/forge/github/github.go 中找到对应实现OAuth 登录与令牌交换Login()方法构造 OAuth 授权 URL 引导用户跳转收到回调携带的 code 后调用config.Exchange()换取令牌再通过 GitHub API 获取用户、验证邮箱必须存在已验证邮箱否则登录失败见 github.go#L136-L143并持久化 AccessToken、RefreshToken 与过期时间见 github.go#L108-L154。令牌刷新Refresh()方法利用 OAuth2 的TokenSource自动刷新过期令牌并回写用户记录见 github.go#L156-L181。源码注释明确指出GitHub OAuth App 不提供 refresh tokenwhen using Github oAuth app no refresh token is provided这正是官方文档警告不要使用 GitHub App 的深层原因——GitHub App 的用户令牌刷新机制与 Woodpecker 当前的驱动实现不兼容。Webhook 解析与 PR 合并引用Hook()方法调用parseHook(r, c.MergeRef)解析 GitHub 推送的 Webhook 负载根据MergeRef决定 PR 事件使用合并引用还是源分支提交随后通过 API 补齐变更文件列表PR 场景或 push 场景再交由调度器创建流水线见 github.go#L679-L717。此外convert.go 负责将 GitHub API 返回的仓库、用户、团队、提交等对象转换为 Woodpecker 内部模型parse.go 负责 Webhook 负载解析配套的 github_test.go、parse_test.go 与 convert_test.go 则覆盖了这些转换与解析逻辑的单元测试可作为阅读驱动行为的参考入口。七、验证与故障排查完成配置并重启 Woodpecker server 后可以从以下角度验证对接是否成功Web 界面登录访问 Woodpecker 实例点击登录应跳转至 GitHub 的 OAuth 授权页授权后回到/authorize回调并成功登录仓库同步登录后在仓库管理页应能列出你在 GitHub 有权限的仓库含组织仓库源码中对应Repos()方法按每页 100 条拉取见 github.go#L232-L249Webhook 触发在 GitHub 仓库设置中添加 Webhook 指向 Woodpecker 实例通常由驱动在仓库激活时自动注册推送代码或创建 PR 应能触发流水线。常见问题排查方向登录报错 no verified Email address for GitHub accountGitHub 账号未设置已验证邮箱需在 GitHub 账号设置中完成邮箱验证回调地址 404检查 Callback URL 是否严格为https://woodpecker实例地址/authorize且服务端OAuthHost配置与该地址一致PR 流水线构建的提交不符合预期检查WOODPECKER_GITHUB_MERGE_REF是否为期望值默认true使用合并引用企业实例 TLS 报错确认WOODPECKER_GITHUB_URL正确、证书可信任必要时按上文配置WOODPECKER_GITHUB_SKIP_VERIFYtrue。如需了解更多 Forge 对接方式Gitea、Forgejo、GitLab、Bitbucket 等可参阅同目录下的 11-overview.md以及各 Forge 对应的配置文档。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐LangChain4j GitHub 文档加载器用 GitHubDocumentLoader 从仓库加载文件与目录构建 RAG 语料库LangChain4j GitHub 文档加载器用 GitHubDocumentLoader 从仓库加载文件与目录构建 RAG 语料库 本文围绕 LangChCI/CDDevOpsWoodpecker CI 与 Gitea 集成配置指南从 OAuth 注册到环境变量详解Woodpecker CI 与 Gitea 集成配置指南从 OAuth 注册到环境变量详解 Woodpecker CI 内置了对 Gitea 的完整支持可通CI/CDDevOpsWoodpecker CI/CD 终极指南环境变量与服务配置完全解析Woodpecker CI/CD 终极指南环境变量与服务配置完全解析 Woodpecker 是一个简单而功能强大的 CI/CD 引擎其环境变量和服务配置功能CI/CDDevOps上一篇为什么需要glogg让海量日志分析不再痛苦下一篇BilibiliDown5分钟掌握跨平台B站视频下载神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Woodpecker 接入 GitHub 完全指南：OAuth 应用配置、环境变量与驱动原理
CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载Woodpecker CI 内置了对 GitHub 与 GitHub Enterprise 的官方支持Forge 驱动通过 OAuth 2.0 协议完成用户登录、仓库授权与 Webhook 事件接收。本文以 Woodpecker 2.8 版本官方文档为核心结合仓库源码逐项讲解 GitHub Forge 的完整配置流程、全部环境变量语义及其在底层驱动中的真实作用读者按本文操作即可完成 Woodpecker 与 GitHub 的对接并理解每一个配置项背后的实现原理。一、前置条件与工作原理要让 Woodpecker 与 GitHub 协同工作需要先在 GitHub 侧注册一个OAuth 2.0 应用OAuth App再在 Woodpecker 服务端server 组件通过环境变量启用 GitHub 驱动。整体链路如下用户在 Woodpecker 页面点击登录服务端构造 GitHub OAuth 授权链接并跳转用户在 GitHub 完成授权后GitHub 回调 Woodpecker 的/authorize端点并携带授权码Woodpecker 服务端用授权码换取访问令牌Access Token并调用 GitHub API 拉取用户信息、邮箱、组织与仓库列表之后 GitHub 的 push、PR、tag 等 Webhook 事件被推送到 Woodpecker触发流水线执行。在仓库源码中这一驱动位于 server/forge/github 目录核心实现为 github.go。驱动结构体client保存了 URL、OAuth Client ID/Secret、SkipVerify、MergeRef、OnlyPublic等全部配置并通过New(id, opts)工厂函数创建实例见 github.go#L53-L96。:::warning 重要提示不要使用 GitHub App 代替 OAuth 2.0 App。目前 GitHub App 与 Woodpecker 配合存在缺陷——因为其用户访问令牌不会自动刷新user access tokens are not being refreshed automatically会导致长时间运行的任务或后续 API 调用因令牌过期而失败。请务必在 GitHub 中创建OAuth AppOAuth 2.0 Application。 :::二、注册 GitHub OAuth 应用2.1 创建入口在 GitHub 中按以下路径进入创建页面Settings设置 - Developer Settings开发者设置 - GitHub Apps - New OAuth2 App注意此处创建的应是 OAuth2 App而不是 GitHub App二者入口在 GitHub 界面中同属于 GitHub Apps 板块但类型不同。2.2 应用设置字段创建或编辑OAuth App 时需要填写以下字段字段填写内容Name应用名称任意名称例如Woodpecker将展示给授权用户Homepage URL主页 URL你的 Woodpecker 实例地址例如https://ci.example.comCallback URL授权回调 URLhttps://your-woodpecker-instance/authorizeApplication description可选应用描述选填可选应用 Logo可上传 Woodpecker 官方 Logo其中Callback URL 必须严格为https://your-woodpecker-instance/authorize。在源码中OAuth 配置的RedirectURL正是由fmt.Sprintf(%s/authorize, server.Config.Server.OAuthHost)生成的见 github.go#L503即 Woodpecker 服务端配置的对外地址OAuth Host拼接/authorize路径与文档要求完全一致。2.3 生成 Client Secret应用创建完成后在 GitHub 应用详情页生成client secret客户端密钥。该密钥与 Client ID 一起用于 OAuth 授权流程其中 Client Secret 应填入 Woodpecker 服务端的WOODPECKER_GITHUB_SECRET环境变量或WOODPECKER_GITHUB_SECRET_FILE指向的密钥文件。三、服务端环境变量配置在 Woodpecker server 组件的环境中设置以下三个核心变量即可启用 GitHub 驱动WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_CLIENTYOUR_GITHUB_CLIENT_ID WOODPECKER_GITHUB_SECRETYOUR_GITHUB_CLIENT_SECRETWOODPECKER_GITHUB_CLIENT与WOODPECKER_GITHUB_SECRET分别对应 GitHub OAuth 应用页面的Client ID与Client secret由于这两个值属于敏感凭据生产环境建议使用_FILE后缀变量从挂载的密钥文件读取见下文 4.4、4.5 小节。在源码中这些环境变量在 cmd/server/flags.go 中注册为 CLI 标志并绑定环境变量来源github、github-merge-ref、github-public-only等标志见 flags.go#L559-L577。此外GitHub 的 Client ID/Secret 也纳入WOODPECKER_FORGE_CLIENT/WOODPECKER_FORGE_SECRET这一通用回退链当未设置 GitHub 专属变量时会依次回退到WOODPECKER_FORGE_*系列通用 Forge 配置见 flags.go#L483-L532便于多 Forge 场景下统一管理。四、全部配置项详解以下为 GitHub 驱动支持的完整配置项。多数选项带有合理的默认值适用于大多数安装场景仅在需要特殊行为时才需要显式调整。4.1WOODPECKER_GITHUB默认值false启用 GitHub 驱动driver的开关。设置为true后服务端才会加载并注册 GitHub Forge 实现。对应源码中githubCLI 标志见 flags.go#L561-L565。4.2WOODPECKER_GITHUB_URL默认值https://github.comGitHub 服务器地址。默认指向 GitHub Cloud当对接GitHub EnterpriseGitHub Enterprise ServerGHES时应将其设置为你的企业实例地址例如https://github.example.com。源码层面的实现细节见 github.go#L78-L81当WOODPECKER_GITHUB_URL与默认值不同时驱动会去除 URL 末尾的/并把 API 地址拼接为url/api/v3/默认情况下 API 地址固定为https://api.github.com/GitHub Cloud 专用 API 域名。也就是说只要配置了自定义WOODPECKER_GITHUB_URL驱动会自动切换到对应企业实例的 REST API v3 地址无需单独配置 API 端点。4.3WOODPECKER_GITHUB_CLIENT默认值空GitHub OAuth Client ID用于 OAuth 授权流程的身份标识。在 OAuth 授权配置中作为oauth2.Config.ClientID使用见 github.go#L495-L504。4.4WOODPECKER_GITHUB_CLIENT_FILE默认值空指定一个文件路径从该文件内容读取WOODPECKER_GITHUB_CLIENT的值。适用于将 Client ID 以文件形式如 Kubernetes Secret 挂载、Docker 密钥文件提供给容器的场景。源码中该文件源被纳入forge-oauth-client标志的ValueSourceChain首选位置见 flags.go#L484-L493即优先从文件读取其次才回退到环境变量。4.5WOODPECKER_GITHUB_SECRET默认值空GitHub OAuth Client Secret用于换取访问令牌时向 GitHub 证明应用身份是授权访问的关键凭据。对应oauth2.Config.ClientSecret见 github.go#L496。4.6WOODPECKER_GITHUB_SECRET_FILE默认值空与WOODPECKER_GITHUB_CLIENT_FILE同理从指定文件路径读取WOODPECKER_GITHUB_SECRET的值文件内容优先级高于环境变量见 flags.go#L509-L518。4.7WOODPECKER_GITHUB_MERGE_REF默认值true控制 GitHub 拉取请求Pull Request事件流水线使用 merge ref合并引用作为克隆与构建的提交还是使用 PR 分支自身的 head commit。对应源码中github-merge-ref布尔标志默认开启见 flags.go#L566-L571。在 Hook 解析流程中parseHook(r, c.MergeRef)会将该配置作为参数传入见 github.go#L682从而决定 PR 事件最终解析出的 commit SHA 来源。启用时流水线验证的是合并进目标分支之后的代码状态更接近真实合并结果关闭时则直接基于 PR 源分支的最新提交。4.8WOODPECKER_GITHUB_SKIP_VERIFY默认值false是否跳过 SSL/TLS 证书校验。当 GitHub Enterprise 使用自签名证书或内部 CA 时可设为true以关闭 TLS 验证。源码中该配置直接影响 OAuth 上下文与 API 客户端的 HTTP Transport 构造当SkipVerify为真时驱动会构造带InsecureSkipVerify: true的tls.Config同时保留代理设置见 github.go#L467-L478 与 github.go#L523-L530。:::warning 安全提示 仅在内网、可信网络且确需自签名证书时开启WOODPECKER_GITHUB_SKIP_VERIFY切勿在公网环境随意关闭 TLS 校验。 :::4.9WOODPECKER_GITHUB_PUBLIC_ONLY默认值false配置 OAuth 授权时仅申请可管理公开仓库的令牌不授予对私有仓库的访问权限。适合只运行公开项目流水线的安全场景。其作用在 OAuth Scope 构造处体现得最直接见 github.go#L482-L488基础 Scope 始终包含user:email读取已验证邮箱与read:org读取组织成员信息当OnlyPublic为false默认时追加repoScope令牌可读写私有仓库、管理 Webhook当OnlyPublic为true时改为追加admin:repo_hook与repo:status令牌只能管理公开仓库的 Hook 与提交状态无法访问私有仓库内容。五、常见配置场景与扩展要点5.1 GitHub Cloud 标准配置WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_CLIENTxxxxxxxxxxxxxxxx WOODPECKER_GITHUB_SECRETyyyyyyyyyyyyyyyy这是最常见的场景三个核心变量即可WOODPECKER_GITHUB_URL保持默认的https://github.comAPI 自动指向https://api.github.com/。5.2 GitHub EnterpriseGHES配置WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_URLhttps://github.example.com WOODPECKER_GITHUB_CLIENTxxxxxxxxxxxxxxxx WOODPECKER_GITHUB_SECRETyyyyyyyyyyyyyyyy设置WOODPECKER_GITHUB_URL后驱动会把 API 自动切换为https://github.example.com/api/v3/。若企业实例使用自签名证书再补充WOODPECKER_GITHUB_SKIP_VERIFYtrue5.3 密钥文件化容器/编排环境WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_CLIENT_FILE/run/secrets/github_client WOODPECKER_GITHUB_SECRET_FILE/run/secrets/github_secret将敏感凭据以文件方式注入容器避免出现在环境变量明文或镜像配置中文件读取优先级高于同名环境变量。5.4 仅公开仓库模式WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_PUBLIC_ONLYtrue此时 OAuth 令牌仅携带user:email、read:org、admin:repo_hook、repo:status四个 Scope无repo权限适合公开开源项目的 CI 场景遵循最小权限原则。六、底层驱动工作原理源码佐证GitHub 驱动的工作流可归纳为以下三个关键环节均能在 server/forge/github/github.go 中找到对应实现OAuth 登录与令牌交换Login()方法构造 OAuth 授权 URL 引导用户跳转收到回调携带的 code 后调用config.Exchange()换取令牌再通过 GitHub API 获取用户、验证邮箱必须存在已验证邮箱否则登录失败见 github.go#L136-L143并持久化 AccessToken、RefreshToken 与过期时间见 github.go#L108-L154。令牌刷新Refresh()方法利用 OAuth2 的TokenSource自动刷新过期令牌并回写用户记录见 github.go#L156-L181。源码注释明确指出GitHub OAuth App 不提供 refresh tokenwhen using Github oAuth app no refresh token is provided这正是官方文档警告不要使用 GitHub App 的深层原因——GitHub App 的用户令牌刷新机制与 Woodpecker 当前的驱动实现不兼容。Webhook 解析与 PR 合并引用Hook()方法调用parseHook(r, c.MergeRef)解析 GitHub 推送的 Webhook 负载根据MergeRef决定 PR 事件使用合并引用还是源分支提交随后通过 API 补齐变更文件列表PR 场景或 push 场景再交由调度器创建流水线见 github.go#L679-L717。此外convert.go 负责将 GitHub API 返回的仓库、用户、团队、提交等对象转换为 Woodpecker 内部模型parse.go 负责 Webhook 负载解析配套的 github_test.go、parse_test.go 与 convert_test.go 则覆盖了这些转换与解析逻辑的单元测试可作为阅读驱动行为的参考入口。七、验证与故障排查完成配置并重启 Woodpecker server 后可以从以下角度验证对接是否成功Web 界面登录访问 Woodpecker 实例点击登录应跳转至 GitHub 的 OAuth 授权页授权后回到/authorize回调并成功登录仓库同步登录后在仓库管理页应能列出你在 GitHub 有权限的仓库含组织仓库源码中对应Repos()方法按每页 100 条拉取见 github.go#L232-L249Webhook 触发在 GitHub 仓库设置中添加 Webhook 指向 Woodpecker 实例通常由驱动在仓库激活时自动注册推送代码或创建 PR 应能触发流水线。常见问题排查方向登录报错 no verified Email address for GitHub accountGitHub 账号未设置已验证邮箱需在 GitHub 账号设置中完成邮箱验证回调地址 404检查 Callback URL 是否严格为https://woodpecker实例地址/authorize且服务端OAuthHost配置与该地址一致PR 流水线构建的提交不符合预期检查WOODPECKER_GITHUB_MERGE_REF是否为期望值默认true使用合并引用企业实例 TLS 报错确认WOODPECKER_GITHUB_URL正确、证书可信任必要时按上文配置WOODPECKER_GITHUB_SKIP_VERIFYtrue。如需了解更多 Forge 对接方式Gitea、Forgejo、GitLab、Bitbucket 等可参阅同目录下的 11-overview.md以及各 Forge 对应的配置文档。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐LangChain4j GitHub 文档加载器用 GitHubDocumentLoader 从仓库加载文件与目录构建 RAG 语料库LangChain4j GitHub 文档加载器用 GitHubDocumentLoader 从仓库加载文件与目录构建 RAG 语料库 本文围绕 LangChCI/CDDevOpsWoodpecker CI 与 Gitea 集成配置指南从 OAuth 注册到环境变量详解Woodpecker CI 与 Gitea 集成配置指南从 OAuth 注册到环境变量详解 Woodpecker CI 内置了对 Gitea 的完整支持可通CI/CDDevOpsWoodpecker CI/CD 终极指南环境变量与服务配置完全解析Woodpecker CI/CD 终极指南环境变量与服务配置完全解析 Woodpecker 是一个简单而功能强大的 CI/CD 引擎其环境变量和服务配置功能CI/CDDevOps上一篇为什么需要glogg让海量日志分析不再痛苦下一篇BilibiliDown5分钟掌握跨平台B站视频下载神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考