Git sources and repositories

A service built from source needs three things the platform keeps apart on purpose: an application that lets TurboPanel talk to a provider, a repository the organization has told the platform about, and the binding in the compose document that says which service builds from it. This chapter covers Projects → Git sources (applications and their installations), Projects → Repositories (the ledger of repositories), the x-turbopanel.source binding, and push-to-deploy.

The model

Three rules:

1. An installation belongs to one organization. Connecting a GitHub installation binds it to the organization that completed the install; another organization cannot claim it (installation_claimed_by_another_organization). Since 2026-09-17 the callback also requires the authorizing GitHub user to be able to see the installation, so an installation id cannot be guessed.
2. The provider is never trusted with a guess. A self-managed GitHub Enterprise or GitLab URL must be https, carry no credentials, name no reserved host, and resolve to a public address (forge_url_rejected) — it is fetched with the application's credentials, so an internal address would turn the control plane into a proxy.
3. Webhooks need a public URL. Push-to-deploy works when the provider can reach the control plane at /webhook/github or /webhook/gitlab. On a LAN-only control plane the application's page says so and the alternative is a manual deploy.

Before you begin

• Manage rights on the organization.
• For GitHub: a GitHub account (personal or organization) you can install Apps on.
• For GitLab: an OAuth application on the GitLab instance with the callback the app shows you.
• For push-to-deploy: the control plane's public URL configured (Admin → Access → Hostnames on self-hosted).

Connect GitHub

Register an existing one (next to Create a GitHub App) takes an existing App's id, private key and secrets instead of the manifest flow — for an App you already own, or on GitHub Enterprise (give its base URL).

Connect GitLab

Bind a repository to a service

The same picker serves the create wizard's Repository card, which is the fastest way from a repository to a running service.

Plain git (deploy keys)

A repository the providers do not host — or one you would rather not connect an application for — can be added by URL. An https URL with no credentials is read anonymously; an SSH URL needs a deploy key (source_ssh_requires_credential), which the platform generates and shows you once to add on the repository. Plain git repositories are read through a connected server rather than the provider's API, cannot be refreshed (source_refresh_not_supported), and never deploy on push.

Push-to-deploy

Two things decide whether a push deploys, and they are kept apart: the repository says whether pushes are allowed at all, and each environment says which branch it builds.

Each repository row carries Auto-deploy:

One branch per environment

An environment builds the branch its services name (x-turbopanel.source.branch), or the repository's default branch when none is named. Because an environment's own compose is laid over the project's, one project can build different branches in different environments from the same repository: production builds main, staging builds staging. A push to staging deploys only staging; production is left alone.

To give an environment its own branch, open it and use its Git branch panel: for each Git-bound service it shows the branch that environment builds and where it came from (this environment, the project, or the repository's default), a Branch for this environment field, and Follow the project to remove the override. The panel saves a small override in the environment's own compose; it does not copy the service. A service that runs a plain image cannot be overridden this way — change it in the compose editor.

Deploy on push (in the same panel, and in the service's Source section) turns push deploys off for that service. The environment can still be deployed by hand; only the push is ignored. If the repository's own Auto-deploy is disabled, the app says so and offers to turn it on, because until it is on no push deploys anything.

Matching is exact: branch names are case-sensitive, refs/heads/staging and staging are the same branch, and tags and other references are never branches. A service with no branch of its own and a repository with no recorded default branch is never deployed by a push — name a branch.

What a push-triggered deploy looks like

The deploy goes through the same path as an app deploy, as the system, and is recorded in the environment's Deployment history as Push to <branch> with the short commit it built. Several services of one repository on different branches in one environment each build their own branch's commit.

A push that cannot deploy is answered and dropped, not retried: no environment builds that branch, the environment has no server, the branch was deleted, push deploys are off for it, or the deploy pipeline refused it for a reason a retry would not fix (the same refusals an app deploy gets — see Deploying). Only a control plane-side failure makes the provider redeliver.

With checks_passed, a repository parks one commit at a time, so when several environments build different branches a newer push to another branch replaces a parked commit that has not yet seen its checks pass.

The webhook URL on each application's page carries that application's routing reference (/webhook/github/<ref> on self-managed providers), so a delivery names its application before any secret is checked; a delivery whose signature does not match is refused.

Repositories — the ledger

Projects → Repositories lists every repository row: its provider, its Access (connection, deploy key or anonymous), the tracked branch, whether the provider's default branch has drifted from it, its auto-deploy mode, and the projects using it. Refresh re-reads the default branch and last commit through the provider. Delete works only for a repository no compose document references (source_referenced_by_compose).

Reference

Errors

Related

• Writing compose — the x-turbopanel.source block and releases.
• Deploying and running an environment — what a push-triggered deploy goes through.
• Accounts and access — signing in with GitHub or Google, which is separate from connecting a repository.
• Security — the operator's view of the installation and URL rules.