GitHub source connections

Connect a workspace to a GitHub repository so pushes to a tracked branch plan and apply, and pull requests get a plan-only preview with a GitHub check and a plan comment. GitHub is the only supported version control provider.

Install the GitHub App

1. Open Get started from Help in the sidebar, or open a workspace’s Source tab.
2. Select Install GitHub App.
3. In GitHub, choose Only select repositories and pick the repositories StackShip should read.
4. Install, then authorize StackShip when GitHub asks.

Installing requires the admin or owner role in StackShip and permission to install apps in your GitHub organization. StackShip connects an installation only if your GitHub account can access it.

The App requests these permissions:

StackShip can’t push code or change repository settings. The only thing it writes to a pull request is its own plan comment.

If you installed the App before it requested Pull requests: Write, GitHub asks an organization owner to accept the new permission. Until someone does, pull requests still get checks but no plan comment.

To add or remove repositories later, change the App’s repository access in GitHub.

Connect a workspace

1. Open the workspace and select the Source tab.

2. Fill in the source settings:

   Field	Details
   Repository	One of the repositories the App can read
   Tracked branch	Pushes to this branch start plan-and-apply runs, for example main
   Working directory	The folder that contains your OpenTofu configuration, relative to the repository root. Use . for the root.
   Trigger paths, one per line	Optional. Only start runs when a changed file matches one of these patterns.
   Speculative-plan federation profile	Optional. Cloud credentials for pull-request plans.

3. Select Save source.

Changing source settings requires the admin or owner role. With the API, use PUT /v1/workspaces/{workspace_id}/source.

State and backends

Runs always read and write the workspace’s own state. Your configuration doesn’t need a cloud block; if it declares one, or a backend block such as s3, StackShip uses the workspace instead for its runs. Keep a cloud block only if you also run tofu against the workspace from your machine.

Trigger paths

Use trigger paths when several workspaces share one repository. With no paths, every change starts a run.

• Paths are relative to the repository root, for example infra/network/** or modules/*/main.tf.
• * matches within one folder, ** matches across folders, and ? matches one character.
• You can add up to 100 paths. Absolute paths, .., and backslashes aren’t allowed.

A push that creates the branch, rewrites history, or is too large for GitHub to list every changed file always starts a run.

What starts a run

Pull-request runs never receive sensitive variables, generic secrets, or plan-and-apply credentials.

Fork pull-request plans also can’t read the workspace’s state, read other workspaces’ outputs or state, or download modules from your private module registry. Because they can’t see current state, they show every resource as new: use them to validate the configuration, and review the real change in the plan for the merged commit.

To let pull-request plans read your cloud, create a Speculative plan version on a credential profile, give its cloud role read-only permissions, and select it on the Source tab.

Every run is pinned to an exact commit; the run page shows the commit SHA and working directory.

GitHub checks

Each run adds one check to its commit and updates it as the run progresses. Each workspace reports its own check, named StackShip / <cloud workspace name> — for example, StackShip / network-foundation. When several workspaces watch the same repository, a commit gets one check per workspace, so one workspace’s result never hides another’s.

To block merges until plans pass, add each workspace’s check name, such as StackShip / network-foundation, as a required status check in your GitHub branch protection rules or rulesets.

A plan-and-apply run’s check shows Plan succeeded while the run waits for approval, then returns to In progress when the apply starts. Only Apply succeeded means the change was applied. A failed check for an interrupted apply means the run needs recovery.

Select Details on the check to open the run in StackShip.

Pull request comments

StackShip posts one comment on each pull request that starts a run, then edits that same comment as plans progress. It never posts a second comment for a later push.

The comment covers every workspace the pull request’s newest commit triggered. In a monorepo where several workspaces watch the same repository, each workspace gets its own row. Workspaces whose trigger paths didn’t match any changed file aren’t listed.

Under the table, each workspace with changes has a collapsed section that lists every planned change by resource address, using OpenTofu’s symbols: + create, ~ update, - destroy, and -/+ replace. The comment shows resource addresses only, never attribute values, so anyone who can read the pull request can read the comment. Open the run for the full plan, including attribute changes.

Each section lists up to 100 changes. If a plan has more, or the comment would pass GitHub’s size limit, the comment links to the run for the full list.

When you push a new commit, the comment switches to that commit and shows its runs. If someone deletes the comment, StackShip posts a new one at the next status change.

Limits

Archives with symbolic links, absolute paths, or .. entries are rejected.

Troubleshooting

If installing the App fails, Get started shows the reason, for example that your GitHub account can’t access the installation or that the connection request expired. Check that you authorized StackShip when GitHub asked and that your GitHub account can access the installation, then select Install GitHub App again. Each attempt can be completed only once, and only by the StackShip user who started it.

If a push or pull request doesn’t start a run, check that:

1. the GitHub App still has access to the repository and isn’t suspended — if it’s suspended, reinstate it in GitHub;
2. the push branch, or the pull request’s base branch, exactly matches the tracked branch;
3. at least one changed file matches a trigger path; and
4. the workspace has a supported OpenTofu version and verified credentials.

If the check shows Neutral, the run is waiting for credentials. Open the run and follow the link to set up or verify a credential profile.

If a pull request gets checks but no plan comment, an organization owner needs to accept the App’s Pull requests: Write permission: in the GitHub organization’s Settings > GitHub Apps, open StackShip and review the permission request.

Next steps

• Workspaces
• Run lifecycle
• Variables and secrets
• Policy sets