Claude Code × AWS CodePipeline: stages, artifacts, aprobaciones y despliegues seguros

“¿Para qué AWS CodePipeline si GitHub Actions funciona bien?”—una pregunta que escucho constantemente.

La respuesta está en la profunda integración con los recursos de AWS. Push a ECR, deploy a ECS, actualización de stacks de CloudFormation—cuando todo esto debe funcionar de forma nativa dentro de AWS, CodePipeline + CodeBuild es la combinación más fluida.

En mi trabajo gestiono pipelines que combinan múltiples servicios de AWS, y desde que Claude Code genera buildspec.yml, código CDK y políticas IAM de una sola vez simplemente describiendo los requisitos del pipeline, el tiempo para construir nuevos pipelines se redujo a la cuarta parte.

Estructura básica de CodePipeline / CodeBuild

CodePipeline (Orquestador)
    │
    ├─ Etapa Source:  Obtener código de GitHub / CodeCommit
    ├─ Etapa Build:   Build, pruebas, creación de imágenes Docker con CodeBuild
    ├─ Etapa Test:    Pruebas de integración, escaneos de seguridad (opcional)
    └─ Etapa Deploy:  Deploy a ECS / Elastic Beanstalk / S3

CodeBuild ejecuta los comandos escritos en buildspec.yml. Es equivalente a steps: en GitHub Actions.

Paso 1: Generación automática de buildspec.yml

claude -p "
Genera un buildspec.yml para CodeBuild con los siguientes requisitos.

[Contenido del Build]
- Entorno Node.js 20
- Instalación con npm ci
- Build TypeScript (npm run build)
- Ejecutar pruebas unitarias (npm test)
- Construir imagen Docker y hacer push a ECR
- Tag de imagen: CODEBUILD_RESOLVED_SOURCE_VERSION (Git SHA)
- También asignar tag latest simultáneamente

[Escaneo de Seguridad]
- Ejecutar escaneo Trivy después del push a ECR
- Fallar el build si hay vulnerabilidades HIGH/CRITICAL

[Artefactos]
- Generar imagedefinitions.json (para deploy en ECS)
"

buildspec.yml generado:

version: 0.2

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

phases:
  install:
    runtime-versions:
      nodejs: 20
    commands:
      - echo "Instalando dependencias..."
      - npm ci

  pre_build:
    commands:
      - echo "Ejecutando pruebas..."
      - npm test
      - echo "Iniciando sesión en 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 "Construyendo imagen Docker..."
      - docker build -t $IMAGE_URI -t $ECR_REGISTRY/$ECR_REPO_NAME:latest .

  post_build:
    commands:
      - echo "Haciendo push de la imagen a ECR..."
      - docker push $IMAGE_URI
      - docker push $ECR_REGISTRY/$ECR_REPO_NAME:latest
      - echo "Escaneando imagen en 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 "Creando 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

Paso 2: Construir todo el pipeline con CDK

claude -p "
Implementa el siguiente CodePipeline en CDK TypeScript en lib/pipeline-stack.ts.

[Configuración del Pipeline]
- Source: GitHub (rama main de owner/repo)
- Build: CodeBuild (usando el buildspec.yml anterior)
- Deploy: Deployment Blue/Green a servicio ECS

[Notificaciones]
- Notificar a Slack vía SNS en caso de fallo del pipeline
- También notificar a Slack cuando el deployment sea exitoso

[Almacén de Artefactos]
- Bucket S3 (cifrado y versionado 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 almacén de artefactos
    const artifactBucket = new s3.Bucket(this, "ArtifactBucket", {
      versioned: true,
      encryption: s3.BucketEncryption.S3_MANAGED,
      removalPolicy: cdk.RemovalPolicy.RETAIN,
    });

    // Definiciones de artefactos
    const sourceOutput = new codepipeline.Artifact("SourceOutput");
    const buildOutput = new codepipeline.Artifact("BuildOutput");

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

    // Otorgar permisos de acceso a 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,
            }),
          ],
        },
      ],
    });

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

Paso 3: Configurar reportes de resultados de pruebas

claude -p "
Quiero enviar resultados de pruebas a CodeBuild Reports en CodeBuild
para poder revisar reportes de calidad por cada PR.

- Framework de pruebas: Vitest
- Reporte de cobertura: Istanbul (formato lcov)
- Agregar sección reports al buildspec.yml
- También definir grupo de reportes con CDK
"

# Sección reports del buildspec.yml
reports:
  UnitTestResults:
    files:
      - "test-results/junit.xml"
    file-format: JUNITXML
  CodeCoverage:
    files:
      - "coverage/lcov.info"
    file-format: CLOVERXML

Paso 4: Diseño de pipeline multi-entorno

claude -p "
Diseña un pipeline de despliegue escalonado en CDK para 3 entornos: dev → staging → prod.

- dev: auto-deploy al hacer push a la rama main
- staging: deploy tras éxito en dev, con aprobación manual
- prod: deploy tras éxito en staging, con aprobación manual
- Notificar a Slack cuando se complete el deployment de cada entorno
"

// Agregar gates de aprobación manual para staging → prod
{
  stageName: "Approve_Staging",
  actions: [
    new codepipeline_actions.ManualApprovalAction({
      actionName: "Approve_Deploy_to_Staging",
      notificationTopic: alertTopic,
      additionalInformation: "¿Aprobar el deployment a Staging?",
    }),
  ],
},
{
  stageName: "Deploy_Staging",
  actions: [
    new codepipeline_actions.EcsDeployAction({
      actionName: "Deploy_to_Staging",
      service: stagingService,
      input: buildOutput,
    }),
  ],
},

4 errores comunes

1. Olvidar privileged: true en CodeBuild

Construir imágenes Docker requiere privileged: true. Sin esto aparece el error Cannot connect to the Docker daemon.

2. Permisos insuficientes en el token OAuth de GitHub

El source de GitHub requiere el scope repo. Usar solo public_repo no funciona para repositorios privados.

3. Región del bucket S3 de artefactos

El pipeline y el bucket S3 de artefactos deben estar en la misma región. Los pipelines cross-region requieren configuración adicional.

4. Formato de imagedefinitions.json para la acción de deploy ECS

El deployment en ECS requiere el formato exacto:

[{"name": "nombre-contenedor", "imageUri": "uri-imagen"}]

El nombre del contenedor debe coincidir exactamente con el nombre del contenedor en la definición de tarea.

Empieza por la forma mínima Source-Build-Test-Deploy

Para principiantes, CodePipeline se entiende mejor como una cinta transportadora de releases. El pipeline es el flujo completo. Un stage es una sección como Source, Build, Test o Deploy. Una action es la tarea concreta dentro del stage. Un artifact es el paquete que una action entrega a la siguiente, por ejemplo el código fuente o el directorio dist generado por CodeBuild.

La página oficial de CodePipeline concepts usa este mismo modelo: los pipelines tienen stages, los stages tienen actions y las actions producen o consumen artifacts. Si se lo explicas así a Claude Code, el resultado sale mucho más revisable.

El primer diseño práctico es Source -> Build -> Test -> Approve -> Deploy. La guía de creación de AWS indica que un pipeline necesita al menos un source stage y otro stage de build o deploy. Para producción, un Manual approval antes del deploy evita que una automatización incompleta llegue a usuarios reales.

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

Ejemplos de despliegue a S3/CloudFront y Lambda

Para un sitio estático, CodeBuild crea dist y una action de S3 deploy lo extrae en el bucket. La invalidación de CloudFront conviene separarla en una action posterior de CodeBuild o Lambda invoke. Para Lambda, CodeBuild empaqueta la función y CloudFormation despliega la plantilla empaquetada.

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:
    - "**/*"

Tres casos reales cubren mucho terreno: un sitio Astro o Next.js hacia S3/CloudFront, una API Lambda actualizada por CloudFormation y un flujo de equipo donde staging es automático pero production requiere aprobación. Separarlos ayuda a revisar artifacts, IAM y rollback.

Qué mirar cuando falla

Si falla Source, revisa ConnectionArn, branch y formato del artifact. Si falla Build, revisa logs de CodeBuild, buildspec, variables e IAM. Si falla Deploy, revisa el nombre del input artifact, permisos del bucket, rol de CloudFormation, ruta del paquete Lambda y región.

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

Errores frecuentes: producir BuildOutput y configurar Deploy para leer SourceOutput; dar al role de CodeBuild permisos insuficientes para S3, CloudFront, CloudFormation o Lambda; guardar tokens como variables de entorno en texto plano. La guía de actions separa Source, Build, Test, Deploy, Approval e Invoke, así que los permisos también deben revisarse por action.

Prompt seguro para Claude Code

Añade CI/CD con AWS CodePipeline + CodeBuild a este repositorio.
Objetivo: Source desde GitHub main, Build con npm ci/test/build, Test como action separada, Manual approval antes de producción, Deploy a S3 e invalidación de CloudFront.
Restricciones: no usar AdministratorAccess, no usar permisos IAM amplios con wildcard, no desplegar producción sin aprobación, no guardar secrets en variables planas, no borrar pipelines ni buckets existentes.
Entregables: buildspec.yml, pipeline.json o CDK stack, comandos de diagnóstico, guía operativa en README.
Verificación: explicar la configuración actual antes de cambiar, mostrar diff y documentar aws codepipeline get-pipeline-state y logs de CodeBuild.

Este prompt sigue Create a pipeline, stages, and actions y Define CI/CD pipelines. Pedirle a Claude Code que cite el concepto oficial usado reduce revisiones vagas.

Nota de verificación estilo Masa y siguiente paso

La mejora más práctica es fijar nombres de artifacts: SourceOutput, BuildOutput y TestOutput. Con eso, el punto de fallo aparece rápido. También conviene ver primero una versión JSON o console antes de abstraer todo con CDK.

Este tema se conecta con AWS IAM, AWS S3 y AWS Lambda. Para uso individual, empieza con el PDF gratuito. Para equipos, conviene diseñar buildspec, IAM, aprobación, rollback y diagnóstico juntos; ahí la formación y consultoría de Claude Code encaja mejor.

Resumen

Tarea	Contribución de Claude Code
Generación de buildspec.yml	Generado con build, pruebas, Docker y escaneo de seguridad incluidos
Pipeline CDK	Auto-genera todas las etapas de Source→Build→Deploy
Diseño multi-entorno	Diseña deployment escalonado con gates de aprobación manual
Reportes de pruebas	Automatiza la configuración de CodeBuild Reports

La configuración de CodePipeline puede parecer compleja, pero solo dile a Claude Code “quiero este tipo de pipeline” y generará tanto buildspec.yml como código CDK de una sola vez. Empieza probando primero con buildspec.yml.