---
title: "Deploy from GitHub, GitLab or git: the while.sh docs"
url: https://while.sh/en/docs/building-blocks/git/
updated: 2026-11-21
---

# Git repository

Your code stays on GitHub or GitLab, or lives in the app's git repository at while. Every push deploys: the main branch to production, a pull or merge request or another branch to a preview.

> You, to your AI: Link the app to our GitHub repository, so we deploy on every push.

## When to use it

Use it to deploy on every push, with nothing else to run: from your GitHub or GitLab repository, which stays your main one, or from the app's git repository at while.

## How it works

Your code can stay on GitHub or GitLab. A person links the repository in the app's settings (Code and budget › Link a repository), or your agent does with `link_git_repo { forge, repo, token }`. The forge token reads the repository, sets statuses, comments and manages webhooks: on GitLab, the “api” scope; on GitHub, a fine-grained token with Contents read, and Commit statuses, Pull requests and Webhooks write. It goes to while's vault. A self-hosted GitLab is given with `base_url`.

Once the repository is linked, a push to its default branch deploys production, and other branches deploy nothing. Each pull or merge request opens a preview (pr-\<n> on GitHub, mr-\<n> on GitLab), whose address while posts as a comment, and which closing the request destroys. Each build sets its status on the commit.

If deployment has to stay in your CI, such as GitHub Actions, your workflow deploys the app with a project token. A person creates it in while, Agents page › Create a token for a CI (the app, “Deploy and read”, “Production only”); an agent connected with a token creates it with `create_token { project, name, environments: ["production"] }`. Keep it in the repository's secrets, as `WHILE_TOKEN`. After `actions/checkout`, a step sends the sources, here for the planning project:

```bash titre="The CI step"
tar -czf - --exclude=.git . | curl -sS --fail-with-body -X POST \
  -H "Authorization: Bearer $WHILE_TOKEN" \
  -H 'content-type: application/gzip' \
  --data-binary @- \
  https://app.while.sh/v1/projects/planning/environments/production/deploy
```

A CI that builds its own image sends it to the same address, as JSON: `{ image, digest }`.

Each project also has its own git repository at while, at `https://app.while.sh/git/<project>.git`, which the app's settings also give. A while token is its password; an agent connected through OAuth asks `get_git_credentials` for a credential valid for one hour. A push to `main` deploys production, and a push to another branch creates a preview.

## What to know

A request from a fork waits for a person of the project to authorize each commit in while, and receives no secret of the project.

Unlinking, with the button in the settings or with `link_git_repo { unlink: true }`, removes the link and its webhook.

## Your agent's MCP tools

Your agent handles it with the `link_git_repo`, `create_token` and `get_git_credentials` tools.

## Guides

- [See every new version before production, like a staging environment (2026)](/en/guides/preview-environments/)
- [Keep GitHub or GitLab as your main repository, and deploy on every push (2026)](/en/guides/keep-github-gitlab/)
