Claude Code × AWS CodePipeline: Stages, Artifacts, Freigaben und sichere Deployments

„GitHub Actions reicht doch, warum noch AWS CodePipeline?”—eine Frage, die ich ständig höre.

Die Antwort liegt in der tiefen Integration mit AWS-Ressourcen. Push zu ECR, Deploy zu ECS, CloudFormation-Stacks aktualisieren—wenn all das nativ innerhalb von AWS ablaufen soll, ist CodePipeline + CodeBuild die nahtloseste Kombination.

Ich verwalte beruflich Pipelines, die mehrere AWS-Services kombinieren, und seitdem Claude Code aus einer einfachen Beschreibung meiner Anforderungen buildspec.yml, CDK-Code und IAM-Policies auf einmal generiert, hat sich die Zeit für den Aufbau neuer Pipelines auf ein Viertel reduziert.

---

Grundstruktur von CodePipeline / CodeBuild

CodePipeline (Orchestrator)
    │
    ├─ Source-Stage:  Code von GitHub / CodeCommit holen
    ├─ Build-Stage:   Build, Tests, Docker-Images mit CodeBuild
    ├─ Test-Stage:    Integrationstests, Security-Scans (optional)
    └─ Deploy-Stage:  Deploy zu ECS / Elastic Beanstalk / S3

CodeBuild führt die in buildspec.yml geschriebenen Befehle aus. Am besten stellt man es sich als Äquivalent zu steps: in GitHub Actions vor.

---

Schritt 1: buildspec.yml automatisch generieren

claude -p "
Generiere eine buildspec.yml für CodeBuild mit folgenden Anforderungen.

[Build-Inhalt]
- Node.js 20 Umgebung
- Installation mit npm ci
- TypeScript-Build (npm run build)
- Unit-Tests ausführen (npm test)
- Docker-Image bauen und zu ECR pushen
- Image-Tag: CODEBUILD_RESOLVED_SOURCE_VERSION (Git SHA)
- Gleichzeitig auch latest-Tag vergeben

[Security-Scan]
- Trivy-Scan nach ECR-Image-Push ausführen
- Build schlägt fehl bei HIGH/CRITICAL-Schwachstellen

[Artefakte]
- imagedefinitions.json ausgeben (für ECS-Deploy)
"

Generierte buildspec.yml:

version: 0.2

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

phases:
  install:
    runtime-versions:
      nodejs: 20
    commands:
      - echo "Abhängigkeiten installieren..."
      - npm ci

  pre_build:
    commands:
      - echo "Tests ausführen..."
      - npm test
      - echo "Bei Amazon ECR anmelden..."
      - 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 "TypeScript bauen..."
      - npm run build
      - echo "Docker-Image bauen..."
      - docker build -t $IMAGE_URI -t $ECR_REGISTRY/$ECR_REPO_NAME:latest .

  post_build:
    commands:
      - echo "Image zu ECR pushen..."
      - docker push $IMAGE_URI
      - docker push $ECR_REGISTRY/$ECR_REPO_NAME:latest
      - echo "Image auf Schwachstellen scannen..."
      - |
        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 "imagedefinitions.json erstellen..."
      - printf '[{"name":"app","imageUri":"%s"}]' $IMAGE_URI > imagedefinitions.json

artifacts:
  files:
    - imagedefinitions.json

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

---

Schritt 2: Gesamte Pipeline mit CDK aufbauen

claude -p "
Implementiere folgende CodePipeline in CDK TypeScript in lib/pipeline-stack.ts.

[Pipeline-Konfiguration]
- Source: GitHub (main-Branch von owner/repo)
- Build: CodeBuild (mit obiger buildspec.yml)
- Deploy: Blue/Green-Deployment zu ECS-Service

[Benachrichtigungen]
- Bei Pipeline-Fehler per SNS an Slack benachrichtigen
- Auch bei erfolgreichem Deployment Slack benachrichtigen

[Artefakt-Store]
- S3-Bucket (Verschlüsselung und Versionierung aktiviert)
"

// 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);

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

    // Artefakt-Definitionen
    const sourceOutput = new codepipeline.Artifact("SourceOutput");
    const buildOutput = new codepipeline.Artifact("BuildOutput");

    // CodeBuild-Projekt
    const buildProject = new codebuild.PipelineProject(this, "BuildProject", {
      buildSpec: codebuild.BuildSpec.fromSourceFilename("buildspec.yml"),
      environment: {
        buildImage: codebuild.LinuxBuildImage.STANDARD_7_0,
        privileged: true,  // Für Docker-Builds erforderlich
      },
      environmentVariables: {
        AWS_ACCOUNT_ID: { value: this.account },
      },
    });

    // ECR-Zugriffsrechte vergeben
    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,
            }),
          ],
        },
      ],
    });

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

---

Schritt 3: Testergebnis-Berichte konfigurieren

claude -p "
Ich möchte Testergebnisse in CodeBuild an CodeBuild Reports senden,
damit ich pro PR Qualitätsberichte einsehen kann.

- Test-Framework: Vitest
- Coverage-Report: Istanbul (lcov-Format)
- Reports-Abschnitt zur buildspec.yml hinzufügen
- Report-Gruppe auch mit CDK definieren
"

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

---

Schritt 4: Multi-Environment-Pipeline-Design

claude -p "
Entwirf eine CDK-gestaffelte Deployment-Pipeline für 3 Umgebungen: dev → staging → prod.

- dev: automatisches Deployment bei Push auf main-Branch
- staging: Deployment nach dev-Erfolg, mit manueller Genehmigung
- prod: Deployment nach staging-Erfolg, mit manueller Genehmigung
- Slack-Benachrichtigung wenn Deployment jeder Umgebung abgeschlossen
"

// Manuelle Genehmigungsgates für staging → prod hinzufügen
{
  stageName: "Approve_Staging",
  actions: [
    new codepipeline_actions.ManualApprovalAction({
      actionName: "Approve_Deploy_to_Staging",
      notificationTopic: alertTopic,
      additionalInformation: "Deployment zu Staging genehmigen?",
    }),
  ],
},
{
  stageName: "Deploy_Staging",
  actions: [
    new codepipeline_actions.EcsDeployAction({
      actionName: "Deploy_to_Staging",
      service: stagingService,
      input: buildOutput,
    }),
  ],
},

---

4 häufige Fallstricke

1. privileged: true in CodeBuild vergessen

Zum Bauen von Docker-Images ist privileged: true Pflicht. Ohne diese Einstellung erscheint der Fehler Cannot connect to the Docker daemon.

2. Unzureichende GitHub OAuth Token-Berechtigungen

Die GitHub-Source benötigt den repo-Scope. Nur public_repo funktioniert nicht für private Repositories.

3. S3-Artefakt-Bucket-Region

Pipeline und Artefakt-S3-Bucket müssen sich in derselben Region befinden. Cross-Region-Pipelines erfordern zusätzliche Konfiguration.

4. imagedefinitions.json-Format für ECS Deploy Action

ECS-Deployment erfordert das exakte Format:

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

Der Container-Name muss exakt mit dem Container-Namen in der Task-Definition übereinstimmen.

---

Mit der minimalen Source-Build-Test-Deploy-Struktur beginnen

Für Einsteiger ist CodePipeline eine Release-Förderstrecke. Die Pipeline ist der gesamte Ablauf. Eine Stage ist ein Abschnitt wie Source, Build, Test oder Deploy. Eine Action ist die konkrete Aufgabe in dieser Stage. Ein Artifact ist das Paket, das an die nächste Action weitergegeben wird, zum Beispiel Quellcode oder ein von CodeBuild erzeugtes dist-Verzeichnis.

Die AWS-Seite CodePipeline concepts beschreibt genau dieses Modell. Wenn Claude Code diese Begriffe sauber bekommt, werden Pipeline, IAM und Artifact-Verkettung deutlich besser prüfbar.

Ein guter Start ist Source -> Build -> Test -> Approve -> Deploy. Laut AWS-Erstellungsleitfaden braucht eine Pipeline mindestens eine Source Stage und eine weitere Build- oder Deploy-Stage. Vor Production ist eine Manual approval fast immer sinnvoll.

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

Deploy-Beispiele für S3/CloudFront und Lambda

Bei einer statischen Website erstellt CodeBuild dist und eine S3 Deploy Action entpackt das Artifact in den Bucket. Die CloudFront-Invalidierung bleibt besser eine nachgelagerte CodeBuild- oder Lambda-Invoke-Action. Bei Lambda paketiert CodeBuild die Funktion und CloudFormation deployt das paketierte Template.

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

Drei Praxisfälle reichen oft aus: Astro oder Next.js nach S3/CloudFront, eine Lambda-API über CloudFormation und ein Team-Flow, bei dem staging automatisch läuft, production aber eine Freigabe braucht. Getrennte Stages halten Artifacts und IAM sauber.

Fehlersuche nach Stage und Action

Bei Source-Fehlern prüfst du ConnectionArn, Branch und Artifact-Format. Bei Build-Fehlern prüfst du CodeBuild-Logs, buildspec, Variablen und IAM. Bei Deploy-Fehlern prüfst du Input-Artifact-Namen, S3-Rechte, CloudFormation-Role, Lambda-Paketpfad und Region.

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

Typische Fehler sind BuildOutput erzeugen, aber SourceOutput deployen; dem CodeBuild Service Role zu wenige Rechte für S3, CloudFront, CloudFormation oder Lambda geben; oder Secrets als Klartext-Umgebungsvariablen speichern. Der AWS actions guide trennt Source, Build, Test, Deploy, Approval und Invoke. Genau so sollten auch Rechte geprüft werden.

Sicherer Prompt für Claude Code

Füge diesem Repository AWS CodePipeline + CodeBuild CI/CD hinzu.
Ziel: Source aus GitHub main, Build mit npm ci/test/build, Test als separate Action, Manual approval vor Production, Deploy nach S3 und CloudFront invalidieren.
Einschränkungen: Kein AdministratorAccess, keine breiten IAM-Wildcards, kein Production-Deploy ohne Freigabe, keine Secrets als Klartextvariablen, keine bestehenden Pipelines oder Buckets löschen.
Lieferumfang: buildspec.yml, pipeline.json oder CDK Stack, Diagnosebefehle, README-Betriebsanleitung.
Prüfung: aktuellen Zustand erklären, Diff zeigen, aws codepipeline get-pipeline-state und CodeBuild-Logs dokumentieren.

Der Prompt orientiert sich an Create a pipeline, stages, and actions und Define CI/CD pipelines. Wenn Claude Code den Bezug zu offiziellen Konzepten erklärt, wird Review einfacher.

Masa-Verifikationsnotiz und nächster Schritt

Am stärksten hilft eine feste Artifact-Namenskonvention: SourceOutput, BuildOutput, TestOutput. Dann ist ein Fehler schnell lokalisierbar. Für Einsteiger ist außerdem eine sichtbare JSON- oder Console-Version oft besser als sofort alles mit CDK zu verstecken.

Das Thema hängt direkt mit AWS IAM, AWS S3 und AWS Lambda zusammen. Allein reicht das kostenlose PDF als Start. Für Teams sollten buildspec, IAM, Freigaben, Rollback und Diagnose gemeinsam geplant werden; dafür passt die Claude Code Training- und Beratungsseite.

Zusammenfassung

Aufgabe	Beitrag von Claude Code
buildspec.yml-Generierung	Mit Build, Test, Docker und Security-Scan generiert
CDK-Pipeline	Alle Stages von Source→Build→Deploy automatisch generiert
Multi-Environment-Design	Gestaffeltes Deployment mit manuellen Genehmigungsgates
Testberichte	Automatisiert die Konfiguration von CodeBuild Reports

Die CodePipeline-Konfiguration mag komplex wirken, aber sage Claude Code einfach „Ich will diese Art von Pipeline” und es liefert sowohl buildspec.yml als auch CDK-Code auf einen Schlag. Fang am besten mit der buildspec.yml an.

Verwandte Artikel

• Claude Code × AWS ECS/Fargate Komplettanleitung
• Claude Code × AWS CloudFormation/CDK Komplettanleitung
• Claude Code × AWS IAM Komplettanleitung

Referenzen

• AWS CodePipeline Offizielle Dokumentation
• AWS CodeBuild buildspec-Referenz
• CDK CodePipeline-Modul