GitHub 集成 #
GitHub 集成概述 #
Heroku 可以与 GitHub 深度集成，实现自动部署、持续集成和 Review Apps 等功能。
集成功能 #
| 功能 | 说明 |
|---|---|
| 自动部署 | 推送到 GitHub 自动部署到 Heroku |
| CI/CD | 集成 Heroku CI 进行测试 |
| Review Apps | 为 PR 自动创建临时应用 |
| Pipeline | 管理多环境部署流程 |
连接 GitHub #
在 Dashboard 中连接 #
- 登录 Heroku Dashboard
- 进入应用设置页面
- 找到 “Deployment method” 部分
- 点击 “Connect to GitHub”
- 授权 Heroku 访问 GitHub 仓库
CLI 配置 #
bash
# 查看应用信息
heroku apps:info
# 检查 GitHub 连接状态
heroku apps:info | grep -i github
自动部署 #
配置自动部署 #
text
┌─────────────────────────────────────────────────────┐
│ 自动部署配置流程 │
├─────────────────────────────────────────────────────┤
│ │
│ 1. 连接 GitHub 仓库 │
│ └── 选择组织和仓库 │
│ │
│ 2. 选择部署分支 │
│ └── main / master / develop │
│ │
│ 3. 启用自动部署 │
│ └── 勾选 "Wait for CI to pass before deploy" │
│ │
│ 4. 保存配置 │
│ │
└─────────────────────────────────────────────────────┘
部署流程 #
text
GitHub Push ──► GitHub Webhook ──► Heroku 接收
│
▼
┌──────────────┐
│ 运行 CI 测试 │
│ (如果启用) │
└──────┬───────┘
│
┌─────────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
测试通过 测试失败 无 CI
│ │ │
▼ ▼ ▼
触发部署 不部署 触发部署
│
▼
┌──────────┐
│ 构建应用 │
└────┬─────┘
│
▼
┌──────────┐
│ 部署成功 │
└──────────┘
Dashboard 配置 #
text
┌─────────────────────────────────────────────────────┐
│ Automatic deploys │
├─────────────────────────────────────────────────────┤
│ │
│ Deploy branch: [main ▼] │
│ │
│ ☑ Wait for CI to pass before deploy │
│ │
│ [Enable Automatic Deploys] │
│ │
└─────────────────────────────────────────────────────┘
Heroku Pipeline #
创建 Pipeline #
bash
# 创建 Pipeline
heroku pipelines:create myapp-pipeline -a myapp-staging -s staging
# 添加应用到 Pipeline
heroku pipelines:add myapp-pipeline -a myapp-production -s production
# 查看 Pipeline
heroku pipelines:info myapp-pipeline
Pipeline 结构 #
text
┌─────────────────────────────────────────────────────┐
│ Pipeline 结构 │
├─────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Review Apps │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ PR #123 │ │ PR #124 │ │ PR #125 │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Staging │ │
│ │ ┌─────────────────────────────────────┐ │ │
│ │ │ myapp-staging │ │ │
│ │ └─────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Production │ │
│ │ ┌─────────────────────────────────────┐ │ │
│ │ │ myapp-production │ │ │
│ │ └─────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────┘
推广到生产 #
bash
# 从 Staging 推广到 Production
heroku pipelines:promote -a myapp-staging
# 输出示例
# Promoting myapp-staging to myapp-production...
# done, v10
Review Apps #
什么是 Review Apps？ #
Review Apps 为每个 Pull Request 自动创建临时应用，方便测试和审查。
启用 Review Apps #
- 在 Pipeline 页面点击 “Enable Review Apps”
- 选择创建应用的方式
- 配置 app.json
app.json 配置 #
json
{
"name": "myapp",
"description": "My awesome app",
"repository": "https://github.com/username/myapp",
"buildpacks": [
{
"name": "heroku/nodejs"
}
],
"env": {
"NODE_ENV": {
"value": "review"
},
"SECRET_KEY": {
"generator": "secret"
}
},
"formation": {
"web": {
"quantity": 1,
"size": "eco"
}
},
"addons": [
{
"plan": "heroku-postgresql:mini"
}
],
"scripts": {
"postdeploy": "npm run db:migrate && npm run db:seed"
}
}
Review Apps 流程 #
text
┌─────────────────────────────────────────────────────┐
│ Review Apps 流程 │
├─────────────────────────────────────────────────────┤
│ │
│ 1. 创建 Pull Request │
│ └── GitHub 通知 Heroku │
│ │
│ 2. 创建 Review App │
│ └── 使用 app.json 配置 │
│ │
│ 3. 部署应用 │
│ └── 构建并启动应用 │
│ │
│ 4. 添加评论 │
│ └── 在 PR 中添加应用链接 │
│ │
│ 5. 测试审查 │
│ └── 访问临时应用进行测试 │
│ │
│ 6. 关闭 PR │
│ └── 自动删除 Review App │
│ │
└─────────────────────────────────────────────────────┘
管理 Review Apps #
bash
# 查看 Review Apps
heroku apps --filter "review-"
# 删除特定 Review App
heroku apps:destroy review-app-name --confirm review-app-name
# 配置 Review Apps 自动销毁时间
# 在 Dashboard 中设置
Heroku CI #
启用 Heroku CI #
bash
# 在 Pipeline 中启用 CI
heroku ci:enable -a myapp-staging
# 查看 CI 状态
heroku ci:info
配置测试 #
json
// app.json
{
"environments": {
"test": {
"scripts": {
"test": "npm test"
},
"addons": [
"heroku-postgresql:mini"
]
}
}
}
CI 流程 #
yaml
# .github/workflows/ci.yml (GitHub Actions 替代方案)
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm ci
- run: npm test
GitHub Actions 集成 #
完整 CI/CD 配置 #
yaml
# .github/workflows/heroku.yml
name: Heroku CI/CD
on:
push:
branches: [main]
pull_request:
branches: [main]
env:
HEROKU_API_KEY: ${{ secrets.HEROKU_API_KEY }}
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
- name: Run linter
run: npm run lint
deploy-staging:
needs: test
runs-on: ubuntu-latest
if: github.ref == 'refs/heads/main'
environment: staging
steps:
- uses: actions/checkout@v4
- name: Deploy to Staging
uses: akhileshns/heroku-deploy@v3.13.15
with:
heroku_api_key: ${{ secrets.HEROKU_API_KEY }}
heroku_app_name: "myapp-staging"
heroku_email: ${{ secrets.HEROKU_EMAIL }}
- name: Run migrations
run: |
heroku run npm run db:migrate --app myapp-staging
env:
HEROKU_API_KEY: ${{ secrets.HEROKU_API_KEY }}
deploy-production:
needs: deploy-staging
runs-on: ubuntu-latest
if: github.ref == 'refs/heads/main'
environment: production
steps:
- name: Deploy to Production
uses: akhileshns/heroku-deploy@v3.13.15
with:
heroku_api_key: ${{ secrets.HEROKU_API_KEY }}
heroku_app_name: "myapp-production"
heroku_email: ${{ secrets.HEROKU_EMAIL }}
部署到 Review App #
yaml
# .github/workflows/review-app.yml
name: Review App
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
create-review-app:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Create Review App
run: |
# 使用 Heroku API 创建 Review App
curl -X POST \
https://api.heroku.com/review-apps \
-H "Accept: application/vnd.heroku+json; version=3" \
-H "Authorization: Bearer ${{ secrets.HEROKU_API_KEY }}" \
-d '{
"branch": "${{ github.head_ref }}",
"pipeline": "${{ secrets.HEROKU_PIPELINE_ID }}",
"source_blob": {
"url": "https://github.com/${{ github.repository }}/archive/${{ github.sha }}.tar.gz"
}
}'
部署通知 #
Slack 通知 #
yaml
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Deploy to Heroku
uses: akhileshns/heroku-deploy@v3.13.15
with:
heroku_api_key: ${{ secrets.HEROKU_API_KEY }}
heroku_app_name: "myapp"
heroku_email: ${{ secrets.HEROKU_EMAIL }}
- name: Notify Slack
if: always()
uses: 8398a7/action-slack@v3
with:
status: ${{ job.status }}
text: |
Deployment to Heroku: ${{ job.status }}
App: myapp
Commit: ${{ github.sha }}
webhook_url: ${{ secrets.SLACK_WEBHOOK }}
最佳实践 #
1. 分支保护 #
markdown
## GitHub 分支保护规则
main 分支：
- ☑ Require pull request reviews before merging
- ☑ Require status checks to pass before merging
- ☑ Require branches to be up to date before merging
- ☑ Include administrators
2. 环境变量管理 #
bash
# 使用 GitHub Secrets 存储敏感信息
# Settings → Secrets → Actions
# 必需的 Secrets：
# - HEROKU_API_KEY
# - HEROKU_EMAIL
# - DATABASE_URL (用于测试)
# - SECRET_KEY (用于测试)
3. 部署策略 #
text
┌─────────────────────────────────────────────────────┐
│ 推荐部署策略 │
├─────────────────────────────────────────────────────┤
│ │
│ Feature Branch │
│ │ │
│ ▼ │
│ ┌─────────┐ │
│ │ PR 创建 │ ──► Review App (自动) │
│ └────┬────┘ │
│ │ │
│ ▼ │
│ ┌─────────┐ │
│ │ PR 合并 │ ──► CI 测试 ──► Staging (自动) │
│ └────┬────┘ │
│ │ │
│ ▼ │
│ ┌─────────┐ │
│ │ 手动推广│ ──► Production │
│ └─────────┘ │
│ │
└─────────────────────────────────────────────────────┘
故障排查 #
自动部署失败 #
bash
# 检查 GitHub 连接
heroku apps:info | grep -i github
# 查看部署日志
heroku builds:output
# 重新连接 GitHub
# Dashboard → Settings → Disconnect → Reconnect
Review App 创建失败 #
bash
# 检查 app.json 格式
cat app.json | jq .
# 查看 Review App 日志
heroku logs --app review-app-name
# 常见问题
# 1. app.json 格式错误
# 2. Add-ons 配额不足
# 3. 环境变量缺失
下一步 #
GitHub 集成掌握后，接下来学习 Docker 部署 了解容器化部署方式！
最后更新：2026-03-28