Atlantis 自动合并（Automerge）：配置 pull request 在计划全部应用成功后自动合并的完整指南

DevOpsCI/CD基础设施【免费下载链接】atlantisTerraform Pull Request Automation项目地址https://gitcode.com/gh_mirrors/at/atlantis点击查看免费下载Atlantis 作为 Terraform Pull Request Automation 工具除了自动执行 plan/apply 之外还提供了一项让整个 IaC 交付流程进一步自动化的重要能力自动合并Automerge。当启用后只要某个 pull request 中所有项目的 plan 都成功并通过atlantis apply完成应用Atlantis 就会自动将 PR 合并到目标分支无需开发者再手动点击合并按钮。本文以官方文档 runatlantis.io/es/docs/automerging.md西班牙语版与英文版内容一致为核心结合仓库源码深入讲解启用方式、合并方法merge/rebase/squash的设置、底层触发逻辑与权限要求帮助你在自己的仓库中安全、正确地开启这条自动化流水线。说明上图取自 runatlantis.io/docs/images/automerge.png展示了启用自动合并后 Atlantis 在 PR 上发布的评论样式。自动合并的工作方式自动合并的语义非常简单在 pull request 中所有项目的 plan 全部成功应用之后Atlantis 自动将该 pull request 合并。整个流程可以概括为开发者推送新 commit触发 autoplan自动计划所有相关项目的 plan 成功执行生成可应用的 plan开发者或 CI对全部项目执行atlantis apply所有 plan 均成功应用Atlantis 在 PR 上评论Automatically merging because all plans have been successfully applied.随后调用 VCS API 完成合并。其中第 4 步的评论文案与合并动作定义在 server/events/command_runner.go 与 server/events/automerger.go 中。AutoMerger结构体持有 VCS 客户端、全局自动合并开关与全局默认合并方法三个依赖// server/events/automerger.go type AutoMerger struct { VCSClient vcs.Client GlobalAutomerge bool GlobalAutomergeMethod string }automerge方法会先遍历 pull 的状态中的每个项目只要存在一个项目的状态不是AppliedPlanStatus就立即中止合并并记录日志——这正是所有 plan 必须全部应用成功这一硬性约束的源码实现// 仅当所有项目都已被成功应用时才执行自动合并 for _, p : range pullStatus.Projects { if p.Status ! models.AppliedPlanStatus { ctx.Log.Info(not automerging because project at dir %q, workspace %q has status %q, p.RepoRelDir, p.Workspace, p.Status.String()) return } }如何启用自动合并自动合并可以通过以下两种方式启用且二者的优先级关系明确仓库配置atlantis.yaml中显式声明的值优先于服务端全局参数。方式一服务端全局启用启动atlantis server时传入--automerge标志atlantis server --automerge该标志对应的配置项定义在 cmd/server.go默认值为false官方描述为Automatically merge pull requests when all plans are successfully applied.。传入该标志即表示该 Atlantis 实例服务的所有仓库默认启用自动合并。在 server/user_config.go 中该配置以Automerge bool字段承载mapstructure 键名为automerge因此在服务端配置文件YAML中同样可以写作automerge: true方式二仓库级配置优先在仓库根目录的atlantis.yaml中设置automerge: trueversion: 3 automerge: true projects: - dir: .:::tip 注意 如果一个仓库存在atlantis.yaml文件那么该仓库中的每一个项目都必须配置在projects键下否则 Atlantis 不会对其执行自动计划/应用。 :::atlantis.yaml中的automerge字段由 server/core/config/raw/repo_cfg.go 解析类型为*boolyaml:automerge,omitempty。当仓库配置显式给出该字段时它会覆盖服务端的全局设置——这与AutoMerger.automergeEnabled的逻辑一致// server/events/automerger.go // 若存在项目级配置则优先使用项目配置否则回退到全局配置 func (c *AutoMerger) automergeEnabled(projectCmds []command.ProjectContext) bool { automerge : c.GlobalAutomerge if len(projectCmds) 0 { automerge projectCmds[0].AutomergeEnabled } return automerge }从源码结构看projectCmds[0].AutomergeEnabled即由仓库atlantis.yaml的automerge字段经配置解析链路写入每个项目上下文定义见 server/events/command/project_context.go从而实现了仓库显式声明优先的行为。如何为单个 apply 命令临时禁用如果服务端或仓库已全局启用自动合并但你希望在某一次特定的atlantis apply执行后不触发合并可以在命令中追加--auto-merge-disabled选项atlantis apply --auto-merge-disabled该选项解析后写入命令上下文的AutoMergeDisabled字段见 server/events/event_parser.go并在执行时作为自动合并的拦截条件之一// server/events/apply_command_runner.go if a.autoMerger.automergeEnabled(projectCmds) !cmd.AutoMergeDisabled { ... a.autoMerger.automerge(ctx, pullStatus, ...) }也就是说只有自动合并已启用且本次命令未显式禁用时合并动作才会发生。这为临时需要人工确认的合并场景提供了逃生口。如何设置自动合并的合并方法自动合并默认采用的合并方式取决于 VCS 平台。Atlantis 支持通过服务端参数或单条命令参数指定合并方法可选值固定为以下三种merge— 标准合并提交merge commitrebase— 变基合并squash— 压缩为单个提交合并。合法取值在 cmd/server.go 中集中定义// ValidAutomergeMethods are the valid merge methods that can be set for the // automerge-method flag. var ValidAutomergeMethods []string{merge, rebase, squash}若传入非法值服务启动校验会直接报错见 cmd/server.goinvalid --automerge-method: must be one of [merge rebase squash]设置服务端默认合并方法通过--automerge-method服务端标志或ATLANTIS_AUTOMERGE_METHOD环境变量设置全局默认atlantis server --automerge-method method对应的服务端配置字段为 server/user_config.go 中的AutomergeMethod stringmapstructure 键名automerge-method。当单条命令未显式指定合并方法时AutoMerger.automerge会回退到该全局默认值// server/events/automerger.go // 当评论命令未通过 --auto-merge-method 指定合并方法时回退到服务端默认值 if mergeMethod { mergeMethod c.GlobalAutomergeMethod }为单条 apply 命令覆盖合并方法在atlantis apply时使用--auto-merge-method覆盖服务端默认值atlantis apply --auto-merge-method method该值同样经 server/events/event_parser.go 解析为命令上下文的AutoMergeMethod最终作为pullOptions.MergeMethod传给 VCS 客户端完成合并。GitHub 上的实际合并行为官方文档明确指出合并方法的完整实现目前仅适用于 GitHub VCS。在 server/events/vcs/github/client.go 的MergePull实现中可以看到Atlantis 会先读取仓库设置检查仓库是否允许merge、rebase、squash三种合并方式对应 GitHub API 的allow_merge_commit、allow_rebase_merge、allow_squash_merge然后遵循以下决策逻辑若命令/配置显式指定了合并方法先校验该方法是否合法再校验仓库 PR 设置是否允许该方法任一不满足都会返回错误并中止合并若未显式指定默认使用merge若仓库不允许 merge commit则按rebase、squash的顺序自动选择一个仓库允许的方式。因此如果你的 GitHub 仓库关闭了某些合并类型例如只允许 squash mergeAtlantis 会自动适配仓库设置避免因合并方式不匹配而导致自动合并失败。使用自动合并的前提条件所有 plan 必须成功启用自动合并后一个 pull request 中的所有 plan 都必须成功之后任何一个plan 才可能被应用。这意味着你无法只对其中成功的项目单独执行 apply。举例说明假设一个 PR 同时修改了两个 Terraform 项目分别位于dir1/与dir2/打开 PR两个项目均被 autoplandir2/的 plan 因 Terraform 语法错误而失败。此时即便dir1/的 plan 成功了你也不能运行atlantis apply -d dir1因为所有plan 成功是任何plan 得以被保存/应用的前提。修复dir2/的问题后推送新 commitautoplan 会重新执行届时两个 plan 都能成功你才能将二者一并 apply随后触发自动合并。所有 plan 必须全部被应用如果多个项目/目录/workspace 都被配置为自动计划autoplan那么它们必须全部被 applyAtlantis 才会自动合并 PR。这一点正是前面AutoMerger.automerge中遍历所有项目、任一状态不是AppliedPlanStatus即中止逻辑的直观体现——只要还有任何一个项目停留在 plan 完成但未应用的状态合并就不会发生。对应的测试用例也验证了该行为例如 server/events/apply_command_runner_test.go 中对所有项目均已应用时才调用MergePull、存在未应用项目时MergePull绝不被调用的各种场景均有断言。需要足够的权限Atlantis 使用的 VCS 用户如 GitHub App 或机器人的身份必须拥有合并 pull request 的权限。若权限不足MergePull调用会失败Atlantis 会记录错误日志并在 PR 上发布失败评论// server/events/automerger.go failureComment : fmt.Sprintf(Automerging failed:\n\n%s\n, err)因此在实际部署时请确认授予 Atlantis VCS 凭据token以pull写入权限GitHub 上通常对应Pull Requests: write及目标仓库的合并权限。自动合并执行时的完整检查链综合 server/events/apply_command_runner.go 的实现一次atlantis apply在即将触发自动合并前会依次完成以下校验apply 结果无错误result.HasErrors()为真则直接返回不合并PR 状态新鲜度检查若 apply 期间 PR 的 head commit 发生变化pullStatusFreshnessError拒绝合并并要求重新atlantis plan自动合并是否启用automergeEnabled(projectCmds)仓库配置优先且!cmd.AutoMergeDisabled禁用标签检查若服务端配置了--disable-automerge-label定义见 server/user_config.go则查询 PR 标签若命中该标签同样跳过合并全项目已应用所有项目状态均为AppliedPlanStatus执行合并发表自动合并评论携带合并方法与是否删除源分支DeleteSourceBranchOnMerge选项调用MergePull。这套完整链路保证了自动合并只在最安全、最符合预期的时刻发生避免把有冲突、有失败或尚未完成应用的 PR 合入主干。总结配置项作用范围设置方式--automerge/automerge: true服务端全局 / 仓库级仓库优先atlantis server标志、服务端配置或atlantis.yaml--auto-merge-disabled单条 apply 命令atlantis apply选项--automerge-method/ATLANTIS_AUTOMERGE_METHOD服务端默认合并方法merge/rebase/squash服务端标志或环境变量--auto-merge-method单条 apply 命令atlantis apply选项--disable-automerge-label服务端全局禁用标签atlantis server标志启用自动合并后从推送代码到基础设施变更合入主干的最后一个手动环节被消除Terraform 变更交付实现端到端自动化。只要牢记所有 plan 成功且全部应用这一核心前提并为 Atlantis 的 VCS 用户授予合并权限你就能安全地让 Atlantis 帮你完成最后一步合并操作。赞分享DevOpsCI/CD基础设施【免费下载链接】atlantisTerraform Pull Request Automation项目地址https://gitcode.com/gh_mirrors/at/atlantis点击查看免费下载相关推荐手速跑不赢刷新大麦抢票工具 ticket-purchase 双端自动下单快速上手与避坑手速跑不赢刷新大麦抢票工具 ticket purchase 双端自动下单快速上手与避坑 热门票开售即秒空你刷新得再快也跑不过服务器。ticket purchGUI 自动化RPAKubernetes 社区 Pull Request 全流程指南从提交、评审到自动合并的完整实践Kubernetes 社区 Pull Request 全流程指南从提交、评审到自动合并的完整实践 Kubernetes 社区每年通过 GitHub 处理数以万开源治理文档研发协作UnityFx.Outline脚本开发入门用OutlineBehaviour实现物体级轮廓控制UnityFx.Outline脚本开发入门用OutlineBehaviour实现物体级轮廓控制 UnityFx.Outline是一款强大的Unity3D屏幕空图形学游戏开发上一篇Kubernetes Elections 选举子项目指南Elekto 平台、Steering 委员会选举与团队选举申请全流程下一篇5分钟快速解决Buzz音频转录软件8大常见问题终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考