Claude Code × AWS CodePipeline: stages, artifacts, aprovações e deploy seguro

“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";
import * as ecs from "aws-cdk-lib/aws-ecs";

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.

---

Comece pelo fluxo mínimo Source-Build-Test-Deploy

Para iniciantes, CodePipeline é uma esteira de release. Pipeline é o fluxo inteiro. Stage é uma seção como Source, Build, Test ou Deploy. Action é a tarefa executada dentro do stage. Artifact é o pacote entregue para a próxima action, como o código-fonte ou o diretório dist gerado pelo CodeBuild.

A página oficial CodePipeline concepts usa essa estrutura. Quando você pede para o Claude Code criar uma pipeline usando esses termos, a resposta fica muito mais fácil de revisar.

Um primeiro desenho prático é Source -> Build -> Test -> Approve -> Deploy. A documentação de criação da AWS diz que uma pipeline precisa de uma source stage e pelo menos outra stage de build ou deploy. Antes de produção, Manual approval é um controle simples e valioso.

aws codepipeline create-pipeline --cli-input-json file://pipeline.json
aws codepipeline get-pipeline-state --name webapp-main
aws codepipeline start-pipeline-execution --name webapp-main

Exemplos de deploy para S3/CloudFront e Lambda

Em site estático, CodeBuild cria dist e a action de S3 deploy extrai o artifact no bucket. A invalidation do CloudFront pode ficar em uma action posterior de CodeBuild ou Lambda invoke. Em Lambda, CodeBuild empacota a função e CloudFormation aplica o template empacotado.

version: 0.2

env:
  variables:
    AWS_REGION: ap-northeast-1
    S3_BUCKET: my-webapp-prod
    CLOUDFRONT_DISTRIBUTION_ID: E1234567890ABC

phases:
  install:
    runtime-versions:
      nodejs: 20
    commands:
      - npm ci
  pre_build:
    commands:
      - npm test
      - npm run lint
  build:
    commands:
      - npm run build
  post_build:
    commands:
      - aws s3 sync ./dist s3://$S3_BUCKET/ --delete --cache-control "public,max-age=300"
      - aws cloudfront create-invalidation --distribution-id $CLOUDFRONT_DISTRIBUTION_ID --paths "/*"

artifacts:
  base-directory: dist
  files:
    - "**/*"

Três exemplos cobrem muita coisa: site Astro ou Next.js em S3/CloudFront, API Lambda via CloudFormation e fluxo de equipe com staging automático e produção com aprovação. Separar os casos deixa artifacts, IAM e rollback mais claros.

Como diagnosticar falhas

Se Source falha, verifique ConnectionArn, branch e formato do artifact. Se Build falha, olhe logs do CodeBuild, buildspec, variáveis e IAM. Se Deploy falha, olhe nome do input artifact, permissões do bucket, role do CloudFormation, caminho do pacote Lambda e região.

aws codepipeline get-pipeline-state --name webapp-main
aws codepipeline list-action-executions --pipeline-name webapp-main --max-results 5
aws logs tail /aws/codebuild/webapp-build --since 30m --follow

Falhas comuns: produzir BuildOutput e configurar Deploy para ler SourceOutput; deixar a service role do CodeBuild sem S3, CloudFront, CloudFormation ou Lambda; guardar tokens como variáveis de ambiente em texto puro. O guia de actions separa Source, Build, Test, Deploy, Approval e Invoke, então revise permissões por action.

Prompt seguro para Claude Code

Adicione CI/CD com AWS CodePipeline + CodeBuild a este repositório.
Objetivo: Source no GitHub main, Build com npm ci/test/build, Test em action separada, Manual approval antes de produção, Deploy para S3 e invalidation do CloudFront.
Restrições: não usar AdministratorAccess, não usar IAM wildcard amplo, não fazer deploy de produção sem aprovação, não armazenar secrets em variáveis planas, não apagar pipelines ou buckets existentes.
Entregáveis: buildspec.yml, pipeline.json ou CDK stack, comandos de diagnóstico, guia operacional no README.
Verificação: explicar a configuração atual antes de mudar, mostrar diff, documentar aws codepipeline get-pipeline-state e logs do CodeBuild.

Esse prompt segue Create a pipeline, stages, and actions e Define CI/CD pipelines. Pedir que o Claude Code explique os conceitos oficiais usados melhora muito a revisão.

Nota de verificação estilo Masa e próximo passo

O hábito mais útil é fixar nomes de artifacts: SourceOutput, BuildOutput, TestOutput. Assim a falha aparece rápido. Para iniciantes, uma primeira versão em JSON ou console também ajuda antes de esconder tudo atrás de CDK.

Este assunto conecta com AWS IAM, AWS S3 e AWS Lambda. Para estudo individual, comece pelo PDF gratuito. Para equipe, planeje buildspec, IAM, aprovação, rollback e diagnóstico juntos; a página de treinamento e consultoria Claude Code é o próximo passo natural.

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