企业官网建设流程全解析

• 文档
• 教程
• 知识库

导读

在基于 Git 的 Heroku 部署流程中，平台默认只会在推送到远程master分支时触发构建与发布。本文结合 TIL 仓库中 devops/push-non-master-branch-to-heroku.md 这篇笔记，讲清"为什么git push heroku staging不会触发部署"，以及如何借助 Git 的 refspec 语法（staging:master）把本地非 master 分支安全地部署到 Heroku，实现 staging 环境的独立发布。

Heroku 的部署规则：只有 master 分支才会被构建

当使用 Git 向 Heroku 部署应用时，平台默认期望推送目标是远程的master分支。执行下面的命令：

$ git push heroku master

Heroku 会收到这次推送，随后尝试构建并运行你的应用。也就是说，heroku这个 remote 的master分支是平台的"部署入口"——推送一旦命中它，就会触发 buildpack 构建、release 发布等完整流程。

这条规则带来的直接后果是：如果应用维护着一个独立的staging分支，希望把它推送到 Heroku 上的 staging 环境，直接执行下面这条命令是行不通的：

$ git push heroku staging

Heroku 只会对推送到远程master分支的提交执行构建。因此上述命令虽然会向远程staging分支写入提交，却不会触发任何构建与部署，staging 环境也就得不到更新。

解决方案：用 refspec 把本地分支映射到远程 master

要绕过这个限制，思路是让"本地分支名"与"远程分支名"解耦——本地仍然推送staging，但在 refspec 中显式声明它对应远程的master分支：

$ git push heroku staging:master

这条命令的含义是：把本地staging分支的提交推送到herokuremote 的master分支。由于最终落点仍是远程master，Heroku 的部署钩子会被正常触发，从而完成对 staging 应用的构建与发布。

这是git push中<src>:<dst>refspec 标准写法的典型应用。它并不只适用于 Heroku——在 git/push-to-a-branch-on-another-remote.md 这篇 TIL 中，同样的语法被用来将本地staging分支推送到某个 remote 的main分支：

$ git push heroku staging:main

两处用法唯一的区别只是目标分支名（mastervsmain），语法与原理完全一致。这也说明，凡是"本地分支名与目标远程分支名不一致"的推送场景，都可以借助该 refspec 语法完成映射。

进阶：用HEAD让当前分支直接部署

如果不想每次手写分支名，TIL 仓库的 git/push-to-a-branch-on-another-remote.md 还记录了一种更轻量的写法：

$ git push heroku HEAD

HEAD代表当前检出的分支，这条命令会把当前分支的状态推送到herokuremote 上同名的分支。结合本文主题，如果当前正处在staging分支上，希望部署到 Heroku，可以组合使用：

$ git push heroku HEAD:master

将当前分支的提交直接映射到 Heroku 的master分支，省去显式写分支名。这类"把当前分支推送到另一个名字的远程分支"的需求，与上文staging:master属于同一类 refspec 应用。

部署前后的配套实践

围绕"非 master 分支上 Heroku"这一场景，TIL 仓库还记录了若干配套操作，值得一并参考：

• 分支改动与试运行：heroku/deploy-a-review-app-to-a-different-stack.md 提到，在做 Ruby 版本升级、切换 stack（如从heroku-16到heroku-18）等变更后，可以先把改动推到分支再转成 PR，通过 Heroku 的 Review App 在临时环境验证，避免直接冲击生产。这与本文"先走 staging 分支、再部署"的思路一脉相承。
• 环境隔离确认：Heroku 上每个应用有独立的配置与数据库，staging 与 production 通常是两个独立 App。部署前建议先确认当前仓库的herokuremote 指向的是 staging 应用而非生产应用，可用git remote -v查看 remote 地址。

小结

把非 master 分支推送到 Heroku 的关键就一句话：Heroku 只认远程master分支的推送，因此用git push heroku staging:master这种 refspec 语法完成分支映射。掌握这一写法后，无论分支叫staging、dev还是别的名字，都能在保留本地分支命名习惯的同时，顺利触发 Heroku 的构建部署流程。

• 文档
• 教程
• 知识库