Stacktape integrates with any CI/CD system that can run shell commands — GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines, Jenkins, or custom scripts. Authenticate with an API key, then run deploy or delete as a pipeline step to deploy and manage your AWS infrastructure from existing workflows.
When to use custom CI/CD
Choose custom CI/CD when your deployment workflow needs steps beyond "push triggers deploy." Typical reasons:
- Pre-deploy validation — run tests, type checks, or lint before allowing a deployment
- Approval gates — require manual approval or status checks before production deploys
- Multi-step pipelines — build artifacts, run integration tests, deploy staging, run smoke tests, then deploy production
- Notifications and reporting — post deploy status to Slack, update issue trackers, or trigger downstream jobs
- Non-git triggers — deploy on schedule, on a webhook from another system, or from a monorepo filter
Custom CI/CD gives you full control over what happens before, during, and after a Stacktape deployment.
When NOT to use custom CI/CD
If you want push-to-deploy with zero pipeline code, use GitOps with Console instead. GitOps handles branch pushes and PR previews automatically — no workflow files to write or maintain. Writing a CI pipeline purely to call stacktape deploy on every push adds maintenance for no benefit.
You can combine both: GitOps for staging and PR previews, custom CI for production where you need test gates.
Authentication
Create an API key in the Stacktape Console under API keys and store it as a secret in your CI provider. You can authenticate the CLI in two ways:
- Explicit login step — run
stacktape login --api-key <key>as a pipeline step before deploying. The login command verifies the key and saves it for subsequent CLI commands. - Environment variable — set
STACKTAPE_API_KEYas an environment variable in your CI runner. The CI examples on this page use this approach for brevity.
If the pipeline also sets AWS credentials, for example with aws-actions/configure-aws-credentials, Stacktape deploys to the connected account they belong to. Pass --aws-account <name> to choose the account explicitly; the AWS credentials must then belong to it. See Choosing the account for a CLI command.
| Provider | Where to store the secret |
|---|---|
| GitHub Actions | Repository Settings → Secrets and variables → Actions |
| GitLab CI | Settings → CI/CD → Variables (masked) |
| Bitbucket Pipelines | Repository Settings → Pipeline → Repository variables |
| CircleCI | Project Settings → Environment Variables |
Create a dedicated API key for CI/CD rather than reusing a personal key. This makes it easy to rotate without disrupting developer workflows.
Essential CLI flags for CI
--yes
The deploy and delete commands can prompt for confirmation before modifying infrastructure. The --yes flag skips these prompts. Always include this flag in automated pipelines — without it, the CLI may wait for confirmation before modifying infrastructure, which is unsuitable for automated CI jobs. See the deploy CLI reference for details.
--stage and --region
CI commands should pass --stage and --region explicitly so the deployment target is unambiguous. Set the stage to match your environment (e.g. production, staging, or a dynamic PR name). If the combined project name and stage name produces a stack name that's too long, Stacktape warns that some AWS resource names will be obfuscated to stay within CloudFormation naming limits — keep stage names short when deriving them from PR numbers or branch names.
A full deploy command in CI:
A delete command (for PR cleanup):
If your CI pipeline deploys more than one Stacktape project, make the project selection explicit — set the project name in each configuration file or pass it as a CLI argument.
--full
When only code changed, stacktape deploy updates the changed Lambda functions and container workloads directly, without CloudFormation (see Fast deployments). The --full flag deploys every change through CloudFormation instead.
--auto-rollback
By default, a failed deployment keeps what it created or updated, and the next pipeline run continues from the failure. The --auto-rollback flag makes CloudFormation undo a failed deployment instead, so the stack returns to the last successful deployment (or, for a first deployment, is deleted). When a deploy is rolled back (outside of stack-monitoring errors, where the actual stack outcome is unknown), Stacktape removes deployment artifacts from the rolled-back attempt. See the deploy CLI reference for details.
Use automatic rollback for production pipelines that must never leave a stack between two versions. To set it for every deployment of a stage, use deploymentConfig.autoRollback with $Stage().
GitHub Actions
A GitHub Actions workflow can run the Stacktape CLI from a Node.js runner with a single run step. Create .github/workflows/deploy.yml in your repository:
Store STACKTAPE_API_KEY in your repository's Actions secrets. The npx stacktape invocation downloads and caches the CLI on first run.
Adding tests before deploy
The needs: test dependency ensures the deploy only runs when tests pass.
PR preview environments
Deploy an isolated stage for each pull request and tear it down on close. Each PR stage creates real AWS resources for whatever your Stacktape config defines — delete preview stages promptly to avoid accumulating unused infrastructure.
Add a cleanup workflow that runs when the PR is closed:
Delete preview stages on PR close to avoid unused infrastructure and costs. Each preview stage provisions the full set of resources defined in your config — databases, functions, containers, and networking — all of which incur AWS charges while running.
For more on the branch-to-stage mapping pattern, see stacks per git branch.
Concurrency control
Stacktape deploys use CloudFormation, which serializes updates to a single stack. If two CI runs deploy to the same stage simultaneously, one fails because the stack is in an UPDATE_IN_PROGRESS state. Add a concurrency group to prevent parallel deploys:
Place this at the job level in your GitHub Actions workflow. The cancel-in-progress: false setting queues new runs instead of cancelling them, so no deploy is silently dropped.
GitLab CI
A GitLab CI pipeline can run the Stacktape CLI from a Node.js Docker image. Add to .gitlab-ci.yml:
Store STACKTAPE_API_KEY as a masked CI/CD variable in your GitLab project settings.
Multi-stage pipeline with tests
The when: manual on production requires a developer to click "Run" in the GitLab UI — an approval gate without additional tooling. Use GitLab resource groups if you need to prevent parallel deploys to the same stage.
Bitbucket Pipelines
Add to bitbucket-pipelines.yml:
Store STACKTAPE_API_KEY as a repository variable in Bitbucket Pipeline settings.
CircleCI
Add to .circleci/config.yml:
Store STACKTAPE_API_KEY as a project environment variable in CircleCI.
Choosing CI runner capacity
| Scenario | Recommended command |
|---|---|
| Small to medium project, CI runner has enough CPU/RAM | stacktape deploy (default --runner local) |
| Large dependencies or container builds | deploy on a larger CI worker |
| Need a consistent build environment | Pin the CI image and tool versions |
| Need AWS-hosted GitHub Actions compute | deploy on a self-hosted runner |
| Want fastest possible deploy from CI | stacktape deploy with caching |
The default deploy command runs the build and deployment on your CI worker. Configure CPU, memory, disk, Docker support, and dependency caches in the CI provider. For GitHub Actions, Stacktape can manage an EC2-based self-hosted runner in your AWS account.
Multi-environment patterns
A common pattern maps branches to stages:
| Branch | Stage | Region | Trigger |
|---|---|---|---|
main | production | us-east-1 | Push (after tests pass) |
develop | staging | us-east-1 | Push |
| PR branch | pr-{number} | us-east-1 | PR opened/updated |
Implement this with separate workflow triggers or CI stages. The core command stays the same — only the --stage value changes.
Passing config-level variables per environment
Stacktape supports deploy-time parameterization so you can keep one configuration file across all environments while varying database sizes, instance counts, or feature flags. See deploy-time parameters and directives for the available patterns.
Previewing changes before deploying
In workflows with approval gates, use diff as an earlier pipeline step to inspect what a deployment would change before approving it. This gives reviewers a chance to see the planned infrastructure diff without actually applying changes.
This is useful in production pipelines where a reviewer needs to see the infrastructure diff before approving. Pair it with a manual approval step so the team can review changes before the deploy job runs. See the diff CLI reference for details on its output.
Troubleshooting
CLI hangs or throws an error waiting for input
Add --yes to your deploy or delete command. Without this flag, the CLI may wait for confirmation before modifying infrastructure, which is unsuitable for automated CI jobs.
Authentication fails
Verify that you have authenticated — either by setting the STACKTAPE_API_KEY environment variable (case-sensitive) or by running stacktape login --api-key <key> before the deploy step. Check that the API key hasn't been revoked in the Console under API keys, and rotate it if necessary.
Stack name too long or resource names obfuscated
If the combined project name and stage name produces a stack name that exceeds CloudFormation naming limits, Stacktape warns that some AWS resource names will be obfuscated. When deriving stage names from PR numbers or branch names, keep them short — pr-42 is fine, but a long descriptive name combined with a long project name may trigger obfuscation.
Concurrent deploys to the same stage
A stack runs one deploy, rollback or delete at a time. If two CI runs deploy to the same stage simultaneously, the second waits for the first to finish, names it while it waits, and then deploys on top of what the first one deployed. If a CI job is killed, its lock expires within two minutes and the waiting deploy continues. If the killed job was running a release command, the waiting deploy also waits for that command to finish. Runs wait in no particular order, so a run of an older commit can finish last. To always end on the newest commit, use CI concurrency controls (a GitHub Actions concurrency group or a GitLab resource group), which also save the runner time spent waiting.
The first deploy of a new stage is the exception: until the stage exists, it has nowhere to keep the lock. If two first deploys of the same stage run at once, the second stops without changing anything; run it again.
Custom CI/CD FAQ
How do I authenticate Stacktape in a CI pipeline?
Run stacktape login --api-key <key> as a pipeline step before deploying — the login command verifies the key and saves it for subsequent CLI commands. Alternatively, set STACKTAPE_API_KEY as an environment variable in your CI runner. Create API keys in the Stacktape Console under API keys. Use a dedicated key for CI rather than a personal key so you can rotate it without disrupting developer workflows.
When should I use custom CI/CD vs GitOps?
Use GitOps with Console when you want zero-maintenance push-to-deploy with PR previews and no workflow files. Use custom CI/CD when you need pre-deploy test gates, manual approval steps, multi-step pipelines, or non-git triggers. You can combine both — GitOps for staging branches and custom CI for production.
Where does the deployment build run?
The standard deploy command builds on the CI worker that invokes it. Size that worker for your workload and configure provider-level caches for package managers and Docker. If you use Stacktape's self-hosted GitHub Actions integration, the workflow runs on the project's EC2 runner in your AWS account.
What happens when a deploy fails in CI?
By default, the stack keeps what the failed deployment created or updated and stays in CREATE_FAILED or UPDATE_FAILED. Fix the issue and run the pipeline again; the deploy continues from the failure. With --auto-rollback or deploymentConfig.autoRollback, CloudFormation rolls the deployment back instead, and Stacktape removes deployment artifacts from the rolled-back attempt (except after stack-monitoring errors, where the actual stack outcome is unknown). See Rollbacks for the full options.
How do I deploy to multiple AWS regions from CI?
Run the deploy command once per region with the same stage name but different --region values. Each region creates an independent stack. You can run these as parallel jobs in your CI pipeline. See multi-region deployments for patterns and considerations.
What happens when two deploys to the same stage run at once?
A stack runs one deploy, rollback or delete at a time, including deploys that skip CloudFormation. The second deploy waits for the first to finish and then deploys on top of its result. A killed run blocks the next one for at most two minutes. To control the order of runs, use a GitHub Actions concurrency group (with cancel-in-progress: false to queue rather than drop runs) or a GitLab resource group.