企业官网建设流程全解析

• CI/CD
• DevOps

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 驱动。整体链路如下：

1. 用户在 Woodpecker 页面点击登录，服务端构造 GitHub OAuth 授权链接并跳转；
2. 用户在 GitHub 完成授权后，GitHub 回调 Woodpecker 的/authorize端点并携带授权码；
3. Woodpecker 服务端用授权码换取访问令牌（Access Token），并调用 GitHub API 拉取用户信息、邮箱、组织与仓库列表；
4. 之后 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 App（OAuth 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 时，需要填写以下字段：

其中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_GITHUB=true WOODPECKER_GITHUB_CLIENT=YOUR_GITHUB_CLIENT_ID WOODPECKER_GITHUB_SECRET=YOUR_GITHUB_CLIENT_SECRET

• WOODPECKER_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.com

GitHub 服务器地址。默认指向 GitHub Cloud；当对接GitHub Enterprise（GitHub Enterprise Server，GHES）时，应将其设置为你的企业实例地址，例如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_GITHUB=true WOODPECKER_GITHUB_CLIENT=xxxxxxxxxxxxxxxx WOODPECKER_GITHUB_SECRET=yyyyyyyyyyyyyyyy

这是最常见的场景：三个核心变量即可，WOODPECKER_GITHUB_URL保持默认的https://github.com，API 自动指向https://api.github.com/。

5.2 GitHub Enterprise（GHES）配置

WOODPECKER_GITHUB=true WOODPECKER_GITHUB_URL=https://github.example.com WOODPECKER_GITHUB_CLIENT=xxxxxxxxxxxxxxxx WOODPECKER_GITHUB_SECRET=yyyyyyyyyyyyyyyy

设置WOODPECKER_GITHUB_URL后，驱动会把 API 自动切换为https://github.example.com/api/v3/。若企业实例使用自签名证书，再补充：

WOODPECKER_GITHUB_SKIP_VERIFY=true

5.3 密钥文件化（容器/编排环境）

WOODPECKER_GITHUB=true WOODPECKER_GITHUB_CLIENT_FILE=/run/secrets/github_client WOODPECKER_GITHUB_SECRET_FILE=/run/secrets/github_secret

将敏感凭据以文件方式注入容器，避免出现在环境变量明文或镜像配置中；文件读取优先级高于同名环境变量。

5.4 仅公开仓库模式

WOODPECKER_GITHUB=true WOODPECKER_GITHUB_PUBLIC_ONLY=true

此时 OAuth 令牌仅携带user:email、read:org、admin:repo_hook、repo:status四个 Scope，无repo权限，适合公开开源项目的 CI 场景，遵循最小权限原则。

六、底层驱动工作原理（源码佐证）

GitHub 驱动的工作流可归纳为以下三个关键环节，均能在 server/forge/github/github.go 中找到对应实现：

1. OAuth 登录与令牌交换：Login()方法构造 OAuth 授权 URL 引导用户跳转，收到回调携带的 code 后调用config.Exchange()换取令牌，再通过 GitHub API 获取用户、验证邮箱（必须存在已验证邮箱，否则登录失败，见 github.go#L136-L143），并持久化 AccessToken、RefreshToken 与过期时间（见 github.go#L108-L154）。

2. 令牌刷新：Refresh()方法利用 OAuth2 的TokenSource自动刷新过期令牌并回写用户记录（见 github.go#L156-L181）。源码注释明确指出：GitHub OAuth App 不提供 refresh token（"when using Github oAuth app no refresh token is provided"），这正是官方文档警告不要使用 GitHub App 的深层原因——GitHub App 的用户令牌刷新机制与 Woodpecker 当前的驱动实现不兼容。

3. 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 后，可以从以下角度验证对接是否成功：

1. Web 界面登录：访问 Woodpecker 实例，点击登录应跳转至 GitHub 的 OAuth 授权页，授权后回到/authorize回调并成功登录；
2. 仓库同步：登录后在仓库管理页应能列出你在 GitHub 有权限的仓库（含组织仓库），源码中对应Repos()方法，按每页 100 条拉取（见 github.go#L232-L249）；
3. Webhook 触发：在 GitHub 仓库设置中添加 Webhook 指向 Woodpecker 实例（通常由驱动在仓库激活时自动注册），推送代码或创建 PR 应能触发流水线。

常见问题排查方向：

• 登录报错 "no verified Email address for GitHub account"：GitHub 账号未设置已验证邮箱，需在 GitHub 账号设置中完成邮箱验证；
• 回调地址 404：检查 Callback URL 是否严格为https://<woodpecker实例地址>/authorize，且服务端OAuthHost配置与该地址一致；
• PR 流水线构建的提交不符合预期：检查WOODPECKER_GITHUB_MERGE_REF是否为期望值（默认true使用合并引用）；
• 企业实例 TLS 报错：确认WOODPECKER_GITHUB_URL正确、证书可信任，必要时按上文配置WOODPECKER_GITHUB_SKIP_VERIFY=true。

如需了解更多 Forge 对接方式（Gitea、Forgejo、GitLab、Bitbucket 等），可参阅同目录下的 11-overview.md，以及各 Forge 对应的配置文档。

• CI/CD
• DevOps