Claude Code × AWS CodePipeline/CodeBuild Guía Completa | Construcción automática de pipelines CI/CD

“¿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";

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.

---

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.

Artículos relacionados

• Claude Code × AWS ECS/Fargate Guía Completa
• Claude Code × AWS CloudFormation/CDK Guía Completa
• Claude Code × AWS IAM Guía Completa

Referencias

• Documentación Oficial de AWS CodePipeline
• Referencia buildspec de AWS CodeBuild
• Módulo CDK CodePipeline