Git
Last updated on November 19, 2026
You connect a repo to a Procedure once. From that point on, every push to a tracked branch produces a Deployment, and pushes to the production branch push to every Station bound to that branch.
Supported providers
TofuPilot integrates natively with the providers below. For everything else, deploy through the CLI or the REST API.
| Provider | Authentication | Webhook scope |
|---|---|---|
| GitHub (Free, Team, Enterprise Cloud) | GitHub App | App-level |
| GitLab (Free, Premium, Ultimate) | Group or project access token | Group or project |
| GitLab Self-Managed | Group or project access token | Group or project |
| Bitbucket Data Center / Server | Project HTTP access token | Repository |
Bitbucket support covers Data Center / Server (self-hosted) instances only. Bitbucket Cloud (bitbucket.org) is not supported yet.
Connect a repository
Follow the steps below to wire a repository to a procedure.
Open the procedure and go to Settings > Repository.
Pick GitHub, GitLab, or Bitbucket. For GitHub, install the TofuPilot GitHub App on the account or organization. For GitLab, paste a group access token (preferred) or a personal access token with api and read_repository scopes. For Bitbucket, enter your Data Center instance URL and a project-scoped HTTP access token with Project admin permission, then select the project.
Connecting a provider requires the Admin or Owner role in TofuPilot. Once a provider is connected, Developers can link repositories and deploy. See access roles.
Select the repository. TofuPilot registers the webhook automatically.
Pick the production branch. Pushes to this branch produce production deployments, and pushes to every other branch produce preview deployments.
Save. The next push to any tracked branch triggers a build.
Production branch
A production Deployment is created each time a commit lands on the production branch. The default is main, and you can change it under Settings > Repository > Production branch.
Switching the production branch only affects future pushes. Existing deployments keep their original environment label.
Preview branches
Every non-production branch is a preview branch. Pushes to these branches produce preview deployments with their own ID, and preview deployments do not auto-promote to production.
Private repositories
You can connect private repositories from every provider:
- GitHub: install the TofuPilot GitHub App with access to the repo. Authentication uses short-lived installation tokens.
- GitLab: generate a Group Access Token scoped to the group. The token is encrypted at rest.
- Bitbucket Data Center: generate a project-scoped HTTP access token with Project admin permission (required to register repository webhooks). The token is encrypted at rest.
When a push arrives, TofuPilot looks for a member of your organization in this order: the Git account of the person who pushed (linked to their TofuPilot account), then the Git username of the commit author, then the commit author's email. If none of them is a member with deploy permissions (Owner, Admin, or Developer), the push is recorded as skipped and nothing is built.
Git submodules
TofuPilot fetches the procedure repository's submodules at every build, nested ones included. Use them to share code across procedures, such as a plug library kept in its own repository. Add one from the procedure repository, then commit and push:
git submodule add https://github.com/your-org/plugs.git plugs- URL: HTTPS, relative, or SSH (
git@github.com:your-org/plugs.git). SSH URLs are fetched over HTTPS, so no SSH key is needed. - Access: a private submodule on the procedure's host is read with the same integration. On GitHub, add its repository to the TofuPilot GitHub App installation. On GitLab and Bitbucket, the integration token must be able to read it. A submodule on another host must be public.
- Commit: the commit the procedure repository points to must be pushed.
Anyone who can push to the procedure repository chooses its submodules among the repositories the integration can read. Grant the integration only what your procedures need.
If a submodule cannot be fetched, the build fails and its log says which one and why.
Forks of public repositories
Pushes to a fork do not deploy automatically. An Admin or Owner authorizes the deployment from the procedure's Deployments page, and authorization is per-PR. Once a PR is authorized, subsequent pushes to the same PR build automatically.
Re-running a failed deployment
A build that fails because of the build service is retried automatically. When a build fails because of the procedure, fix it and push again, or click Redeploy in the failed deployment's row menu. Redeploy builds the same commit as a new deployment, in the same environment.
Detaching a repository
When you want to remove the integration, follow these steps:
- Open Settings > Repository.
- Click Disconnect repository.
The webhook is removed, while existing deployments are preserved and stay pinned to their stations.
How is this guide?
Deployments
Learn how TofuPilot deployments build a procedure version from Git and ship it to one or many factory stations with status, environment, and trigger metadata.
Environments
Learn how TofuPilot tags every deployment with production, preview, or development so you can ship safely from laptop to factory.