Codeconnections

Both work in pipeline configurations. IAM policy prefix must match the resource ARN prefix.

Provider Comparison

Create a Connection

For self-managed providers, use --host-arn instead of --provider-type:

Check status:

The PENDING State Trap

Connections created via CLI/CloudFormation/CDK are always PENDING. There is NO API to complete authorization — the console OAuth handshake is mandatory.

A PENDING connection:

• Returns no errors from create-connection
• Passes ARN validation in pipeline definitions
• Silently fails when the pipeline fetches source

Authorize a Connection (Console Required)

GitHub / GitHub Enterprise

1. AWS Console → Developer Tools > Settings > Connections
2. Select PENDING connection → Update pending connection
3. Install a new app (or select existing GitHub App)
4. Browser redirects to GitHub — sign in as organization owner
5. Select org, choose repos → Install
6. Back in AWS Console → Connect

Pitfall: Non-owner members get cookie errors or blank pages. GitHub App installation REQUIRES org owner role.

GitLab.com / GitLab Self-Managed

1. AWS Console → Developer Tools > Settings > Connections
2. Select PENDING connection → Update pending connection
3. Redirects to GitLab → authorize the AWS application
4. Connect to finalize

Bitbucket Cloud

Same flow as GitLab: Console → select connection → redirect → authorize → Connect.

Verify

Create a Host Resource (Self-Managed Only)

Required for GitHub Enterprise Server and GitLab Self-Managed. NOT needed for hosted providers.

--vpc-configuration required when endpoint is not publicly accessible. TlsCertificate accepts PEM-encoded CA cert (base64).

Host creation is async — check status:

Connection Sharing

A single connection serves unlimited pipelines within the same account and region. Create one connection per provider per account — do not create one per pipeline.

Cross-account: share connections using AWS Resource Access Manager (RAM). See sharing connections (opens in a new tab). Without RAM, each account needs its own connection.

IAM Configuration

Use codeconnections: prefix for all Actions. The dual prefix only matters in the Resource field (to match existing ARNs):

CRITICAL: UseConnection is over-permissive without condition keys. It grants access to ALL repositories the connection can reach. MUST specify conditions:

For pipeline service roles: minimum codeconnections:UseConnection with condition keys scoped to the repo.

For CodeBuild roles using CODEBUILD_CLONE_REF: add codeconnections:UseConnection to the CodeBuild service role (not the pipeline role), with the same condition key scoping.

Common Errors

Security

• MUST scope UseConnection with condition keys (FullRepositoryId, ProviderAction) — without them, any repo accessible to the connection is exposed
• Scope Resource to specific connection ARNs in production
• Enable CloudTrail for codeconnections:* API auditing
• Revoke connections when personnel with OAuth access leave the organization
• Connections store OAuth tokens managed by AWS — prefer connections over manual PATs which cannot be auto-rotated

Related

• codepipeline.md for source action and trigger configuration
• troubleshooting.md for pipeline-level debugging