Connecting Your AWS Account

Stacktape deploys infrastructure into your own AWS account using a secure cross-account IAM role. You connect an AWS account once in the Stacktape Console, and Stacktape handles credential management from that point — no manual AWS access keys required. Your projects and stacks can be deployed to any region.

Overview

The AWS accounts page (/aws-accounts) in the Stacktape Console lets you establish and manage the trust relationship between Stacktape and your AWS accounts. When you connect an account, Stacktape generates a link to an AWS CloudFormation Quick Create Stack page. The CloudFormation stack creates a cross-account IAM role that Stacktape assumes to interact with your AWS account — perform deployments, list logs, fetch metrics, and manage resources on your behalf. Credentials are temporary and short-lived — no permanent AWS access keys are stored or exchanged.

Each connected account appears in a table showing its name, AWS account ID, connection status, creation date, and primary regions. You can connect multiple AWS accounts to a single organization — for example, separate accounts for production and development.

Connecting your account is free. You only pay for the AWS resources that Stacktape deploys into your account. For a detailed breakdown of what permissions the cross-account role includes, see AWS permissions.

Walkthrough

You need the org:manage-aws-accounts permission in your Stacktape organization to connect an account.

  1. Open the modal — In the Stacktape Console, open /aws-accounts and click Connect AWS account.
  2. Name the account — Enter a label for the connection (e.g. "production" or "dev-account"). This name is for your reference only — the Console pre-fills a default like aws-account-1.
  3. Create the connection stack in AWS — Click Connect account in AWS console. This opens the generated AWS connection link in a new tab. The modal shows an image of the AWS-side steps to follow.
  4. Wait for activation — Return to the Stacktape Console. A newly created connection can appear as PENDING until the AWS CloudFormation stack finishes. While a PENDING account exists, the Console refetches account data every two seconds. When the backend returns the account as ACTIVE, the table shows ACTIVE.

Warning: The connection CloudFormation stack must be created in the eu-west-1 region. The Console opens a generated AWS link that targets the correct region. Your projects and stacks can be deployed to any region.

The connection modal contains two steps: an account name input field (Step 1) and an image illustrating the AWS-side steps to follow when creating the CloudFormation connection stack (Step 2).

Connection States

Each connected AWS account has one of three states:

StateMeaningAction needed
ACTIVE (green)Connection is working. Stacktape can deploy to this account.None.
PENDING (orange)The connection link was generated but the CloudFormation stack hasn't finished creating.Use the "Finish the account connection" link shown in the Note column to complete stack creation in AWS.
BLOCKED (red)The connection failed or was revoked. The status reason explains why.Check the status reason in the Note column, fix the issue in AWS, and reconnect if needed.

While a PENDING account exists on the AWS accounts page, the Console refetches account data every two seconds. When the backend returns the account as ACTIVE, the table shows ACTIVE.

Common Tasks

Connecting multiple AWS accounts

Organizations commonly connect separate AWS accounts for different purposes — a production account with stricter controls and a development account for experimentation. Click Connect AWS account again and repeat the walkthrough for each additional account. Each connection is created through its own generated AWS CloudFormation flow.

Choosing the account for a CLI command

CLI commands that work with a deployed stack, such as deploy, delete and rollback, run in one connected account. The CLI picks it in this order:

  1. --aws-account <name>, the account's name in the Console.
  2. The account your local AWS credentials belong to: --profile, then AWS_PROFILE, then AWS_ACCESS_KEY_ID in the environment. The CLI reads the account ID from the profile's sso_account_id or role_arn when it can, and otherwise asks AWS STS.
  3. The default saved with stacktape defaults set.
  4. Your organization's only connected account.

If the local credentials belong to an account that is not connected, the command stops before it changes anything and lists the connected accounts. It also stops when their account cannot be determined, for example when an SSO session has expired, and when a profile and environment keys point to different accounts. To deploy anyway, pass --aws-account, unset the profile, or connect the account.

--aws-account takes precedence over a profile; the CLI prints a line saying the profile is ignored. AWS credentials in environment variables are still used for the deployment when they are set, so they must belong to the selected account.

Each of these commands prints the account it uses, for example AWS credentials loaded via Stacktape for account production (222222222222).

Revoking access

You can revoke Stacktape's access to your AWS account in two ways:

  • Delete the AWS account connection in the Stacktape Console — removes the connection from Stacktape's side.
  • Delete the CloudFormation connection stack in the AWS Console — removes the IAM role from your AWS account. If Stacktape later reports the connection as BLOCKED, check the status reason in the Note column.

Checking which regions an account uses

The AWS accounts table shows Primary regions for each connected account. The table displays the account's primary regions when checked, or "not checked" if regions haven't been evaluated yet. The connection modal also states that projects and stacks can be deployed to any region.

Troubleshooting

Account stuck in PENDING

If your account remains in PENDING state:

  1. Use the Finish the account connection link in the Note column to reopen the generated AWS CloudFormation flow. If AWS reports a stack creation failure, inspect the failure in the AWS CloudFormation console.
  2. Verify the stack is being created in the eu-west-1 region — the Console's generated link targets the correct region automatically.
  3. Users with the org:manage-aws-accounts permission see a delete control on connected-account rows. If you cannot complete the AWS-side stack, delete the account entry and start a new connection.

Cannot delete a connected AWS account

Stacktape prevents deletion when projects reference the account in their GitOps deployment configurations. The error message lists the affected projects. Delete the GitOps deployment configurations from the listed projects, then retry the deletion.

Account shows BLOCKED

A BLOCKED state means the connection is no longer usable. Read the status reason in the Note column — for example, the IAM role may have been modified or removed. Fix the underlying issue in AWS. You can remove the Stacktape-side connection from the table if you need to recreate it.

"You do not have permission to manage AWS accounts"

This action requires the org:manage-aws-accounts permission. Ask your organization owner or admin to grant you the appropriate role. See Team and access control for details.

Connecting Your AWS Account FAQ

Do I need to create AWS access keys for Stacktape?

No. Stacktape uses cross-account IAM role assumption, not static access keys. The connection CloudFormation stack creates an IAM role that Stacktape assumes with temporary credentials. You never need to generate, rotate, or store AWS access keys for Stacktape to work.

Can I deploy to any AWS region after connecting?

Yes. The connection stack must be created in eu-west-1, but that only controls where the connection CloudFormation stack is created. Your projects and stacks can be deployed to any region.

Is connecting my AWS account free?

Connecting the account is free. You pay only for the AWS resources that Stacktape later deploys into your account.

How do I revoke Stacktape's access to my AWS account?

You have two options: delete the AWS account connection in the Stacktape Console (removes it from Stacktape's side), or delete the CloudFormation connection stack in the AWS Console (removes the IAM role from your account). Either one stops deployments to that account from working. After deleting the stack in AWS, Stacktape reports the connection as BLOCKED — remove it from the AWS accounts table and create a new connection to restore access.

Why is the "Connect AWS account" button disabled?

Connecting and deleting account connections requires the org:manage-aws-accounts permission. If the button (or the delete control on a connected-account row) is disabled, you don't currently have that organization permission. Ask your organization owner or admin to grant the appropriate role — see Team and access control.

Why won't my account stay connected (stuck in PENDING)?

PENDING means the connection link was generated but the CloudFormation stack in AWS hasn't finished creating. The Console refetches the account every two seconds and flips it to ACTIVE automatically once the backend reports it. If it stays PENDING, use the "Finish the account connection" link in the Note column to reopen the AWS flow, and verify the stack is being created in the eu-west-1 region.

Why can't I delete a connected AWS account?

Stacktape blocks deletion when projects reference the account in their GitOps deployment configurations; the error message lists the affected projects. Remove the GitOps deployment configurations from those projects, then retry the deletion.