Skip to content

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.

By Aloïs Oddon, co-founder of Nextmap. Facts checked on November 16, 2026.

View as Markdown

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.

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.

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:

.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.

In the docs: Git repository, Previews and Variables and secrets.

Next steps

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.

Connect your agent, it takes care of the rest

To paste into your agent

Read while.sh/agents, then deploy my app with while.

Copy the instructions

No account needed to try: your app is live right away. To keep it, sign in.

A project for your company? Talk to the team: hello@while.sh