Skip to content
Warp

Factories > Secrets

Configuring AWS ECR credentials

Open in ChatGPT ↗
Ask ChatGPT about this page
Open in Claude ↗
Ask Claude about this page
Copied!

Create an IAM role-backed secret and attach it to a Warp-hosted Linux runner to pull private container images from Amazon ECR.

An “AWS ECR credential” lets a Warp-hosted Linux runner pull private Amazon ECR images. Warp stores the role ARN and requests a short-lived token per run. Create the credential in the web app, not the legacy CLI.

Prerequisites

Section titled “Prerequisites”
  • AWS access to create an IAM role in the account that owns the registry.
  • Permission to create team secrets and edit the factory’s runner configuration.
  • An existing Warp-hosted Linux runner. See Runners for Warp Factories.

Creating the ECR credential

Section titled “Creating the ECR credential”
  1. In the Warp Factories web app, click Secrets, then click New > Create secret.
  2. At the top of the form, click Untitled and enter a secret name such as ECR_PULL_CREDENTIAL.
  3. In the “Type” dropdown, choose AWS ECR credential.
  4. In the registry’s AWS account, create an IAM role with the trust and permissions policies shown in the form. If you restrict repository read actions to a repository ARN, keep ecr:GetAuthorizationToken on Resource: "*".
  5. Back in the secret form, enter the “IAM role ARN” and “AWS region”, then click Save.

Warp derives the registry host from the role’s account ID and region. Creation checks role assumption and token retrieval, not repository-specific pull permissions.

Attaching the credential to a runner

Section titled “Attaching the credential to a runner”

For a Warp-managed factory:

  1. In the Warp Factories web app, click your factory in the sidebar to expand it, then click Settings.
  2. In the “Runners” section, click the pencil button labeled Edit runner next to the Linux runner.
  3. In the runner editor’s “Private image credential” dropdown, choose the ECR secret you created. Its registry host must match the image’s registry.
  4. Click Save.

For an externally managed runner, set platform.linux.registryCredentialSecretName to the secret name in its YAML file and apply the change through a pull request. See runner file syntax.

Start a new run using the runner to confirm it can pull the private image. The credential authenticates image pulls and isn’t injected into the agent environment. Self-hosted workers use backend-specific registry authentication instead.

Changing permissions or retiring the credential

Section titled “Changing permissions or retiring the credential”

To change ECR permissions, update the IAM role in AWS. To retire the credential, remove its runner references, then delete the team secret.

Troubleshooting

Section titled “Troubleshooting”

ECR role assumption fails

Section titled “ECR role assumption fails”

Check that the role exists, the ARN is correct, and its trust policy matches the form, including your team’s sts:ExternalId. AWS returns AccessDenied for missing roles and trust-policy denials. For other errors, check that AWS STS is available in the registry’s region.

ECR token retrieval fails

Section titled “ECR token retrieval fails”

Confirm that the role allows ecr:GetAuthorizationToken on Resource: "*". For access denials, check permissions boundaries and AWS Organizations service control policies. For other failures, confirm that the AWS region matches the registry.

ECR image pulls fail

Section titled “ECR image pulls fail”

Confirm that the role grants ecr:BatchCheckLayerAvailability, ecr:BatchGetImage, and ecr:GetDownloadUrlForLayer for the repository, and that the credential’s registry host matches the image’s registry.

Section titled “Related pages”