使用atlassian/heroku-deploy从Bitbucket Pipelines部署到Heroku时401授权失败

问题场景 #

使用Atlassian官方的heroku-deploy管道从Bitbucket Pipelines部署NestJS后端应用到Heroku时，管道抛出401未授权错误：

✖ Failed to create sources. Expected HTTP Status 201, got 401.
Error message: {"id":"unauthorized","message":"Invalid credentials provided."}

已通过Postman验证Heroku API密钥有效，但管道内部署始终失败。

现有环境配置 #

仓库目录结构 #

project
├── backend
├── frontend
└── .bitbucket-pipelines.yml

Bitbucket Pipelines配置 #

image: node:18

pipelines:
  branches:
    dev:
      - step:
          name: Build App - (Dev)
          script:
            - cd backend
            - npm install
            - npm run build

      - step:
            name: Create Artifact (Dev)
            script:
              - cd backend
              - git archive --format=tar.gz dev -o application.tar.gz
            artifacts:
              - backend/application.tar.gz
      - step:
          name: Deploy to Heroku (Dev)
          deployment: Staging
          script:
            - pipe: atlassian/heroku-deploy:2.4.1
              variables:
                HEROKU_API_KEY: $HEROKU_API_KEY
                HEROKU_APP_NAME: $HEROKU_APP_NAME
                ZIP_FILE: backend/application.tar.gz
                WAIT: "true"
          caches:
            - node

后端package.json启动脚本 #

"scripts": {
    "prebuild": "rimraf dist",
    "build": "nest build",
    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
    "start": "node dist/main"
}

已验证的前置条件 #

• Bitbucket仓库变量HEROKU_APP_NAME设置为正确的应用名devcrm
• HEROKU_API_KEY从Heroku控制台账户页复制，无多余空格/引号，且通过Postman请求GET https://api.heroku.com/apps能正常获取应用列表
• 已尝试重新生成API密钥、更换管道版本、确认Heroku账户对应用的所有权

针对性解决方案 #

1. 确认Bitbucket变量的作用域与类型 #

• 确保HEROKU_API_KEY是仓库级安全变量：进入Bitbucket仓库Settings > Repository variables，检查变量类型为Secured，且未被设置为"Restricted to specific pipelines"（若设置限制需确保当前部署分支/环境在允许范围内）
• 若使用项目级变量，需确认仓库已开启Inherit variables from project选项

2. 验证管道中变量的注入状态 #

在部署步骤的script中添加变量检查（安全变量无法直接打印，可通过长度验证）：

- step:
    name: Deploy to Heroku (Dev)
    deployment: Staging
    script:
      - echo "HEROKU_API_KEY 长度: ${#HEROKU_API_KEY}" # 确认变量非空
      - echo "HEROKU_APP_NAME: $HEROKU_APP_NAME" # 验证应用名正确
      - pipe: atlassian/heroku-deploy:2.4.1
        variables:
          HEROKU_API_KEY: $HEROKU_API_KEY
          HEROKU_APP_NAME: $HEROKU_APP_NAME
          ZIP_FILE: backend/application.tar.gz
          WAIT: "true"
    caches:
      - node

若HEROKU_API_KEY长度为0，说明变量未被正确注入，需检查变量设置的作用域。

3. 检查Heroku账户的应用权限 #

即使API密钥能获取应用列表，仍需确认：

• 该Heroku账户是目标应用devcrm的所有者或已被添加为协作者（进入Heroku应用Settings > Members查看）
• 协作者账户需拥有Deploy权限（默认协作者具备该权限，若被修改需重新开启）

4. 绕过管道直接用Heroku CLI验证部署 #

替换管道部署步骤，用Heroku CLI直接部署，排除管道自身问题：

- step:
    name: Deploy to Heroku (Dev)
    deployment: Staging
    script:
      - cd backend
      - npm install -g heroku
      - echo "$HEROKU_API_KEY" | heroku auth:login -i
      - heroku git:remote -a $HEROKU_APP_NAME
      # 注意：若dist目录未被git追踪，需先添加到临时提交
      - git add dist/
      - git commit -m "Deploy dist files" --allow-empty
      - git push heroku dev:main --force

若此方式部署成功，说明是atlassian/heroku-deploy管道的适配问题，可尝试提交issue或继续使用CLI部署方式。

5. 修正Artifact生成逻辑（附带优化） #

当前git archive命令仅打包仓库已追踪文件，而Build步骤生成的dist目录若未被git追踪（通常会加入.gitignore），会导致部署包缺少运行文件。可修改Artifact生成步骤：

- step:
    name: Create Artifact (Dev)
    script:
      - cd backend
      # 打包当前目录所有文件（包括dist），而非git追踪文件
      - tar -czf application.tar.gz .
    artifacts:
      - backend/application.tar.gz

内容的提问来源于stack exchange，提问作者Code Guru