aws-codepipeline-setup

AWS CodePipeline + CodeBuild Setup

Build a GitHub → CodeStar Connection → CodePipeline → CodeBuild pipeline interactively.

Role separation (important)

This skill strictly separates what Claude can automate from what the user must do manually.

Task	Owner	Reason
Export AWS_PROFILE / AWS_REGION	User	Shell environment is owned by the user
Run aws sts get-caller-identity	Claude (read-only)	Confirm active account/region
Issue GitHub Fine-grained PAT	User	Performed in the GitHub web UI
Store PAT in Secrets Manager	User	Keeps the secret out of Claude's session and logs
Approve the CodeStar Connection	User	Requires clicking in the AWS Console
Create the CodeStar Connection	Claude	create-connection CLI
Create IAM Role / Policy	Claude	CLI
Create S3 artifact bucket	Claude	CLI
Create CodeBuild project	Claude	CLI
Create CodePipeline V1/V2	Claude	CLI
Author and commit buildspec.yml	User	Repository code change

For every Claude-owned step, Claude first shows the full command and asks the user y/N before running it.

---

Step 0. Intake — ask about the pipeline shape

Run this first. Skip any question the user has already answered in context.

0-1. Ask the use case

"What do you need this pipeline for?

1. Auto-build and deploy on every commit push to a branch
2. Run lint / test / build on every pull request, before merge
3. Both
4. Something else (free-form)"

0-2. Recommend V1 or V2

Map the answer to a recommendation and state the reasoning in 1–2 lines:

Use case	Recommendation	Why
1 (commit push deploy)	V1	Flat $1/month per active pipeline suits frequent deploys; SUPERSEDED runs only the latest commit
2 (PR pre-merge)	V2	Pull request trigger filters only exist in V2; action-execution-minute billing is cheaper for sparse runs
3 (both)	V1 + V2 together	V1 handles deploys, V2 is the pre-merge gate. Roles and Connection are shared
4	Explain tradeoffs	—

Then ask: "V1 / V2 / Both / Pick again — how should we proceed?" Respect the user's choice even if it overrides the recommendation.

0-3. Collect the remaining inputs in one batch

Key	Example	Notes
app	my-app	Resource name prefix
github_owner	my-org	GitHub owner
github_repo	my-repo	GitHub repo
artifact_bucket	default codepipeline-artifacts-<app>	Claude creates it if it doesn't exist
v1_branches	["dev","staging","main"]	Only if V1 is selected
v1_buildspec	buildspec.yml	Only if V1 is selected
v2_buildspec	buildspec-pre-merge.yml	Only if V2 is selected
compute_type	BUILD_GENERAL1_MEDIUM (default)	See AWS CodeBuild docs
image	aws/codebuild/amazonlinux2-x86_64-standard:5.0 (default)	—

---

Step 1. Prerequisites — user actions (Claude only explains)

Claude does not execute these. Claude shows the checklist and example commands, then asks the user to confirm completion.

1-1. Activate an AWS profile

In the user's shell:

export AWS_PROFILE=<profile-name>
export AWS_REGION=<region>   # e.g. ap-northeast-2
aws sts get-caller-identity   # confirm account/user

Claude will later run aws sts get-caller-identity read-only to verify the active account and region. If the wrong account is active, ask the user to switch profiles.

1-2. Issue a GitHub Fine-grained PAT

Performed by the user in the GitHub web UI.

• Repository access: the specific repo(s) needed
• Repository permissions (Read & Write): Metadata (Read), Actions, Code, Commit statuses, Deployments, Pull requests
• Organization permissions: none

Claude does not accept the PAT string in the session. The user stores it in Secrets Manager in the next step.

1-3. Store the PAT in Secrets Manager (user runs this directly)

Claude shows the template only:

aws secretsmanager create-secret \
  --name /<app>/github-pat \
  --description "GitHub PAT for <app> CI/CD" \
  --secret-string '{"GITHUB_TOKEN":"<fine-grained-pat>"}'

After running it, the user shares only the returned Secret ARN with Claude. Claude uses the ARN from here on.

---

Step 2. Claude-owned steps — one approval per step

For each step, Claude shows the full command and asks y/N. If the command fails, Claude summarizes stderr and offers {retry / skip / abort}.

Temporary policy and pipeline JSON files live under /tmp/<app>-cicd/ and are removed at the end of Step 2.

2-1. Create the CodeStar Connection

aws codestar-connections create-connection \
  --provider-type GitHub \
  --connection-name <app>-github

• Save the ConnectionArn in the session state.
• Initial status is PENDING.

2-2. Approve the Connection — user action

Claude provides only the Console path and waits.

User action: AWS Console → Developer Tools → Settings → Connections → the new connection → Update pending connection → install and authorize the GitHub App.

After the user confirms approval:

aws codestar-connections get-connection --connection-arn <ARN>

Verify ConnectionStatus: AVAILABLE.

2-3. Create IAM roles (CodeBuild + CodePipeline)

Claude writes the policy JSON to /tmp/<app>-cicd/, then runs:

aws iam create-role --role-name codebuild-<app> \
  --assume-role-policy-document file:///tmp/<app>-cicd/cb-trust.json
aws iam put-role-policy --role-name codebuild-<app> \
  --policy-name codebuild-<app> \
  --policy-document file:///tmp/<app>-cicd/cb-policy.json

aws iam create-role --role-name codepipeline-<app> \
  --assume-role-policy-document file:///tmp/<app>-cicd/cp-trust.json
aws iam put-role-policy --role-name codepipeline-<app> \
  --policy-name codepipeline-<app> \
  --policy-document file:///tmp/<app>-cicd/cp-policy.json

The policy templates mirror the role shapes discussed in the plugin README. ARNs for the secret (from 1-3), the Connection (from 2-1), and the artifact bucket (from 2-4) are substituted at write time.

The CodePipeline role is shared by V1 and V2.

2-4. Create the S3 artifact bucket (if it doesn't exist)

If artifact_bucket already exists, verify it with aws s3api head-bucket and skip.

aws s3api create-bucket --bucket <artifact_bucket> \
  --create-bucket-configuration LocationConstraint=$AWS_REGION
aws s3api put-bucket-versioning --bucket <artifact_bucket> \
  --versioning-configuration Status=Enabled
aws s3api put-bucket-lifecycle-configuration --bucket <artifact_bucket> \
  --lifecycle-configuration file:///tmp/<app>-cicd/lifecycle.json

Apply a 30-day object expiration lifecycle.

2-5. Create CodeBuild projects

Create one or two projects based on the selection.

V1 deploy project (if V1 selected):

aws codebuild create-project \
  --name <app>-deploy \
  --source type=CODEPIPELINE,buildspec=<v1_buildspec> \
  --artifacts type=CODEPIPELINE \
  --environment type=LINUX_CONTAINER,image=<image>,computeType=<compute_type>,privilegedMode=false \
  --service-role <codebuild-role-arn> \
  --cache type=S3,location=<artifact_bucket>/codebuild-cache-v1

V2 pre-merge project (if V2 selected):

aws codebuild create-project \
  --name <app>-pre-merge \
  --source type=CODEPIPELINE,buildspec=<v2_buildspec> \
  --artifacts type=CODEPIPELINE \
  --environment type=LINUX_CONTAINER,image=<image>,computeType=<compute_type>,privilegedMode=false \
  --service-role <codebuild-role-arn> \
  --cache type=S3,location=<artifact_bucket>/codebuild-cache-v2

2-6. Create CodePipeline V1 (per branch) — if V1 selected

For each branch in v1_branches, write the pipeline JSON to /tmp/<app>-cicd/pipeline-v1-<branch>.json, then:

aws codepipeline create-pipeline \
  --cli-input-json file:///tmp/<app>-cicd/pipeline-v1-<branch>.json

Key fields in the pipeline JSON:

• pipeline.pipelineType: V1
• pipeline.executionMode: SUPERSEDED
• Source stage: AWS CodeStarSourceConnection provider with ConnectionArn, FullRepositoryId, and BranchName
• Build stage: the <app>-deploy project from Step 2-5

2-7. Create CodePipeline V2 — if V2 selected

aws codepipeline create-pipeline \
  --cli-input-json file:///tmp/<app>-cicd/pipeline-v2.json

Key fields in the pipeline JSON:

• pipeline.pipelineType: V2
• pipeline.triggers: Pull request filter (events: [OPEN, UPDATED], plus the branch filter)
• Source stage: the CodeStar Connection
• Build stage: the <app>-pre-merge project from Step 2-5

2-8. Clean up temporary files

rm -rf /tmp/<app>-cicd/

---

Step 3. Summary

Claude prints a markdown table of:

• Created resource names and ARNs (Connection, IAM roles, bucket, CodeBuild projects, pipelines)
• AWS Console links (CodePipeline, CodeBuild, Secrets Manager)

---

Step 4. Follow-up user actions — Claude only explains

4-1. Add buildspec files to the repository

• V1: buildspec.yml (install → build → deploy → S3 sync → CloudFront invalidation, etc.)
• V2: buildspec-pre-merge.yml (lint → typecheck → test → build, fail-fast)

4-2. Trigger the first run

• V1: push a commit to the target branch → check CodePipeline Executions.
• V2: open a PR → verify the entry in the PR Checks tab.

---

Execution rules

• The user does not type commands themselves. Claude runs them via Bash (except prerequisites, Secrets Manager storage, Console approval, and buildspec commits).
• Before each step, Claude shows the exact command and asks y/N. Anything other than y skips that step.
• On failure, Claude summarizes stderr and offers {retry / skip / abort}.
• ARNs produced in each step are kept in the session state for later steps to reuse.

Hard rules

• Never accept, echo, or persist the GitHub PAT value. The user stores it in Secrets Manager themselves and shares only the Secret ARN.
• No --no-verify or force-permission bypasses.
• Claude never runs export for AWS_PROFILE or AWS_REGION; it only reads what the user has set.
• If a resource with the same name already exists, do not overwrite it — ask the user how to proceed.
• Never try to automate the AWS Console UI. The CodeStar Connection approval must be done by the user.