Claude Code × AWS CodePipeline : stages, artifacts, approbations et déploiements sûrs

« GitHub Actions suffit bien, pourquoi se compliquer avec AWS CodePipeline ? »—une question que j’entends souvent.

La réponse réside dans la profonde intégration avec les ressources AWS. Push vers ECR, déploiement sur ECS, mise à jour des stacks CloudFormation—lorsque tout cela doit fonctionner nativement au sein d’AWS, CodePipeline + CodeBuild est la combinaison la plus fluide.

Dans mon travail, je gère des pipelines combinant plusieurs services AWS, et depuis que Claude Code génère buildspec.yml, le code CDK et les politiques IAM en une seule fois simplement en décrivant les exigences du pipeline, le temps de construction de nouveaux pipelines a été réduit au quart.

---

Structure de base de CodePipeline / CodeBuild

CodePipeline (Orchestrateur)
    │
    ├─ Étape Source:  Récupérer le code depuis GitHub / CodeCommit
    ├─ Étape Build:   Build, tests, création d'images Docker avec CodeBuild
    ├─ Étape Test:    Tests d'intégration, scans de sécurité (optionnel)
    └─ Étape Deploy:  Déploiement vers ECS / Elastic Beanstalk / S3

CodeBuild exécute les commandes écrites dans buildspec.yml. C’est l’équivalent de steps: dans GitHub Actions.

---

Étape 1 : Génération automatique de buildspec.yml

claude -p "
Génère un buildspec.yml pour CodeBuild avec les exigences suivantes.

[Contenu du Build]
- Environnement Node.js 20
- Installation avec npm ci
- Build TypeScript (npm run build)
- Exécuter les tests unitaires (npm test)
- Construire l'image Docker et faire un push vers ECR
- Tag d'image : CODEBUILD_RESOLVED_SOURCE_VERSION (Git SHA)
- Attribuer également le tag latest simultanément

[Scan de Sécurité]
- Exécuter un scan Trivy après le push de l'image ECR
- Échec du build si des vulnérabilités HIGH/CRITICAL sont trouvées

[Artefacts]
- Générer imagedefinitions.json (pour le déploiement ECS)
"

buildspec.yml généré :

version: 0.2

env:
  variables:
    AWS_DEFAULT_REGION: eu-west-1
    ECR_REPO_NAME: myapp
  parameter-store:
    ECR_REGISTRY: /myapp/ecr-registry

phases:
  install:
    runtime-versions:
      nodejs: 20
    commands:
      - echo "Installation des dépendances..."
      - npm ci

  pre_build:
    commands:
      - echo "Exécution des tests..."
      - npm test
      - echo "Connexion à 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 "Compilation TypeScript..."
      - npm run build
      - echo "Construction de l'image Docker..."
      - docker build -t $IMAGE_URI -t $ECR_REGISTRY/$ECR_REPO_NAME:latest .

  post_build:
    commands:
      - echo "Push de l'image vers ECR..."
      - docker push $IMAGE_URI
      - docker push $ECR_REGISTRY/$ECR_REPO_NAME:latest
      - echo "Scan de l'image pour les vulnérabilités..."
      - |
        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 "Création de 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

---

Étape 2 : Construire le pipeline complet avec CDK

claude -p "
Implémente le CodePipeline suivant en CDK TypeScript dans lib/pipeline-stack.ts.

[Configuration du Pipeline]
- Source : GitHub (branche main de owner/repo)
- Build : CodeBuild (en utilisant le buildspec.yml ci-dessus)
- Deploy : Déploiement Blue/Green vers le service ECS

[Notifications]
- Notifier Slack via SNS en cas d'échec du pipeline
- Notifier également Slack en cas de déploiement réussi

[Stockage d'Artefacts]
- Bucket S3 (chiffrement et versionnage activés)
"

// 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 pour le stockage d'artefacts
    const artifactBucket = new s3.Bucket(this, "ArtifactBucket", {
      versioned: true,
      encryption: s3.BucketEncryption.S3_MANAGED,
      removalPolicy: cdk.RemovalPolicy.RETAIN,
    });

    // Définitions des artefacts
    const sourceOutput = new codepipeline.Artifact("SourceOutput");
    const buildOutput = new codepipeline.Artifact("BuildOutput");

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

    // Accorder les droits d'accès à 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,
            }),
          ],
        },
      ],
    });

    // Notifications d'échec
    const alertTopic = new sns.Topic(this, "AlertTopic");
    pipeline.notifyOnAnyStageStateChange("PipelineNotification", alertTopic, {
      events: [
        codepipeline.PipelineNotificationEvents.PIPELINE_EXECUTION_FAILED,
        codepipeline.PipelineNotificationEvents.PIPELINE_EXECUTION_SUCCEEDED,
      ],
    });
  }
}

---

Étape 3 : Configurer les rapports de résultats de tests

claude -p "
Je veux envoyer les résultats de tests à CodeBuild Reports dans CodeBuild
pour pouvoir consulter les rapports de qualité par PR.

- Framework de test : Vitest
- Rapport de couverture : Istanbul (format lcov)
- Ajouter la section reports à buildspec.yml
- Définir également le groupe de rapports avec CDK
"

# Section reports du buildspec.yml
reports:
  UnitTestResults:
    files:
      - "test-results/junit.xml"
    file-format: JUNITXML
  CodeCoverage:
    files:
      - "coverage/lcov.info"
    file-format: CLOVERXML

---

Étape 4 : Conception de pipeline multi-environnement

claude -p "
Conçois un pipeline de déploiement progressif CDK pour 3 environnements : dev → staging → prod.

- dev : déploiement automatique au push sur la branche main
- staging : déploiement après succès de dev, avec approbation manuelle
- prod : déploiement après succès de staging, avec approbation manuelle
- Notifier Slack quand le déploiement de chaque environnement est terminé
"

// Ajouter les gates d'approbation manuelle pour staging → prod
{
  stageName: "Approve_Staging",
  actions: [
    new codepipeline_actions.ManualApprovalAction({
      actionName: "Approve_Deploy_to_Staging",
      notificationTopic: alertTopic,
      additionalInformation: "Approuver le déploiement vers Staging ?",
    }),
  ],
},
{
  stageName: "Deploy_Staging",
  actions: [
    new codepipeline_actions.EcsDeployAction({
      actionName: "Deploy_to_Staging",
      service: stagingService,
      input: buildOutput,
    }),
  ],
},

---

4 pièges courants

1. Oublier privileged: true dans CodeBuild

Construire des images Docker nécessite privileged: true. Sans cela, l’erreur Cannot connect to the Docker daemon apparaît.

2. Permissions insuffisantes du token OAuth GitHub

La source GitHub nécessite le scope repo. Utiliser uniquement public_repo ne fonctionne pas pour les dépôts privés.

3. Région du bucket S3 d’artefacts

Le pipeline et le bucket S3 d’artefacts doivent être dans la même région. Les pipelines cross-region nécessitent une configuration supplémentaire.

4. Format de imagedefinitions.json pour l’action de déploiement ECS

Le déploiement ECS nécessite le format exact :

[{"name": "nom-conteneur", "imageUri": "uri-image"}]

Le nom du conteneur doit correspondre exactement au nom du conteneur dans la définition de tâche.

---

Commencer par la structure minimale Source-Build-Test-Deploy

Pour un débutant, CodePipeline ressemble à une chaîne de release. Le pipeline est le flux complet. Un stage est une étape nommée, comme Source, Build, Test ou Deploy. Une action est la tâche exécutée dans ce stage. Un artifact est le paquet transmis à l’action suivante, par exemple le code source ou le dossier dist généré par CodeBuild.

La page officielle CodePipeline concepts décrit cette structure : un pipeline contient des stages, les stages contiennent des actions, et les actions utilisent ou produisent des artifacts. Donner ces mots à Claude Code rend la sortie beaucoup plus contrôlable.

Un premier pipeline réaliste est Source -> Build -> Test -> Approve -> Deploy. La documentation de création AWS précise qu’un pipeline doit avoir au moins une source stage et une autre stage de build ou deploy. Avant la production, une Manual approval donne un point de contrôle humain.

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

Exemples de déploiement S3/CloudFront et Lambda

Pour un site statique, CodeBuild construit dist puis une action S3 deploy l’extrait dans le bucket. L’invalidation CloudFront peut être une action CodeBuild ou Lambda invoke séparée. Pour Lambda, CodeBuild produit le paquet et CloudFormation déploie le template packagé.

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

Trois cas d’usage suffisent souvent : un site Astro ou Next.js vers S3/CloudFront, une API Lambda déployée par CloudFormation, et un flux d’équipe où staging est automatique mais production demande une approbation. Les séparer rend les artifacts et IAM plus lisibles.

Que vérifier en cas d’échec

Si Source échoue, regarder ConnectionArn, branche et format d’artifact. Si Build échoue, regarder les logs CodeBuild, buildspec, variables et IAM. Si Deploy échoue, regarder le nom de l’input artifact, les permissions S3, le rôle CloudFormation, le chemin du package Lambda et la région.

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

Les erreurs classiques sont : produire BuildOutput mais lire SourceOutput au deploy, donner trop peu de permissions au role CodeBuild, ou mettre des secrets dans des variables en clair. Le guide actions distingue Source, Build, Test, Deploy, Approval et Invoke ; les permissions doivent donc être relues action par action.

Prompt sûr pour Claude Code

Ajoute un CI/CD AWS CodePipeline + CodeBuild à ce dépôt.
Objectif : Source depuis GitHub main, Build avec npm ci/test/build, Test dans une action séparée, Manual approval avant production, Deploy vers S3 puis invalidation CloudFront.
Contraintes : pas d'AdministratorAccess, pas de permissions IAM wildcard larges, pas de production sans approbation, pas de secrets en variables en clair, ne pas supprimer de pipeline ou bucket existant.
Livrables : buildspec.yml, pipeline.json ou stack CDK, commandes de diagnostic, procédure README.
Vérification : expliquer l'état actuel, montrer le diff, documenter aws codepipeline get-pipeline-state et les logs CodeBuild.

Ce prompt suit Create a pipeline, stages, and actions et Define CI/CD pipelines. Demander à Claude Code de relier sa sortie aux concepts officiels aide énormément la revue.

Note de vérification façon Masa et suite

Le geste le plus rentable est de fixer les noms d’artifacts : SourceOutput, BuildOutput, TestOutput. On voit alors vite où l’exécution casse. Il est aussi plus simple de comprendre une première version JSON ou console avant de tout masquer derrière CDK.

Ce sujet touche naturellement AWS IAM, AWS S3 et AWS Lambda. Pour apprendre seul, le PDF gratuit suffit. Pour une équipe, il faut concevoir ensemble buildspec, IAM, approbation, rollback et diagnostic ; la page formation et consultation Claude Code est faite pour cela.

Résumé

Tâche	Contribution de Claude Code
Génération de buildspec.yml	Généré avec build, tests, Docker et scan de sécurité inclus
Pipeline CDK	Auto-génère toutes les étapes de Source→Build→Deploy
Conception multi-environnement	Conçoit le déploiement progressif avec gates d’approbation manuelle
Rapports de tests	Automatise la configuration de CodeBuild Reports

La configuration de CodePipeline peut sembler complexe, mais dites simplement à Claude Code « je veux ce type de pipeline » et il produira buildspec.yml et le code CDK en une seule fois. Commencez par essayer avec buildspec.yml.

Articles connexes

• Claude Code × AWS ECS/Fargate Guide Complet
• Claude Code × AWS CloudFormation/CDK Guide Complet
• Claude Code × AWS IAM Guide Complet

Références

• Documentation Officielle AWS CodePipeline
• Référence buildspec AWS CodeBuild
• Module CDK CodePipeline