Git repositories

In the dashboard: Settings → Git, or while making a project with New project → Import a repository. Only team owners and admins connect or remove accounts.

• GitHub: you install our app on your account or organization and choose the repositories. An installation belongs to one team only.
• GitLab (gitlab.com): you approve with OAuth.
• Self-hosted GitLab: you give its https address. If this platform has no application for that address, create an OAuth application on your GitLab (scope api, redirect address as shown by the platform) and give its id and secret.

cloudhost git connect github
cloudhost git connect gitlab --url https://git.example.com --application <id>   # the secret on stdin
cloudhost git connections

Make a new project from a repository, or link an existing one. A project has one repository; one repository can build several projects (a monorepo, for example).

cloudhost git repos acme
cloudhost apps git import shop acme acme/shop
cloudhost apps git link docs acme acme/docs --branch release
cloudhost apps git show shop
cloudhost apps git unlink docs

• A push to the production branch (default: the repository's default branch) deploys production.
• A push to any other branch builds a preview at <branch>--<name>, with the preview database branch and variables. You can turn previews off in the project's settings.
• The names main, master and production are always production; when the production branch is another name, a push to those is not built.
• A pull request from a fork is not built, because its code would run with the project's variables.
• Deleting a branch deletes its preview. A commit that is built or building is not built twice.

To build a branch right away, use “Build now” in the project's Git settings, or:

cloudhost apps git deploy shop --branch feature/cart
cloudhost apps builds shop

Every build writes a status on the commit (building, ready, failed) with a link to the deployment page. For a pull request (GitLab: merge request) one comment is written and updated as the build goes; it holds the preview link.

• Git tells us with a signed webhook; the signature (GitHub: HMAC-SHA256, GitLab: a secret token per project) is checked before anything else.
• The repository is cloned inside the build sandbox with a short-lived, read-only token (GitHub: that repository only, about an hour). These tokens are stored nowhere, never reach the build log, and are removed from the build's environment after the clone.
• GitLab cannot narrow a token to one repository; your short-lived access token is used. GitLab's refresh tokens are kept encrypted under the team's key because they must rotate.
• Removing the account (or the app on GitHub) stops automatic builds; earlier deployments stay.