Woodpecker Secrets 完全指南：三级密钥体系、from_secret 注入与 CLI 实战（v2.8）

CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载Woodpecker 提供独立于 YAML 配置文件之外的中央密钥存储central secret store允许以命名参数的形式保存密钥并在流水线运行时按需注入到单个步骤中。本文以 Woodpecker v2.8 文档为核心结合仓库源码server/model/secret.go、cli/repo/secret/secret_add.go、pipeline/frontend/yaml/compiler/深入讲解仓库级 / 组织级 / 全局级三级密钥的优先级规则、from_secret推荐用法、参数预处理转义、Pull Request 事件安全策略、镜像过滤机制以及通过 CLI 添加与管理密钥的完整实战命令。三级密钥体系与优先级Woodpecker 提供三个不同层级来为流水线添加密钥。当同一个密钥在多个层级同时定义时按以下优先级生效仓库级Repository secrets 组织级Organization secrets 全局级Global secrets仓库级密钥Repository secrets对某个仓库的所有流水线可用。在server/model/secret.go中判定方法为s.RepoID ! 0 s.OrgID 0。组织级密钥Organization secrets对某个组织的所有流水线可用。判定方法为s.RepoID 0 s.OrgID ! 0。全局级密钥Global secrets由实例管理员admin配置对整个Woodpecker 实例的所有流水线可用因此只应存放允许所有用户读取的密钥。判定方法为s.RepoID 0 s.OrgID 0见 server/model/secret.go。从源码看密钥在数据层统一由Secret结构体表示server/model/secret.go包含ID、OrgID、RepoID、Name、Value、Images、Events、Note等字段其中OrgID/RepoID的组合值决定了密钥所属层级Images与Events分别用于镜像过滤与事件过滤。所有密钥统一存储在secrets数据表中TableName()返回secrets。在命令中使用密钥已弃用方式版本警告在命令中直接使用密钥的方式自 v2.8 起已被标记为弃用deprecated计划在 v3 中移除。请改用下文介绍的secrets in settings and environmentfrom_secret方式v2.8 中即可开始迁移。在弃用方式下密钥会作为大写环境变量暴露给流水线步骤与插件只要在secrets段中声明其用途即可在命令部分引用steps: - name: docker image: docker commands: - echo $docker_username - echo $DOCKER_PASSWORD secrets: [ docker_username, DOCKER_PASSWORD ]环境变量的大小写不会改变但密钥匹配是大小写不敏感的。上例中DOCKER_PASSWORD即使在密钥实际名为docker_password时也能匹配成功。这与编译器的实现一致在 pipeline/frontend/yaml/compiler/option.go 中WithSecret通过strings.ToLower(secret.Name)将密钥名统一转为小写存入compiler.secrets映射从而保证匹配时不区分大小写。参数预处理注意事项请注意参数表达式会经过预处理。当在参数表达式中使用密钥时应当进行转义使用双美元符号steps: - name: docker image: docker commands: - - echo ${docker_username} - - echo ${DOCKER_PASSWORD} - echo $${docker_username} - echo $${DOCKER_PASSWORD} secrets: [ docker_username, DOCKER_PASSWORD ]若不加$$转义${...}形式的表达式会在预处理阶段被提前展开导致密钥无法以预期形式注入到命令中。推荐方式在 settings 与 environment 中使用from_secret使用from_secret语法可以将密钥值赋给某个 setting 或 environment 变量。示例将名为secret_token的密钥作为名为TOKEN_ENV的环境变量传入steps: env-secret-example: image: alpine commands: - echo The secret is $TOKEN_ENV environment: TOKEN_ENV: from_secret: secret_token同样的语法也适用于 settings。例如将名为secret_token的密钥传给名为token的 setting该值随后会以PLUGIN_TOKEN环境变量的形式出现在插件中详见 插件开发文档steps: - name: settings-secret-example image: my-plugin settings: token: from_secret: secret_token源码级原理from_secret如何被解析from_secret的解析逻辑位于 pipeline/frontend/yaml/compiler/settings/params.go 的injectSecret函数当某个 map 值中存在from_secret键时编译器会调用getSecretValue回调取得密钥值并直接替换该参数若密钥不存在则返回错误。该检查同样作用于复杂类型如嵌套 map、slice内部通过injectSecretRecursive递归探测params.go。密钥值在注入前的可用性校验由 pipeline/frontend/yaml/compiler/compiler.go 的Secret.Available完成依次检查若密钥设置了镜像过滤AllowedPlugins非空而当前步骤不是插件plugin步骤则拒绝注入当前步骤镜像是否命中AllowedPlugins列表当前流水线事件是否命中密钥的Events过滤Secret.Matchcompiler.go其中所有 pull 类事件统一按EventPull处理。注入时settings 以PLUGIN_前缀、大写形式写入环境变量environment 则以原样无前缀、不转大写写入见 pipeline/frontend/yaml/compiler/convert.go同时通过secretMapping记录哪些环境变量来自密钥供运行时日志脱敏使用convert.go中的SecretMapping字段。在 Pull Request 事件中使用密钥默认情况下密钥不会暴露给 Pull Request。可以通过创建密钥时启用pull_request事件类型来覆盖该行为方式为 UI 操作或 CLI 命令见下文 CLI 示例。:::note 安全警告 向 Pull Request 暴露密钥时请务必谨慎。如果你的仓库是开源的且接受 Pull Request你的密钥并不安全——恶意攻击者可以提交一个精心构造的 Pull Request 来泄露你的密钥。 :::镜像过滤Image filter为防止恶意使用导致密钥被滥用可以将密钥限制到一组镜像。一旦设置了镜像过滤密钥对任何其他插件不可用指没有用户自定义命令的步骤。如果你或攻击者定义了显式命令commands密钥将不会提供给该容器以防止泄露。这一点在源码中得到双重保障Secret.Available中一旦AllowedPlugins非空普通命令步骤非插件直接无法使用该密钥并会给出提示secret %q is only allowed to be used by plugins (a filter has been set on the secret)compiler.go。同时server/model/secret.go中的Validate()会对每个镜像条目校验其是否符合 Docker 镜像命名规则正则validDockerImageString支持 registry 主机名、端口、命名空间、tag、sha256:digest 等写法不合法的镜像名会返回ErrSecretImageInvalidserver/model/secret.go。添加密钥密钥可以在 Woodpecker UI 中添加也可以使用 CLI 添加。CLI 示例1. 使用默认设置创建密钥。密钥将对流水线中的所有镜像可用并且只对 push、tag 与 deploy 事件生效不含 pull request 事件woodpecker-cli secret add \ -repository octocat/hello-world \ -name aws_access_key_id \ -value value从源码看cli/repo/secret/secret_add.go 中定义了默认事件集合defaultSecretEvents即push、tag、release、deploy四种当未通过-event指定任何事件时自动采用该默认集合。同时密钥名会通过strings.ToLower转为小写后提交secretCreate函数。2. 创建密钥并限制到单个镜像woodpecker-cli secret add \ -repository octocat/hello-world \ -image plugins/s3 \ -name aws_access_key_id \ -value value3. 创建密钥并限制到一组镜像重复-image参数woodpecker-cli secret add \ -repository octocat/hello-world \ -image plugins/s3 \ -image peloton/woodpecker-ecs \ -name aws_access_key_id \ -value value4. 创建密钥并启用多个 hook 事件重复-event参数woodpecker-cli secret add \ -repository octocat/hello-world \ -image plugins/s3 \ -event pull_request \ -event push \ -event tag \ -name aws_access_key_id \ -value value5. 使用 curl语法从文件加载密钥值。这是从文件加载密钥以保留换行符的推荐方式woodpecker-cli secret add \ -repository octocat/hello-world \ -name ssh_key \ -value /root/ssh/id_rsa文件加载在 cli/repo/secret/secret_add.go 中实现当-value以开头时CLI 会读取后的文件路径内容作为密钥值从而完整保留文件中的换行符例如 SSH 私钥等多行内容。补充密钥校验与 UI 管理无论通过 UI 还是 CLI 添加密钥最终都会经过 server/model/secret.go 的Secret.Validate()校验Events必须至少指定一个有效事件ErrSecretEventInvalidImages中每个镜像名都必须合法ErrSecretImageInvalidName与Value均不能为空分别对应ErrSecretNameInvalid、ErrSecretValueInvalid。在 UI 中管理员与仓库维护者可以通过对应层级的 Secrets 管理页面完成同样的创建、编辑SecretPatch支持更新 name/value/images/events/note与删除操作。此外CLI 还提供配套的管理命令secret ls、secret rm、secret update、secret show等位于 cli/repo/secret 目录与secret add一同构成完整的密钥生命周期管理能力。总结密钥按仓库 组织 全局三级组织同名校验优先级从上到下递减全局级只存放可被所有用户读取的内容v2.8 起推荐使用from_secret语法注入密钥到settings/environment替代旧的secrets命令方式插件中以PLUGIN_前缀环境变量消费在参数表达式中使用密钥需以$$转义避免预处理提前展开Pull Request 默认不暴露密钥需显式开启pull_request事件开源仓库务必谨慎镜像过滤可把密钥锁定到指定插件镜像任何带显式 commands 的普通步骤都无法读取从编译期与校验期双重保障安全。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker 秘密Secrets管理与使用完整指南from_secret 注入、三级作用域与 CLI 操作Woodpecker 秘密Secrets管理与使用完整指南 from_secret 注入、三级作用域与 CLI 操作 Woodpecker 提供集中式的密CI/CDDevOpsEarthly Secrets 实战指南在 Earthfile 中安全注入密码与 API 密钥Earthly Secrets 实战指南在 Earthfile 中安全注入密码与 API 密钥 Secrets密钥是构建过程中需要保护、不应写入 EartCI/CDDevOps构建工具OneUptime Monitor Secrets 实战指南加密密钥的创建、注入与访问控制OneUptime Monitor Secrets 实战指南加密密钥的创建、注入与访问控制 Monitor Secrets 是 OneUptime 内置的敏感可观测性后端运维前端云原生微服务AI Agent上一篇naive-ui 贡献指南分支工作流、常用命令与文档/变更日志规范全解下一篇告别卡顿Magpie GPU加速技术完全启用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考