Git providers

A git connection lets KamalCloud list your repositories and branches, clone them on the runner, and hear about pushes. An account can hold several, including several to the same host.

Each connection is your own credential – your GitHub App installation, your GitLab application, your Bitbucket token. KamalCloud does not proxy your code through a shared account.

GitHub

GitHub is a two-step dance, and both steps are KamalCloud’s own pages:

1. Register — KamalCloud creates a GitHub App under your user or organisation, with the permissions it needs and no more.
2. Install — you install that app on the repositories it should see. All of them, or a list you pick.

Afterwards the connection knows its installation and can clone, list and receive webhooks. Add or remove repositories later from GitHub’s own installation settings.

GitLab

GitLab authorises rather than installs. First create an OAuth application on the instance – gitlab.com or your own – and paste its application ID and secret into KamalCloud. KamalCloud then sends your browser to the instance to approve it, and the instance sends it back with a code. Self-hosted GitLab is supported; give KamalCloud the instance URL.

Gitea

Gitea authorises the same way GitLab does: create an OAuth2 application on the instance, paste its client ID and secret, then approve. Gitea is almost always self-hosted, so the instance URL is part of connecting.

Bitbucket

Bitbucket takes a token rather than a handshake. Give KamalCloud your username, your Atlassian account email, an Atlassian API token and the workspace. KamalCloud checks them by listing the workspace once. A connection made with an older app password still works.

Repositories and branches

Once connected, the app form’s source picker reads repositories and branches straight from the host. Private repositories work: the clone URL KamalCloud builds on the runner carries a token, which is why the deploy log names the clone rather than printing the URL, and why origin is reset immediately after.

Push to deploy

Each connection registers a webhook. When a push arrives, KamalCloud looks for environments that should act on it. An environment deploys from a push only if all of these are true:

• Auto-deploy is switched on for that environment. It is off by default – a branch matching by coincidence should never ship to production on its own.
• The push matches the trigger. push means the ref is that environment’s branch; tag means any tag, because which tags matter is a question about the repository, not about one environment.
• The changed paths match the environment’s path patterns, if it has any. This is how a monorepo deploys one app and not the other four.
• No deployment is already active for that environment. A push mid-deploy waits rather than racing: KamalCloud tries again every 30 seconds, up to 20 times.

Some pushes are ignored before any of that. A push that deletes a branch, or that carries no commits, has nothing new to ship. A commit message with a skip marker – [skip ci], [ci skip], [no ci], [skip actions] or [actions skip] – is skipped too.

A deployment created this way records the push rather than a person, and writes the commit at the moment it is created – so the row stays truthful even if another push lands while it waits.

Disconnecting

Disconnecting a git connection forgets the source. The app and its servers stay exactly as they are, and what is deployed keeps running. You will not be able to deploy again until the app names a source it can reach.