AWS CodePipeline无法拉取Bitbucket仓库：未找到main分支

问题描述 #

配置了从Bitbucket仓库拉取代码的AWS CodePipeline，运行时Source阶段失败，错误信息：

错误代码：Action execution failed
错误信息：[Bitbucket] No Branch [main] found for FullRepositoryName [workspace/example-bitbucket-repo]

已确认Bitbucket用户Bitbucket-AWS-INT拥有仓库写入权限，且main是仓库唯一分支。以下是相关Terraform配置：

AWS IAM配置 #

data "aws_iam_policy_document" "example_assume_role_codebuild" {
  statement {
    effect = "Allow"
    principals {
      type        = "Service"
      identifiers = ["codebuild.amazonaws.com"]
    }
    actions = ["sts:AssumeRole"]
  }
}

resource "aws_iam_role" "example_codebuild_role" {
  name               = "example_codebuild_role"
  assume_role_policy = data.aws_iam_policy_document.example_assume_role_codebuild.json
  managed_policy_arns = [
    "arn:aws:iam::aws:policy/AdministratorAccess"
  ]
}

data "aws_iam_policy_document" "example_assume_role" {
  statement {
    effect = "Allow"
    principals {
      type        = "Service"
      identifiers = ["codepipeline.amazonaws.com"]
    }
    actions = ["sts:AssumeRole"]
  }
}

resource "aws_iam_role" "example_codepipeline_role" {
  name               = "example_codepipeline_role"
  assume_role_policy = data.aws_iam_policy_document.example_assume_role.json
}

data "aws_iam_policy_document" "example_codepipeline_policy" {
  statement {
    effect = "Allow"
    actions = [
      "s3:GetObject",
      "s3:GetObjectVersion",
      "s3:GetBucketVersioning",
      "s3:PutObjectAcl",
      "s3:PutObject",
    ]
    resources = [
      aws_s3_bucket.example-s3-bucket.arn,
      "${aws_s3_bucket.example-s3-bucket.arn}/*"
    ]
  }
  statement {
    effect    = "Allow"
    actions   = ["codestar-connections:UseConnection"]
    resources = [aws_codestarconnections_connection.example_bitbucket.arn]
  }
  statement {
    effect = "Allow"
    actions = [
      "codebuild:BatchGetBuilds",
      "codebuild:StartBuild",
    ]
    resources = ["*"]
  }
  statement {
    effect = "Allow"
    actions = [
      "sns:Publish",
    ]
    resources = ["*"]
  }
}

resource "aws_iam_role_policy" "example_codepipeline_policy" {
  name   = "example_codepipeline_policy"
  role   = aws_iam_role.example_codepipeline_role.id
  policy = data.aws_iam_policy_document.example_codepipeline_policy.json
}

CodeStar Connection配置 #

resource "aws_codestarconnections_connection" "example_bitbucket" {
  name          = "example_bitbucket"
  provider_type = "Bitbucket"
}

CodePipeline配置 #

resource "aws_codepipeline" "example_codepipeline" {
  name     = "example-codepipeline"
  role_arn = aws_iam_role.example_codepipeline_role.arn
  artifact_store {
    location = aws_s3_bucket.example-s3-bucket.bucket
    type     = "S3"
  }
  stage {
    name = "Source"
    action {
      name             = "Source"
      category         = "Source"
      owner            = "AWS"
      provider         = "CodeStarSourceConnection"
      version          = "1"
      output_artifacts = ["source_output"]
      configuration = {
        ConnectionArn    = aws_codestarconnections_connection.example_bitbucket.arn
        FullRepositoryId = "workspace/example-bitbucket-repo"
        BranchName       = "main"
        DetectChanges    = "false"
      }
    }
  }
  stage {
    name = "Build"
    action {
      name             = "Execute"
      category         = "Build"
      owner            = "AWS"
      provider         = "CodeBuild"
      input_artifacts  = ["source_output"]
      output_artifacts = ["build_output"]
      version          = "1"
      run_order        = "1"
      configuration = {
        ProjectName = "example-codebuild"
      }
    }
  }
}

原因及解决方案 #

1. CodeStar Connection未完成Bitbucket授权 #

通过Terraform创建aws_codestarconnections_connection后，该连接默认处于PENDING状态，必须手动在AWS控制台完成Bitbucket OAuth授权才能激活。

• 解决步骤：
  1. 登录AWS控制台，进入CodeStar Connections服务
  2. 找到名为example_bitbucket的连接，点击Connect to Bitbucket
  3. 按照提示完成Bitbucket账号授权，确保连接状态变为Available

2. FullRepositoryId格式错误 #

Bitbucket的FullRepositoryId要求使用工作区ID/仓库slug，而非工作区显示名称或仓库全称：

• 工作区ID：在Bitbucket工作区设置的Workspace ID字段（通常是小写无空格的标识符，和显示名称可能不同）
• 仓库slug：仓库的短名称（Bitbucket仓库URL最后一段的字符串，小写无空格）
• 解决步骤：
  1. 打开Bitbucket目标仓库，进入仓库设置查看正确的工作区ID和仓库slug
  2. 修改Terraform中CodePipeline的FullRepositoryId为正确格式，例如my-workspace-id/my-repo-slug

3. 分支名称大小写不匹配 #

Bitbucket分支名称区分大小写，需确保配置中的BranchName与仓库实际分支名完全一致（例如不要把main写成Main）。

• 解决步骤：
  1. 在Bitbucket仓库的分支页面确认目标分支的精确名称
  2. 调整Terraform配置中BranchName的值，确保大小写完全匹配

4. 授权用户无仓库访问权限 #

需确认CodeStar Connection授权使用的Bitbucket账号确实是Bitbucket-AWS-INT，且该账号能正常访问目标仓库的main分支：

• 解决步骤：
  1. 检查CodeStar Connection授权的Bitbucket账号是否为Bitbucket-AWS-INT
  2. 用该账号登录Bitbucket，确认能看到目标仓库的main分支

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