deployment

部署技能

使用 GitHub Actions 和 app_action 工作流部署到 App Platform。

理念：PUSH 模式部署

本技能专注于 PUSH 模式——即将基础设施定义为代码，并由 GitHub Actions 驱动部署。

PULL MODE (Console-driven) — NOT covered by this skill
• Go to DigitalOcean Console → Create App → Point to GitHub
• App Platform auto-generates app spec
• Good for: Quick starts, manual one-offs

PUSH MODE (CLI/Actions-driven) — THIS SKILL
• Define app spec in repo (.do/app.yaml)
• Use GitHub Actions + app_action to deploy
• Good for: CI/CD, automation, GitOps, multi-environment

提示：对于复杂项目，可考虑使用 planner 技能分阶段处理。所有技能请参阅 根目录 SKILL.md。

---

快速决策

Using GitHub Actions? (RECOMMENDED)
├── YES → Use digitalocean/app_action/deploy@v2
│         • Handles spec updates AND code deployments
│         • Manages app creation if doesn't exist
│         • Supports PR previews
│
└── NO (Manual/Scripting)
    ├── Spec changed? → doctl apps update --spec
    └── Code only? → doctl apps create-deployment

命令	用途	使用时机
doctl apps create --spec	创建新应用	仅限首次部署
doctl apps update --spec	更新应用规范	配置变更时
doctl apps create-deployment	触发重新构建	仅代码变更时
app_action v2	同时处理规范和重新构建	推荐：一站式处理

---

快速开始：环境设置

# 1. Create DigitalOcean projects
doctl projects create --name "myapp-staging" --environment "Staging"
doctl projects create --name "myapp-production" --environment "Production"

# 2. Create GitHub environments
gh api --method PUT repos/:owner/:repo/environments/staging
gh api --method PUT repos/:owner/:repo/environments/production

# 3. Set secrets per environment (user fills in values)
gh secret set DIGITALOCEAN_ACCESS_TOKEN --env staging
gh secret set DIGITALOCEAN_ACCESS_TOKEN --env production
gh variable set DO_PROJECT_ID --env staging --body "PROJECT_ID"
gh variable set DO_PROJECT_ID --env production --body "PROJECT_ID"

完整设置指南：请参阅 initial-setup.md

---

快速开始：基本工作流

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - uses: digitalocean/app_action/deploy@v2
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
        with:
          token: ${{ secrets.DIGITALOCEAN_ACCESS_TOKEN }}
          project_id: ${{ vars.DO_PROJECT_ID }}

所有工作流模板：请参阅 workflow-templates.md

---

工作流选择

场景	工作流	参考资料
简单的单环境部署	最小可用	workflow-templates.md
预发布环境 + 生产环境	基于环境	workflow-templates.md
生产环境需要审批	受保护的环境	workflow-templates.md
合并前测试 PR	PR 预览	workflow-templates.md
多个环境，共用一个工作流	统一工作流	workflow-templates.md
需要回退	回滚	workflow-templates.md

---

快速开始：调试容器

对于包含多个集成的复杂应用，请先部署调试容器：

# Add to .do/app.yaml temporarily
workers:
  - name: debug
    image:
      registry_type: GHCR
      registry: ghcr.io
      repository: bikramkgupta/do-app-debug-container-python
      tag: latest
    instance_size_slug: apps-s-1vcpu-2gb
    envs:
      - key: DATABASE_URL
        scope: RUN_TIME
        value: ${db.DATABASE_URL}

# Connect and verify
doctl apps console $APP_ID debug
./diagnose.sh

完整指南：请参阅 debug-container-deployment.md

---

常用命令速查

任务	命令
验证规范	doctl apps spec validate .do/app.yaml
创建应用	doctl apps create --spec .do/app.yaml --project-id $PROJECT_ID
更新应用	doctl apps update $APP_ID --spec .do/app.yaml
重新部署	doctl apps create-deployment $APP_ID
查看日志	doctl apps logs $APP_ID --type run
设置密钥	gh secret set NAME --env staging
列出密钥	gh secret list --env staging

完整参考：请参阅 command-reference.md

---

参考文件

文件	内容
initial-setup.md	项目、环境、密钥和应用规范设置
workflow-templates.md	所有 GitHub Actions 工作流 YAML 模板
debug-container-deployment.md	用于基础设施验证的调试容器
command-reference.md	完整的 doctl 和 gh CLI 命令

---

快速故障排查

问题	症状	解决方法
未找到应用规范	Error: spec file not found	确保 .do/app.yaml 存在
令牌无效	401 Unauthorized	检查 DIGITALOCEAN_ACCESS_TOKEN 密钥
未找到项目	project_id is invalid	验证 DO_PROJECT_ID 变量
构建失败	BuildJobFailed	检查构建日志：doctl apps logs $APP_ID --type build
环境变量显示为字面值	值显示为 ${...}	检查可绑定变量名称是否匹配

---

固定默认配置

决策	默认值	理由
CI 平台	GitHub Actions	通过 app_action 实现最佳的 DO 集成
部署 Action	app_action/deploy@v2	一步完成 spec 配置和部署
密钥	每个环境使用 GitHub Secrets	安全，AI 永远看不到这些值
deploy_on_push	app spec 中设为 false	由 GitHub Actions 控制部署
App spec 位置	.do/app.yaml	符合惯例，也与 DO 按钮一致

---

与其他技能集成

• ← designer：创建部署时使用的 .do/app.yaml
• ← postgres：处理数据库设置，并将 DATABASE_URL 存储在 GitHub Secrets 中
• → troubleshooting：调试部署失败
• ← devcontainers：确保本地开发环境与生产环境一致

---

生产环境检查清单

• 已创建带有环境标签的 DO Projects
• 已创建 GitHub 环境（staging、production）
• 已为每个环境设置 DIGITALOCEAN_ACCESS_TOKEN 密钥
• 已为每个环境设置 DO_PROJECT_ID 变量
• .do/app.yaml 中已设置 deploy_on_push: false
• 已创建 .github/workflows/deploy.yml
• 已启用生产环境保护规则
• 已测试 staging 部署
• 已测试 production 部署

---

文档链接

• app_action GitHub 仓库
• App Platform 文档
• App Spec 参考
• GitHub 环境文档