Custom CI/CD

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_KEY as 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.

ProviderWhere to store the secret
GitHub ActionsRepository Settings → Secrets and variables → Actions
GitLab CISettings → CI/CD → Variables (masked)
Bitbucket PipelinesRepository Settings → Pipeline → Repository variables
CircleCIProject 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:

npx stacktape deploy --stage production --region us-east-1 --yes

A delete command (for PR cleanup):

npx stacktape delete --stage pr-42 --region us-east-1 --yes

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.

npx stacktape deploy --stage staging --region us-east-1 --full --yes

--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.

npx stacktape deploy --stage production --region us-east-1 --auto-rollback --yes

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:

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Deploy to production
        env:
          STACKTAPE_API_KEY: ${{ secrets.STACKTAPE_API_KEY }}
        run: npx stacktape deploy --stage production --region us-east-1 --yes

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

name: Test and Deploy
on:
  push:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test
  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Deploy to production
        env:
          STACKTAPE_API_KEY: ${{ secrets.STACKTAPE_API_KEY }}
        run: npx stacktape deploy --stage production --region us-east-1 --yes

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.

name: PR Preview
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  deploy-preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Deploy PR preview
        env:
          STACKTAPE_API_KEY: ${{ secrets.STACKTAPE_API_KEY }}
        run: npx stacktape deploy --stage "pr-${{ github.event.pull_request.number }}" --region us-east-1 --yes

Add a cleanup workflow that runs when the PR is closed:

name: Cleanup PR Preview
on:
  pull_request:
    types: [closed]
jobs:
  delete-preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Delete PR preview
        env:
          STACKTAPE_API_KEY: ${{ secrets.STACKTAPE_API_KEY }}
        run: npx stacktape delete --stage "pr-${{ github.event.pull_request.number }}" --region us-east-1 --yes

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:

concurrency:
  group: deploy-production
  cancel-in-progress: false

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:

deploy:
  image: node:20
  stage: deploy
  only:
    - main
  script:
    - npx stacktape deploy --stage production --region us-east-1 --yes
  variables:
    STACKTAPE_API_KEY: $STACKTAPE_API_KEY

Store STACKTAPE_API_KEY as a masked CI/CD variable in your GitLab project settings.

Multi-stage pipeline with tests

stages:
  - test
  - deploy

test:
  image: node:20
  stage: test
  script:
    - npm ci
    - npm test

deploy-staging:
  image: node:20
  stage: deploy
  only:
    - develop
  script:
    - npx stacktape deploy --stage staging --region us-east-1 --yes
  variables:
    STACKTAPE_API_KEY: $STACKTAPE_API_KEY

deploy-production:
  image: node:20
  stage: deploy
  only:
    - main
  script:
    - npx stacktape deploy --stage production --region us-east-1 --yes
  variables:
    STACKTAPE_API_KEY: $STACKTAPE_API_KEY
  when: manual

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:

image: node:20

pipelines:
  branches:
    main:
      - step:
          name: Deploy to production
          script:
            - npx stacktape deploy --stage production --region us-east-1 --yes

Store STACKTAPE_API_KEY as a repository variable in Bitbucket Pipeline settings.

CircleCI

Add to .circleci/config.yml:

version: 2.1
jobs:
  deploy:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Deploy to production
          command: npx stacktape deploy --stage production --region us-east-1 --yes
workflows:
  deploy-on-push:
    jobs:
      - deploy:
          filters:
            branches:
              only: main

Store STACKTAPE_API_KEY as a project environment variable in CircleCI.

Choosing CI runner capacity

ScenarioRecommended command
Small to medium project, CI runner has enough CPU/RAMstacktape deploy (default --runner local)
Large dependencies or container buildsdeploy on a larger CI worker
Need a consistent build environmentPin the CI image and tool versions
Need AWS-hosted GitHub Actions computedeploy on a self-hosted runner
Want fastest possible deploy from CIstacktape 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:

BranchStageRegionTrigger
mainproductionus-east-1Push (after tests pass)
developstagingus-east-1Push
PR branchpr-{number}us-east-1PR 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.

npx stacktape diff --stage production --region us-east-1

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.