Git providers

The Git providers page (Advanced → /connect/git) is where you connect a Git host — GitHub, GitLab or Bitbucket — to your MZPanel account. Once connected, per-site deployments and Docker apps can clone and build straight from your repositories, including private ones. It’s an account-level integration, so you connect a provider once and every server in the account can use it. Managing connections needs the integrations capability (the owner or a team member granted it); anyone in the infra group can browse the connected repos.

Connect a provider, step by step

1. Click Connect Git provider (top right) — or pick a tile under Add a Git account — to open the connect drawer.
2. Choose the Provider: GitHub, GitLab or Bitbucket.
3. GitHub, one-click (recommended, when available): if the GitHub App is configured on your control plane, click Install GitHub App. You’re redirected to GitHub to pick exactly which repositories to grant — no token to create or paste. When you come back, the connection is listed and its repos are ready.
4. Any provider, with a token: paste a read-scoped Personal Access Token. The drawer shows exactly where to create it per provider — for example GitHub’s Settings → Developer settings → Personal access tokens with the repo (read) scope. Bitbucket also needs your username / workspace (it uses an App password).
5. Click Verify & connect. MZPanel checks the token against the provider before saving, detects the account name and visible scopes, then stores the token encrypted. The connection appears under Connected accounts with its status dot, method badge, scopes and a count of visible repositories.

Use a read-only token

Deployments only ever read your code. A token scoped to repo read (plus webhooks, if you want auto-deploy) is all MZPanel needs — never grant write or admin scopes.

What else you can do

• Manage a connection — open the Manage drawer on any connected account to browse its repositories (name, public/private, default branch, last push) and search across them.
• Re-verify — inside Manage, click Re-verify to re-check the token against the provider and refresh the cached repo list. If a token was revoked upstream, the connection flips to Auth failed.
• Configure on GitHub — for GitHub App connections, a shortcut jumps to GitHub’s Installed Apps to add or remove which repos are shared.
• Revoke — remove a connection. For a token connection the stored token is deleted from the control plane; for a GitHub App you also uninstall the App on GitHub for a full revoke. Apps already built keep their code; only future builds from that account stop.

How it works

Everything on this page runs control-plane → provider — your VPS is never involved, and the token never leaves the control plane:

Action	API route	What happens
List connections	GET /v1/git/connections	returns masked records (never the token)
Connect (token)	POST /v1/git/connections	verifies the PAT, encrypts it, caches the repo list
Re-verify / refresh	POST /v1/git/connections/:id/verify	re-checks + refreshes the cache
Browse repos	GET /v1/git/connections/:id/repos	serves the cache (?refresh=1 goes live)
Revoke	DELETE /v1/git/connections/:id	deletes the connection
GitHub App install	GET /v1/git/github-app/install-url → GitHub → …/github-app/callback	signed round-trip, stores the installation

The token is encrypted at rest with AES-256-GCM and only the last four characters are ever shown. Connections live in the control-plane database (git_connections), scoped to your organization. When a per-site deployment or a Docker app builds from a private repo, the build reuses the stored token (or mints a short-lived GitHub App token) to clone the code — you don’t paste it again.

API & automation

Git connections are a control-plane resource, so the on-box mz CLI does not manage them. On the Max plan you can drive them over the account API instead — for example listing connections and browsing a connection’s repos:

GET  /v1/git/connections
GET  /v1/git/connections/:id/repos
POST /v1/git/connections           # verify + store a token

See the API reference for authentication and the full endpoint list.

Gotchas & troubleshooting

• This page only connects the account — it doesn’t deploy anything. Choosing which repo and branch a site deploys from is configured per-site under Sites → Deployments; Docker apps pick a connected repo when you create them. The repo browser here is read-only.
• GitHub App vs. token. The one-click GitHub App is only offered when the App is configured on your control plane. Until then, a read-scoped PAT does the same job. OAuth sign-in for GitLab/Bitbucket is shown as “coming soon” — use a token today.
• “Auth failed” status. The provider rejected the stored token — it was revoked, expired, or lost the needed scope. Open Manage → Re-verify; if it still fails, revoke and reconnect with a fresh token.
• No repos visible? A token only sees what its scope allows. For a fine-grained GitHub token, make sure the target repositories (or org) are selected; for a GitHub App, use Configure on GitHub to grant the missing repos, then Re-verify.
• Encryption must be configured. If the control plane has no encryption secret set, connecting returns a “not configured” error — contact your administrator (this only affects self-hosted control planes).

Related

• Docker apps & stacks — build an app straight from a connected repo.
• Staging & deploy — per-site push-to-live workflow.
• Team & roles — who can manage integrations.
• API reference — automate connections on the Max plan.