Claude Code × AWS CodePipeline/CodeBuild Guia Completo | Construção Automática de Pipeline CI/CD

“GitHub Actions já basta, por que usar AWS CodePipeline?”—uma pergunta que ouço com frequência.

A resposta está na profunda integração com os recursos da AWS. Push para ECR, deploy no ECS, atualização de stacks do CloudFormation—quando tudo isso precisa funcionar de forma nativa dentro da AWS, CodePipeline + CodeBuild é a combinação mais fluida.

No meu trabalho, gerencio pipelines que combinam vários serviços da AWS, e desde que o Claude Code passou a gerar buildspec.yml, código CDK e políticas IAM de uma vez só ao descrever os requisitos do pipeline, o tempo para construir novos pipelines caiu para um quarto.

---

Estrutura Básica do CodePipeline / CodeBuild

CodePipeline (Orquestrador)
    │
    ├─ Stage Source:  Buscar código do GitHub / CodeCommit
    ├─ Stage Build:   Build, testes, criação de imagens Docker com CodeBuild
    ├─ Stage Test:    Testes de integração, varreduras de segurança (opcional)
    └─ Stage Deploy:  Deploy no ECS / Elastic Beanstalk / S3

O CodeBuild executa os comandos escritos no buildspec.yml. Pense nele como o equivalente ao steps: do GitHub Actions.

---

Passo 1: Gerar buildspec.yml Automaticamente

claude -p "
Gere um buildspec.yml para CodeBuild com os seguintes requisitos.

[Conteúdo do Build]
- Ambiente Node.js 20
- Instalação com npm ci
- Build TypeScript (npm run build)
- Executar testes unitários (npm test)
- Construir imagem Docker e fazer push para ECR
- Tag da imagem: CODEBUILD_RESOLVED_SOURCE_VERSION (Git SHA)
- Também atribuir tag latest simultaneamente

[Varredura de Segurança]
- Executar varredura Trivy após push da imagem ECR
- Falhar o build se vulnerabilidades HIGH/CRITICAL forem encontradas

[Artefatos]
- Gerar imagedefinitions.json (para deploy no ECS)
"

buildspec.yml gerado:

version: 0.2

env:
  variables:
    AWS_DEFAULT_REGION: sa-east-1
    ECR_REPO_NAME: myapp
  parameter-store:
    ECR_REGISTRY: /myapp/ecr-registry

phases:
  install:
    runtime-versions:
      nodejs: 20
    commands:
      - echo "Instalando dependências..."
      - npm ci

  pre_build:
    commands:
      - echo "Executando testes..."
      - npm test
      - echo "Fazendo login no Amazon ECR..."
      - aws ecr get-login-password | docker login --username AWS --password-stdin $ECR_REGISTRY
      - IMAGE_TAG=$CODEBUILD_RESOLVED_SOURCE_VERSION
      - IMAGE_URI=$ECR_REGISTRY/$ECR_REPO_NAME:$IMAGE_TAG

  build:
    commands:
      - echo "Compilando TypeScript..."
      - npm run build
      - echo "Construindo imagem Docker..."
      - docker build -t $IMAGE_URI -t $ECR_REGISTRY/$ECR_REPO_NAME:latest .

  post_build:
    commands:
      - echo "Fazendo push da imagem para ECR..."
      - docker push $IMAGE_URI
      - docker push $ECR_REGISTRY/$ECR_REPO_NAME:latest
      - echo "Varrendo imagem em busca de vulnerabilidades..."
      - |
        docker run --rm \
          -v /var/run/docker.sock:/var/run/docker.sock \
          aquasec/trivy:latest image \
          --exit-code 1 \
          --severity HIGH,CRITICAL \
          $IMAGE_URI
      - echo "Criando imagedefinitions.json..."
      - printf '[{"name":"app","imageUri":"%s"}]' $IMAGE_URI > imagedefinitions.json

artifacts:
  files:
    - imagedefinitions.json

reports:
  test-reports:
    files:
      - "coverage/junit.xml"
    file-format: JUNITXML

---

Passo 2: Construir Todo o Pipeline com CDK

claude -p "
Implemente o seguinte CodePipeline em CDK TypeScript em lib/pipeline-stack.ts.

[Configuração do Pipeline]
- Source: GitHub (branch main de owner/repo)
- Build: CodeBuild (usando o buildspec.yml acima)
- Deploy: Deployment Blue/Green para serviço ECS

[Notificações]
- Notificar Slack via SNS em caso de falha do pipeline
- Também notificar Slack em caso de deploy bem-sucedido

[Armazenamento de Artefatos]
- Bucket S3 (criptografia e versionamento habilitados)
"

// lib/pipeline-stack.ts
import * as cdk from "aws-cdk-lib";
import * as codepipeline from "aws-cdk-lib/aws-codepipeline";
import * as codepipeline_actions from "aws-cdk-lib/aws-codepipeline-actions";
import * as codebuild from "aws-cdk-lib/aws-codebuild";
import * as s3 from "aws-cdk-lib/aws-s3";
import * as iam from "aws-cdk-lib/aws-iam";
import * as sns from "aws-cdk-lib/aws-sns";

export class PipelineStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Bucket S3 para armazenamento de artefatos
    const artifactBucket = new s3.Bucket(this, "ArtifactBucket", {
      versioned: true,
      encryption: s3.BucketEncryption.S3_MANAGED,
      removalPolicy: cdk.RemovalPolicy.RETAIN,
    });

    // Definições de artefatos
    const sourceOutput = new codepipeline.Artifact("SourceOutput");
    const buildOutput = new codepipeline.Artifact("BuildOutput");

    // Projeto CodeBuild
    const buildProject = new codebuild.PipelineProject(this, "BuildProject", {
      buildSpec: codebuild.BuildSpec.fromSourceFilename("buildspec.yml"),
      environment: {
        buildImage: codebuild.LinuxBuildImage.STANDARD_7_0,
        privileged: true,  // Necessário para builds Docker
      },
      environmentVariables: {
        AWS_ACCOUNT_ID: { value: this.account },
      },
    });

    // Conceder permissões de acesso ao ECR
    buildProject.addToRolePolicy(new iam.PolicyStatement({
      actions: [
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:PutImage",
        "ecr:InitiateLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload",
      ],
      resources: ["*"],
    }));

    // Pipeline
    const pipeline = new codepipeline.Pipeline(this, "Pipeline", {
      pipelineName: "myapp-pipeline",
      artifactBucket,
      stages: [
        {
          stageName: "Source",
          actions: [
            new codepipeline_actions.GitHubSourceAction({
              actionName: "GitHub_Source",
              owner: "your-org",
              repo: "your-repo",
              branch: "main",
              oauthToken: cdk.SecretValue.secretsManager("github-token"),
              output: sourceOutput,
            }),
          ],
        },
        {
          stageName: "Build",
          actions: [
            new codepipeline_actions.CodeBuildAction({
              actionName: "Build_and_Test",
              project: buildProject,
              input: sourceOutput,
              outputs: [buildOutput],
            }),
          ],
        },
        {
          stageName: "Deploy",
          actions: [
            new codepipeline_actions.EcsDeployAction({
              actionName: "Deploy_to_ECS",
              service: ecs.FargateService.fromFargateServiceAttributes(
                this, "EcsService", {
                  cluster: ecs.Cluster.fromClusterArn(
                    this, "Cluster",
                    `arn:aws:ecs:${this.region}:${this.account}:cluster/myapp-cluster`
                  ),
                  serviceName: "myapp-service",
                }
              ),
              input: buildOutput,
            }),
          ],
        },
      ],
    });

    // Notificações de falha
    const alertTopic = new sns.Topic(this, "AlertTopic");
    pipeline.notifyOnAnyStageStateChange("PipelineNotification", alertTopic, {
      events: [
        codepipeline.PipelineNotificationEvents.PIPELINE_EXECUTION_FAILED,
        codepipeline.PipelineNotificationEvents.PIPELINE_EXECUTION_SUCCEEDED,
      ],
    });
  }
}

---

Passo 3: Configurar Relatórios de Resultados de Testes

claude -p "
Quero enviar resultados de testes para o CodeBuild Reports no CodeBuild
para poder verificar relatórios de qualidade por PR.

- Framework de teste: Vitest
- Relatório de cobertura: Istanbul (formato lcov)
- Adicionar seção reports ao buildspec.yml
- Também definir grupo de relatórios com CDK
"

# Seção reports do buildspec.yml
reports:
  UnitTestResults:
    files:
      - "test-results/junit.xml"
    file-format: JUNITXML
  CodeCoverage:
    files:
      - "coverage/lcov.info"
    file-format: CLOVERXML

---

Passo 4: Design de Pipeline Multi-Ambiente

claude -p "
Projete um pipeline de deployment em etapas CDK para 3 ambientes: dev → staging → prod.

- dev: auto-deploy ao fazer push na branch main
- staging: deploy após sucesso no dev, com aprovação manual
- prod: deploy após sucesso no staging, com aprovação manual
- Notificar Slack quando o deployment de cada ambiente for concluído
"

// Adicionar gates de aprovação manual para staging → prod
{
  stageName: "Approve_Staging",
  actions: [
    new codepipeline_actions.ManualApprovalAction({
      actionName: "Approve_Deploy_to_Staging",
      notificationTopic: alertTopic,
      additionalInformation: "Aprovar o deployment para Staging?",
    }),
  ],
},
{
  stageName: "Deploy_Staging",
  actions: [
    new codepipeline_actions.EcsDeployAction({
      actionName: "Deploy_to_Staging",
      service: stagingService,
      input: buildOutput,
    }),
  ],
},

---

4 Armadilhas Comuns

1. Esquecer privileged: true no CodeBuild

Construir imagens Docker requer privileged: true. Sem isso, aparece o erro Cannot connect to the Docker daemon.

2. Permissões Insuficientes do Token OAuth do GitHub

O source do GitHub requer o scope repo. Usar apenas public_repo não funciona para repositórios privados.

3. Região do Bucket S3 de Artefatos

O pipeline e o bucket S3 de artefatos devem estar na mesma região. Pipelines cross-region requerem configuração adicional.

4. Formato de imagedefinitions.json para a Ação de Deploy ECS

O deployment no ECS requer o formato exato:

[{"name": "nome-container", "imageUri": "uri-imagem"}]

O nome do container deve corresponder exatamente ao nome do container na definição de tarefa.

---

Resumo

Tarefa	Contribuição do Claude Code
Geração de buildspec.yml	Gerado com build, testes, Docker e varredura de segurança incluídos
Pipeline CDK	Auto-gera todos os stages de Source→Build→Deploy
Design multi-ambiente	Projeta deployment em etapas com gates de aprovação manual
Relatórios de testes	Automatiza a configuração do CodeBuild Reports

A configuração do CodePipeline pode parecer complexa, mas basta dizer ao Claude Code “quero este tipo de pipeline” e ele produzirá tanto o buildspec.yml quanto o código CDK de uma vez. Comece experimentando com o buildspec.yml primeiro.

Artigos Relacionados

• Claude Code × AWS ECS/Fargate Guia Completo
• Claude Code × AWS CloudFormation/CDK Guia Completo
• Claude Code × AWS IAM Guia Completo

Referências

• Documentação Oficial AWS CodePipeline
• Referência buildspec AWS CodeBuild
• Módulo CDK CodePipeline