What Permissions Does BYOC Need in My AWS Account?

Answer

WarpBuild BYOC on AWS needs one IAM role in your account, created by a CloudFormation template that the cloud connection page hands you. That role carries fine-grained EC2 permissions for launching and terminating runners, a spot service-linked role grant, network describe permissions, S3 and snapshot permissions for cache and logs, and CloudFormation permissions for stack upgrades, all listed in full in the AWS configuration guide.

Your build steps never assume that role. Runner permissions come from a second grant: an IAM instance profile you create and attach per runner in the Custom Runner configuration, per the instance profile guide. The permissions available to runner instances are exactly the ones you provide through security groups and instance profiles, and WarpBuild adds none of its own to runner workloads, per the security hardening guide.

BYOC runs on AWS, GCP, and Azure, and the role structure below is the AWS shape (BYOC documentation). The macOS fleet is hosted by WarpBuild, so no AWS grant is involved in a macOS job.

Detail

The five permission contexts

The AWS configuration guide organizes the role into named policy contexts. Reviewing them by purpose is faster than reading the action list top to bottom.

Two details in that policy usually decide a security review. First, iam:PassRole appears once in the default document, inside the spot block, scoped to the single service-linked role ARN above rather than to *. Second, the EC2, network, and storage statements use Resource: "*", which is the line most reviewers ask about, and the customization path below is the documented answer.

What the role creates, by name

Every resource the integration role provisions follows a naming pattern, so you can write account policies and cost reports against it (AWS configuration guide).

WarpBuild also adds a managed-by: warpbuild tag to provisioned resources, along with tags carrying the stack name, stack ID, runner ID, runner labels, and GitHub organization. Stack resources pick up that tagging from CloudFormation template version 1.3 in create mode, and runners are tagged in all cases. That tag is the hook for AWS IAM tag-based access control if you want a boundary policy that limits the role to resources it created.

Narrowing the default policy

The configuration guide documents two customization paths. You can modify the CloudFormation template on the AWS redirect page before applying the connection role stack, or you can modify the permissions on the role after it is provisioned, at the name warpbuild-<integration-id>.

Removing a context removes the feature it supports, so decide per context:

• Drop the network context and import mode stops working, since selecting an existing VPC, subnets, and security group requires describing them.
• Drop the spot context and spot-backed runner sets stop launching, because AWS creates spot capacity through its service-linked role.
• Drop the storage context and the cache action and runner log upload paths break.
• Drop the CloudFormation context and connection and stack upgrades stop applying.

Treat the role as a versioned artifact. The guide states that updates may be required when new WarpBuild features need new permissions, so re-read the policy at each stack upgrade rather than assuming a hand-edited role stays complete. Teams that keep IAM in code have a path for this: Terraform support exists for BYOC on AWS, documented in the Terraform guide.

The instance profile is the workload half

An instance profile is configured at the runner level, under Custom Runner configuration and the Instance Profile ARN field, so a deploy runner and a unit-test runner under the same stack can carry different AWS authority. Attaching one takes a single grant on the integration role: iam:PassRole for the role you want attached, conditioned on the service.

aws iam put-role-policy \
    --role-name warpbuild-<UUID> \
    --policy-name PassRolePolicy \
    --policy-document '{
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": "iam:PassRole",
                "Resource": "arn:aws:iam::<account-id>:role/<runner-role>",
                "Condition": {
                    "StringEquals": {
                        "iam:PassedToService": "ec2.amazonaws.com"
                    }
                }
            }
        ]
    }'

The instance profile guide carries the same command plus an aws iam simulate-principal-policy call that confirms the grant resolves before you point a runner at the profile. The integration role name is on the WarpBuild connections page in the format warpbuild-<UUID>. Scoped examples for one bucket and one registry live on the instance profiles page, and the full policy walkthrough is on the IAM permissions page.

What the grant costs you

Nothing on the WarpBuild side changes with the size of the policy. BYOC runners bill $0.002 per runner minute to WarpBuild and the compute lands on your own cloud account (pricing page, checked on 2026-08-13).

The rest of the AWS setup, including stacks, subnets, and custom runner sizing, is on the BYOC on AWS page.

Related Questions

Does WarpBuild get permissions inside my running jobs?

No. The permissions available to runner instances are the ones you provide through security groups and an IAM instance profile, and WarpBuild adds none of its own to runner workloads, per the security hardening guide. The integration role that creates stacks and launches instances is a separate grant that your build steps never assume.

Can I narrow the default IAM policy?

Yes. Modify the CloudFormation template on the AWS redirect page before you apply the connection role stack, or modify the role after it is created at the name warpbuild-<integration-id> (AWS configuration guide). The managed-by: warpbuild tag lets you bound access further with AWS IAM tag-based access control. The context-by-context breakdown of what each removal costs is on the IAM permissions page.

What extra permission does attaching an instance profile need?

One iam:PassRole grant on the warpbuild-<UUID> integration role, scoped to the role ARN you want attached and conditioned on iam:PassedToService equal to ec2.amazonaws.com, per the instance profile guide. Verify it with aws iam simulate-principal-policy before attaching the profile to a runner. Worked examples are on the instance profiles page.

Which resources does the integration role create in my account?

S3 buckets named warpbuild-*, EC2 instances and EBS volumes named warp-*, and launch templates named tmpl-warp-*, per the AWS configuration guide. Every provisioned resource carries the managed-by: warpbuild tag, plus tags for the stack name, stack ID, runner ID, runner labels, and GitHub organization, which is what makes cost attribution in your own billing tools line up with runner labels. The BYOC on AWS page covers the stack objects those resources belong to.