Source control

Nautvia deploys from GitHub or GitLab. The connection is made once per team, under Source control, and only the team owner can make or remove it.

The GitLab connection is for gitlab.com. For a self-hosted GitLab, Gitea or any other git server, use Custom Git instead.

What access is requested

Provider	Scopes
GitHub	repo, admin:repo_hook
GitLab	api

repo is needed to download the commit you are deploying; admin:repo_hook is what lets Nautvia register the webhook that makes push-to-deploy work.

A provider only appears as an option if it has been configured on the platform side. If neither is available, the create-site page says so instead of offering a dead button.

How your code is fetched

Nautvia does not git clone. It downloads a tarball of the exact commit from the provider's API and unpacks it into a new release directory. There is no .git directory on the server, and nothing on the server can push back to your repository.

The token is passed to curl through a file readable only by the deploy user, and deleted when the build finishes.

Push to deploy

Creating a site registers a webhook on the repository. Pushes to the environment's branch then deploy automatically.

Nautvia verifies every delivery — GitHub's X-Hub-Signature-256 HMAC or GitLab's secret token — and ignores anything that is not a push to that branch: tag pushes, branch deletions and other event types are dropped.

If a push arrives while a deploy is running, it is remembered and starts when the current one finishes. Only the newest is kept: three pushes during one deploy result in one further deploy, of the last commit. This is deliberate — deploying every intermediate commit in sequence wastes minutes for a result nobody wanted.

Webhook registration is best-effort. If it fails — usually because the token lacks hook permission — the site is still created and deploys still work from the dashboard; only automatic deploys are missing.

Disconnecting

Removing a provider under Source control does not remove webhooks from your repositories, and does not disable your sites. What it does is break the next deploy of any site that used it, with "The site has no connected git provider."

Reconnecting fixes it. Delete the stale webhook in your repository settings yourself.

When a token expires

GitLab tokens expire after two hours. Nautvia refreshes them itself, shortly before they run out, so a deploy never starts with an expired one.

What still needs you: if access is revoked — the authorization removed in GitLab, or the account locked out — the refresh is refused. Deploys and the repository picker then say to reconnect GitLab under Source control.

GitHub tokens do not expire. If you revoke access there, two things break:

• the repository picker on the create-site page shows an error with a Retry button;
• builds fail while downloading the tarball.

In both cases, disconnect and reconnect the provider.

Custom Git (self-hosted servers)

Any git server that accepts SSH works: self-hosted GitLab, Gitea, Forgejo, Bitbucket Server, a plain git server. There is no provider account to connect — on the create-site page choose Deploy over SSH with a deploy key and enter the repository's SSH clone URL, for example [email protected]:group/shop.git or ssh://[email protected]:2222/group/shop.git.

After the site is created, its environment settings (Repository) show two things to add to the repository yourself:

1. The deploy key. Add it with read-only access (GitLab: Settings → Repository → Deploy keys). Each site has its own key; nothing else can use it.
2. The push webhook. Add the URL and the secret (GitLab: Settings → Webhooks, secret token, push events; Gitea and other GitHub-compatible servers: webhook secret, content type JSON).

How it differs from a connected provider:

• The app server clones the repository over SSH instead of downloading a tarball, then removes .git — a release looks the same either way. Your git server must accept SSH connections from the internet. Its host key is trusted the first time and checked on every later deploy.
• The branch head is resolved on the server. A deploy started from the dashboard builds the latest commit of the branch and records which one it was; a push deploys the exact commit it names.
• There is no repository picker, and nothing is registered for you: remove the deploy key and the webhook from the repository yourself when you delete the site.

Private repositories and monorepos

Private repositories work — that is what the token is for. Monorepos are not supported: the tarball is unpacked at its root and Magento is expected to be there. There is no subdirectory setting.