Skip to content

Git Tokens (Dev & Non-Dev App Servers)

Muppy clones your application's git repository onto every App Server it provisions, and re-clones/pulls on each (re)deploy. This guide explains how the git credentials work, and what token to create depending on the kind of server.

There are two models, picked automatically by the qualifier of the server:

Server kind Credential model Token on the box? Can push?
Dev (Development) Muppy git credential helper No — resolved on demand Yes, via an explicit, approved session
Non-dev (Test / Staging / Prod) Embedded deploy token Yes — read-only token on disk No (read-only)

The guiding principle: a push (write) can poison the repository and propagate to CI/prod, so write access is tightly controlled; a read is low value (the code is already checked out on the box).

1. The building block: a Muppy git token (vault)

A git credential is stored in Muppy as a Vault record (Infrastructure → Vaults, type Git PAT):

Field Meaning
Server the git host, e.g. gitlab.com
User the username git authenticates as
Password the token value (PAT or deploy token)
Access level Read-only or Read-write — advisory in Muppy; the git provider enforces the real scope
Default for this server when set, the token is auto-resolved for any repo on that host (host-wide)

Access level is declarative

Muppy honours Access level when serving credentials (a read session is served a read-only token), but it does not verify the token's real scope against GitLab. Set it to match what you created on the provider, and let the provider enforce the truth.

2. How the Create App Server wizard fills the token (auto-resolution)

When you pick an Application Definition and a qualifier, the wizard tries to auto-fill the Git Access Token. What it proposes — or whether it leaves the field empty — follows a few simple rules. This is the most common source of confusion ("the wizard brings back nothing").

The rule: tokens are resolved per owner, by host

Auto-resolution looks for a vault Git PAT matching, in order:

  1. a token owned by the server's Owner (the Owner field — defaults to you), on the repository's host (e.g. gitlab.com), marked Default for this server;
  2. failing that, a system token — a vault with no owner — on the same host.

Key points:

  • Matching is on host + provider + owner, not on the repository path. So gitlab.com/teamA/repo and gitlab.com/teamB/repo resolve to the same token for a given owner.
  • If neither a token of yours nor a system token exists for that host, the field stays empty — this is expected, not an error. Pick/enter one manually, or create one (see §5).

« The wizard brings back nothing »

The most frequent cause: the only tokens for that host belong to another user. A vault Git PAT has an owner, and auto-resolution only sees your own tokens (plus owner-less system tokens). If you are logged in as a different user than the token's owner, nothing auto-fills — by design. Fix it by creating your own token, or by declaring a system token (leave Owner empty) as a shared fallback for everyone on that host.

What changes per server kind

  • Dev → the box uses the helper (§3), so the wizard embeds no token at all: the field is hidden, replaced by an info banner showing the read-only token the helper will use. An empty/hidden token field is normal for dev.

    Empty qualifier ⇒ treated as dev

    The wizard has no default qualifier; until you pick one it assumes dev. So right after selecting an App Definition the token field is hidden (helper mode). Pick a non-dev qualifier to switch to an embedded token.

  • Non-dev (Test / Staging / Prod) → the wizard pre-fills the App Definition's per-category deploy token (the Test/Staging/Prod default repository token) when set; otherwise it falls back to the per-owner host resolution above. The field is shown and you can override it.

3. Dev servers — the credential helper (no token on the box)

A Dev App Server never stores a token on disk. Instead, the git-credential-muppy helper is installed; on each git operation it calls Muppy, which resolves the token on demand and hands it to git. Nothing is written to disk.

What you create (once, as the server owner)

Create your personal access tokens in GitLab and store them as vaults:

  • a read-only PAT → vault with Access level = Read-only;
  • a read-write PAT → vault with Access level = Read-write.

Mark them Default for this server (host-wide) so the helper resolves them.

The session scope then selects which one is served:

  • read session → your read-only PAT (clone / fetch / pull);
  • read+write session → your read-write PAT (push).

Reading vs pushing on a Dev box

  • Read (clone/pull) works through a short, auto-approved session opened at provisioning, and any session you open later.
  • Push requires an explicit, human-approved session. On the box:
muppy-git-login <your-muppy-username>      # opens a write session (approve it in Muppy)
muppy-git-login <your-muppy-username> 5m   # optional duration: 5m, 2h, or a bare number = hours
git push                                   # now allowed, for the session's lifetime
muppy-git-logout                           # close the session
muppy-git-status                           # show the current session, scope, expiry

When you have no active write session, git push does not prompt — it prints how to open one (muppy-git-login). No token ever lands on disk.

Provisioning the box

At creation, Muppy auto-approves a short read grant (the owner's read-only token) so the first clone — and the build, which fetches dependency add-ons — can authenticate. The owner therefore needs a read-only PAT for the host.

Session lifetimes & login timeouts

How long a session lasts, how long you have to approve a login, and how long muppy-git-login waits before giving up are all configurable — see Git Credential Settings. In particular: a login that times out before you approve leaves no session — re-run muppy-git-login; the next git command does not pick up the approval on its own.

4. Non-dev servers — an embedded read-only deploy token

A Test / Staging / Prod App Server is usually unattended (it pulls to deploy with no human present), so it uses a deploy token embedded in the remote URL. The deploy token is read-only so a compromised box cannot push.

What you create

  1. In GitLab, create a Deploy Token (not a personal token): Project (or Group) → Settings → Repository → Deploy tokens → scope read_repository. GitLab gives you a username (e.g. gitlab+deploy-token-42, or a custom one) and a token value.

    Project vs Group deploy token

    A build pulls the app repo plus its submodules and ikb dependency add-ons — often several private repos. A project deploy token covers one repo; if the dependencies live in the same group, create a group deploy token so it covers them all.

  2. Store it as a Muppy vault (type Git PAT):

    • Server = gitlab.com
    • User = the deploy token username (e.g. gitlab+deploy-token-42) — not your login; an empty user falls back to oauth2 and GitLab refuses it.
    • Password = the deploy token value
    • Access level = Read-only

  3. Assign it on the Application Definition, per category: the Test / Staging / Prod default repository token field. Servers duplicated from that App Definition embed it automatically.

Why read-only

The token is written to the box's git remote URL. A read-write token there could push and poison the repo if the box is compromised. The create-server wizard shows a red warning when the selected deploy token is read-write — use a read-only one.

Rotation

Deploy tokens can expire. When they do, update the vault's Password (and expiry) with a freshly minted deploy token; re-provision (or re-deploy) picks it up.

5. Creating the tokens on GitLab — quick reference

Personal Access Token (dev — your own identity): Profile → Preferences → Access Tokens → scopes: read_repository (RO PAT) or read_repository + write_repository (RW PAT).

Deploy Token (non-dev — repo/group, no human identity): Project/Group → Settings → Repository → Deploy tokens → scope read_repository.

Personal Access Token Deploy Token
Tied to a user a project / group
Used for Dev (helper, owner identity) Non-dev (embedded deploy)
Muppy Access level ro and rw (two PATs) ro only
Muppy User your git username the deploy-token username

6. Roadmap

  • Per-push write approval — every repository alteration gated by a human permission toast (the highest-security write model).
  • OAuth minting — instead of stored tokens, Muppy mints short-lived, repo-scoped tokens on demand (read for non-dev deploys, one-shot write per approved push), so no long-lived token is stored anywhere.

See the gitlab_integration spec for the design.