---
title: "Deploy from GitHub or GitLab on every push, with while.sh"
url: https://while.sh/en/guides/keep-github-gitlab/
author: "Aloïs Oddon, co-founder of Nextmap"
updated: 2026-11-16
---

# Keep GitHub or GitLab as your main repository, and deploy on every push

Your code stays on GitHub or GitLab. A push to the default branch puts production online, every merge request opens a preview whose address arrives as a comment, and every commit gets its status.

## Prerequisites

- An app on while.
- Its repository on GitHub or GitLab, and the right to create an access token there.

## Step 1: Create an access token

On GitHub, create a fine-grained token limited to this repository. Give it Contents read access, and Webhooks, Commit statuses and Pull requests write access.

On GitLab, create a token with the `api` scope. Your account needs the Maintainer role on the project.

## Step 2: Link the repository

In while, open the app settings, go to the Code and budget section, then click Link a repository. Choose GitHub or GitLab, and paste the repository and the token. The repository is written `atelier/boutique`, or pasted as you copy it from GitHub or GitLab.

Your agent can also link it, with the `link_git_repo` tool:

> You, to your agent: Link the app to our GitHub repository atelier/boutique.

It links it with the token you give it. With ChatGPT and Codex, the token does not go through the agent: it gives you the link to the while form, where you paste it.

## What happens on every push

A push to the default branch of the repository, usually `main`, puts production online. Another branch leaves it alone.

A merge request opens a preview, `pr-12` on GitHub or `mr-12` on GitLab, built from its latest commit. Its address arrives as a comment on the request as soon as it responds, and the preview is removed when the request is closed or merged.

Every commit gets its status on GitHub or GitLab: building, online or failed, with the link to the app.

When a deployment must be approved by a person, the commit status says so, with the link to the request. Once approved, it goes out on its own.

A merge request from a fork is not built on its own. A person on the project who can deploy authorizes each commit in while, and the preview receives none of the project's secrets.

## Unlink the repository

In the app settings, Unlink removes the webhook on GitHub or GitLab and erases the token from while. A push no longer puts the app online.

> You, to your agent: Unlink the app's GitHub repository.

## The other way: push from GitHub Actions

If you prefer to keep deployment in your CI, your workflow pushes the code to the app's git repository at while, with a token limited to this app.

In while, open the Agents page and click Create a token for a CI. Choose the app, "Deploy and read", and production as the only place where it acts. Copy it: it is shown only once.

In GitHub, add it to the repository secrets as `WHILE_TOKEN`, then add this workflow:

```yaml titre=".github/workflows/while.yml"
name: while
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: git push "https://while:${WHILE_TOKEN}@app.while.sh/git/boutique.git" HEAD:main
        env:
          WHILE_TOKEN: ${{ secrets.WHILE_TOKEN }}
```

Replace the address with your app's, which its settings give on the Git repository line. A push to `main` at while puts production online. The workflow fetches the whole history of the repository: git refuses to push a clone without its history to another repository.

## Next steps

- [See every new version before production](/en/guides/preview-environments/)
- [The git repository of every app](/en/docs/building-blocks/git/)

## Questions

### Do I still need to push to the while git repository?

No. Once the repository is linked, a push to GitHub or GitLab is enough.

### What happens to the token?

It is kept in the while vault. It is never shown again, neither in while nor to your agent.

### I link another repository. What happens to the first one?

It is unlinked, and its webhook is removed. Only the new repository puts the app online.

### Our GitLab is self-hosted. Does it work?

Yes, like a GitHub Enterprise. Paste the repository address, and the forge is recognized from it.
