Stacktape Console can deploy a stage whenever someone pushes to a branch, and create a preview stage for every pull request. It works with GitHub, GitLab and Bitbucket. You connect the Git provider once, link a project to its repository and choose which branches deploy which stages. There is no pipeline file to maintain. Deployments run on a runner in your own AWS account.
In the Console, these rules are called Git deployments. There are two kinds:
- Push to branch deploys a fixed stage, such as
production, on every push to one branch. - Pull request opened deploys a preview stage named
pr-<number>for every pull request (merge request on GitLab) into one branch, redeploys it when new commits arrive, and can delete it when the pull request closes.
When to use
Use Git deployments when you want push-to-deploy and pull request previews without writing CI configuration.
Use custom CI/CD instead when you need tests, approval gates or other steps to run before the deploy, when your repository is on another Git host, or when you deploy only occasionally. You can also keep tests in your provider's CI and use branch protection, so only tested code reaches a branch that deploys.
Before you start
You need:
- An AWS account connected to your Stacktape organization. See Connecting your AWS account.
- A Git connection for the provider that hosts the repository. An organization owner or admin creates it; the steps for each provider are below.
- A project linked to its repository. Owners, admins and developers can link a repository and manage Git deployments.
Connect your Git provider
Open the profile menu in the Console header and choose Git connections. Click Connect Git provider and pick the provider. Each connection appears in the list with a status. Connected means pushes are received. Needs attention on a GitLab or Bitbucket connection means Stacktape cannot use it, and pushes are not deployed until an owner or admin clicks Reconnect. On a GitHub connection it means the GitHub App's repository write permissions are not approved yet; deployments keep working, and approving the permissions in GitHub clears it.
GitHub
- Choose GitHub. GitHub opens the installation page of the Stacktape GitHub App.
- Choose the GitHub account or organization, and select the repositories Stacktape can access.
- GitHub asks you to authorize Stacktape. This confirms that you installed the app; Stacktape removes the temporary authorization afterwards.
You are returned to the Console, and the connection appears in the list. One GitHub App installation can be connected to only one Stacktape organization. Disconnecting GitHub in the Console also uninstalls the Stacktape GitHub App from that GitHub account.
GitLab
GitLab connections work with groups on gitlab.com.
- Choose GitLab and sign in to GitLab. Approve the access Stacktape requests (the
apiscope). - In Choose a GitLab group, select the group and click Connect group. Only groups you own are listed. Repositories in its subgroups are included.
Stacktape keeps the connection's credentials up to date. Runners clone repositories with a read-only group deploy
token named Stacktape read-only …, which Stacktape replaces before it expires. If the group owner revokes Stacktape's
access, the connection shows Needs attention; reconnect it.
Bitbucket
Bitbucket connects through the Stacktape app for Bitbucket Cloud. A workspace admin installs it.
- Choose Bitbucket. Atlassian opens the installation page of the app. Install it in your workspace and approve the permissions it requests.
- In Bitbucket, open Workspace settings. Under Forge Apps, select Stacktape deployments and click Continue to Stacktape.
- In the Console, choose the Stacktape organization and click Connect workspace. A Stacktape owner or admin must finish this step.
If the Console says the connection link has expired, repeat step 2. A Bitbucket workspace can be connected to only one Stacktape organization. Disconnecting Bitbucket in the Console does not remove the app from Bitbucket; uninstall Stacktape in your workspace settings to do that.
Connections from Stacktape v3
GitLab connections made with a personal or group access token, and Bitbucket connections made with the older Bitbucket OAuth flow, are removed in v4. Projects that used them are no longer linked to a Git connection, so their pushes do not deploy. Connect GitLab or Bitbucket again with the steps above. If an existing project still does not deploy on push after you reconnect, email support@stacktape.com. GitHub App connections continue to work.
Link a project to its repository
A project created by stacktape deploy from your machine has no repository yet. Open the project and click
Connect next to "No Git repository". Choose the repository from your Git connections and click Connect.
Deployments use the Stacktape config committed in the repository.
After the first successful deploy of a new stage from an interactive terminal, the CLI also offers to set this up. It asks whether to set up automatic deployments on pushes to your current branch, opens the browser to connect the provider if needed, and creates a Push to branch Git deployment for that stage.
Create a Git deployment
- Open the project, click the gear icon next to its name and choose Configure Git deployments.
- Click New Git deployment.
- Choose the Deployment trigger: Push to branch or Pull request opened.
- Fill in the form:
| Field | What it does |
|---|---|
| Trigger on push to branch / Trigger on pull requests to branch | The branch to watch. For pull requests, this is the branch the pull request merges into. The name must match exactly; patterns are not supported. |
| Deploy to stage | The stage to deploy, such as production or staging. Shown only for Push to branch. Pull request previews always use pr-<number>. |
| Deploy to AWS account | The connected AWS account. |
| Deploy to region | The AWS region. |
| Config path | The Stacktape config file in the repository. |
| Delete stack after pull request is merged or closed? | Shown only for Pull request opened. Deletes the preview stage when the pull request closes. |
- Click Create Git deployment.
The Git deployments page lists each rule with its trigger, branch, stage, region and AWS account. To change a rule,
delete it and create a new one. Deleting a Git deployment stops future automatic deploys; stages it already deployed
keep running. To remove a stage, delete it in the Console or run stacktape delete.
What triggers a deployment
| Event | Result |
|---|---|
| Push to a branch with a Push to branch rule | Deploys the rule's stage with the pushed commit. Creates the stage if it does not exist. |
| Pull request opened (or reopened) into a branch with a Pull request opened rule | Deploys the preview stage pr-<number>. |
| New commits pushed to that pull request | Redeploys pr-<number> with the latest commit. |
| Pull request merged or closed | Deletes pr-<number> if the rule deletes previews. Otherwise the stage keeps running. |
These events do not deploy anything:
- pushes of tags, and branch deletions;
- pull requests from forks, so code from outside the repository never runs with your project's credentials;
- on GitLab, merge request changes that do not add commits, such as a new title or reviewer.
On Bitbucket, any update to an open pull request, including a title change, redeploys its preview.
On GitHub, pull requests that Stacktape opens from stacktape/fix- branches do not get previews.
Several rules and several pushes
- One event can match several rules. For example, two Push to branch rules for
maincan deploy to two regions or two AWS accounts. Each matching rule starts its own deployment at the same time. - Each project has one runner per AWS account and region. It runs up to two deployments at once. More deployments wait until a slot is free.
- Two operations never run on the same stage at the same time. If you push again while a stage is deploying, the new deployment waits for the current one to finish.
Following a deployment
Git deployments appear in the Console with their logs, like any other deployment.
- Pull request previews: Stacktape comments on the pull request (merge request on GitLab) when the preview deploy starts and updates the comment with the result. It comments the same way when a preview is deleted.
- GitHub: each deployment also appears in the repository's Deployments, marked successful or failed.
- Alerts: to get an alert in Slack, email or another channel, create a notification rule for the Git deployments events (preview deploy and Git push deploy, succeeded or failed).
If a preview deployment cannot start, for example because the AWS account is no longer connected, Stacktape updates the pull request comment to say that it failed.
Runner cost
Creating the first Git deployment for an AWS account and region prepares a runner in the background. The runner starts its installed tools, then stops until the first push arrives. It does not clone your repository or install project dependencies during this preparation. A push that arrives during preparation uses the same runner. If you set the runner to keep running when idle, it stays running instead.
Stopped runners have no EC2 compute charge, but their disks remain billable. The default 50 GiB root disk and 50 GiB cache disk cost about $8.80/month in Ireland, using gp3's included IOPS and throughput. Prices vary by region, and a growing cache costs more. Preparing a runner also incurs a short, one-time EC2 charge. The Console's Runners page shows regional cost estimates. See AWS EBS pricing.
The disks are billed until the runner is removed. Stacktape removes the runner, with its disks, build cache and IAM role, when you delete the project or the last Git deployment that uses its AWS account and region. A deployment that is already running finishes first. If the project's GitHub Actions runner uses the same account and region, the runner stays.
Pull request previews also cost whatever their AWS resources cost, until the preview stage is deleted. Turn on Delete stack after pull request is merged or closed? unless you need previews after merge, for example for post-merge QA.
Provider permissions for security fix pull requests
When you ask Stacktape to prepare a security fix, it creates a stacktape/* branch, commits the selected file changes
and opens a pull request. It never force-pushes, writes directly to the repository's default branch, closes pull
requests or sets commit statuses. The Console requires security:manage access to that project before it can start these
writes.
The provider connection must allow these writes:
- GitHub: the app needs read and write access to repository Contents, Pull requests and Commit statuses. When Stacktape asks for new permissions, a GitHub account owner must approve them on the existing installation. Until then, the connection shows Needs attention with a Reconnect action.
- GitLab: the group connection's
apiscope covers the branch, commit and merge request. The read-only deploy token is used only for cloning. Reconnect the group if its access has expired or been revoked. - Bitbucket: the app needs read and write access to repositories and pull requests. When the app's permissions change, a workspace admin must approve the app upgrade in Bitbucket.
Deployments keep working while new permissions wait for approval, but Stacktape cannot open a security fix pull request until they are approved.
Typical setup
| Rule | Trigger | Branch | Stage | Purpose |
|---|---|---|---|---|
| Production | Push to branch | main | production | Deploys every merge to main |
| Staging | Push to branch | develop | staging | Deploys every push to develop |
| Previews | Pull request opened | main | pr-<number> | A preview for every pull request into main, deleted when it closes |
For naming, cost and cleanup advice for preview stages, see Stacks per Git branch pattern.
GitOps with Console FAQ
How is this different from custom CI/CD?
Git deployments need no pipeline file: you configure them in the Console, and Stacktape deploys on the runner in your AWS account. Custom CI/CD means you write the pipeline yourself (GitHub Actions, GitLab CI, Bitbucket Pipelines or another system) and call the Stacktape CLI as a step. Custom CI/CD gives you control over tests, approvals and extra build steps.
Can I run tests before deploying?
Not inside a Git deployment. It deploys on every matching event. Run tests in your provider's CI and require them to pass before merging, or use custom CI/CD.
Can one push deploy to several accounts or regions?
Yes. Create one Push to branch rule for each AWS account and region, all watching the same branch. A push starts all of them at once.
A push did not deploy. What should I check?
- In Git connections, the connection shows Connected, not Needs attention.
- The project page shows the repository, not "No Git repository".
- A Git deployment of the project watches exactly the branch you pushed to, or, for previews, the branch the pull request merges into.
- The event is one that deploys: not a tag, a branch deletion or a pull request from a fork.
- On GitHub, the Stacktape GitHub App has access to the repository. Check the app's repository access in your GitHub account or organization settings.