Skip to content

Managing GitLab Tokens for Muppy

New here? Git workflows in Muppy explains the model in one page — why it works this way, and which tokens to create.

This page is the GitLab-specific companion to Git Tokens (Dev & Non-Dev).

The GitLab workflow
Can Muppy cancel an authorization here? Yes. Press Disconnect and the grant is really gone from GitLab — nothing is left for you to do.
Can a token describe itself? A classic PAT can. A fine-grained one cannot: GitLab offers it no self-description endpoint, so Muppy reads it through your connection.
Do tokens expire? Yes, always — GitLab requires an expiry date. Muppy records it and reports the token as Expired when the day comes.
The trap Code: Read is not what git clone needs. It needs Code: Download, and the difference surfaces as a 403 at clone time rather than as an error you can read.

GitLab is the provider this model was built against, so it is also the one with the fewest surprises: revocation works, expiry is mandatory, and Muppy can tell you what every token really is. What is left to get right is which checkbox, which is the whole of the rest of this page.

Creating the tokens

Pick the section that matches what you are setting up (cf. the model table in Git Tokens):

You need... Section
A personal token for a Dev box (helper), read-only Fine-grained PAT — read-only, repo-scoped
A personal token for a Dev box (helper), read-write (push sessions) Classic PAT
An embedded token for a Non-dev (Test/Staging/Prod) box Deploy Token

Fine-grained PAT — read-only, repo-scoped

GitLab's current default token type ("Fine-grained personal access token") scopes a token to one or a few specific projects instead of your whole account — this is exactly what Muppy's vault Token scope = Repo-scoped expects, and it is what makes a Dev helper box's reads free of an approval window (a repo-scoped token is already contained, cf. Git Tokens §2).

  1. On gitlab.com: Avatar → Edit profile → Access Tokens → Add new token.
  2. Give it a name (e.g. appserver-m3-ro) and set an expiry date — GitLab requires one.
  3. Under Group and project access, choose "Only specific group or projects that I'm a member of" and select the single project this token is for.
  4. Under Group and project permissions, expand Repository and check Code: Download.

Code: Read is NOT enough

Code: Read looks like the obvious box to tick, but it only covers browsing code through the API/web UI. git clone / git pull over HTTPS needs Code: Download — a separate permission. A token with only Code: Read authenticates fine (GitLab accepts the credentials) but rejects the actual clone with a 403: "credential valid but has no access to this repository." This is the single most common cause of that error.

  1. Generate the token, then store it in Muppy as a Git PAT vault:
  2. Access level = Read-only
  3. Token scope = Repo-scoped

You do not need the other Repository checkboxes (Protected Tag: Read, Repository Tag: Read, Repository: Read, Branch: Read, Commit: Read, Merge Request: Read) for git itself — only Code: Download. Check them too only if you want this same token to also drive GitLab API calls (browsing, project metadata) outside of git operations; Muppy's git probe and helper never need them.

Full permission reference (git operations)

For completeness — what each git-related action actually requires on a fine-grained token:

Operation Resource Permission
Clone / pull a repository Code Download
Push to a repository Code Push
Download a repository archive Code Download
Download/upload Git LFS objects Code Download / Push
Clone / pull a wiki Wiki Read
Clone / pull a snippet Snippet Read

A read-write PAT for a Dev box's write sessions (cf. Git Tokens §3) needs Code: Push instead of (or in addition to) Download — Push already implies you can pull what you can push, but check Download too if you want the same token usable for both.

Classic PAT (account-wide)

The older token type ("scopes" checkboxes, not the project-picker UI above) is inherently account-wide — it maps to Muppy's Token scope = Account-wide, which means reads from a Dev helper box need an approval window every time (cf. Git Tokens §3). Prefer the fine-grained PAT above unless you specifically want a single token that reaches every repository you can.

  1. Avatar → Edit profile → Access Tokens → Add new token, and if GitLab still offers the classic scope list on your instance, select it instead of the project picker.
  2. Scopes:
  3. read_repository for a read-only PAT.
  4. read_repository + write_repository for a read-write PAT.
  5. Store in Muppy: Access level = Read-only or Read-write to match; Token scope = Account-wide.

Deploy Token (non-dev, embedded)

Used for Test / Staging / Prod App Servers, which embed a standing read-only credential on disk rather than using the helper (cf. Git Tokens §4).

  1. Project (or Group) → Settings → Repository → Deploy tokens → Add token.
  2. Scope: read_repository only (never grant write scopes to an embedded token — a compromised box could push and poison the repository).
  3. GitLab shows you a username (defaults to gitlab+deploy-token-{n}, or a custom one you set) and the token value — copy both, the token value is shown only once.
  4. Store in Muppy as a Git PAT vault:
  5. User = the deploy token's username (exactly as shown — not your personal login; an empty user falls back to oauth2 and GitLab refuses it)
  6. Password = the deploy token value
  7. Access level = Read-only

Project vs Group deploy token

A build pulls the app repo plus its 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 instead so it covers all of them.

What Muppy can and cannot do for you here
Check what a token really is Yes — Introspect token reads the scopes, the project limitation and the expiry from GitLab, and corrects your entry in place.
Cancel a Muppy authorization Yes. Disconnect revokes the grant at GitLab; nothing is left outstanding.

You do not have to get Access level, Token scope, Scope and Expiration right by hand. Once the token value is stored, open the credential (Git → Git Tokens) and click Introspect token: Muppy asks GitLab what the token really is and corrects those fields in place. What GitLab says wins over what was typed — a token declared Read-write that turns out read-only is fixed, not flagged.

It also stamps two read-only fields that only introspection can produce:

Field What it tells you
Token Status What GitLab last confirmed: Active, Expired, Revoked, or Never checked. A revocation has no date, so it cannot be deduced from the expiry — only a check can find it.
Last checked When that answer was obtained.

Your name and description are yours

Introspect never overwrites the credential's Name or Description — those are your labels, and calling a token "prod deploy key" when GitLab calls it "gitlab-token-3" is perfectly legitimate. They are only pre-filled from GitLab when you leave them empty. The GitLab-side values are recorded separately as Provider token name / Provider token description (under Advanced → Muppy Git Provider), so nothing is lost and a rename on either side stays visible.

Fine-grained tokens need a connection

A classic PAT can describe itself, so Introspect works straight away. A fine-grained PAT cannot — GitLab offers it no self-description endpoint — so Muppy reads it through your OAuth connection to the provider instead. If you have none, the button offers to connect first and brings you back here afterwards. If Muppy still cannot tell which of your tokens this is (GitLab never reveals a token's value after creation), use Link Git Token to pick it from the list.

Troubleshooting: "credential valid but has no access to this repository"

Muppy's repository probe (a real git-upload-pack HTTP request, not a guess) reports this exact message when GitLab answers 403 — the credential authenticated, but is denied the specific operation. In order of likelihood:

  1. Fine-grained PAT missing Code: Download — see the warning above; by far the most common cause. Fix: edit or regenerate the token with that permission checked.
  2. Deploy token scoped to the wrong project — double-check which project the deploy token was created under; the name you gave it in GitLab or in Muppy's vault does not have to match the actual project it is scoped to.
  3. Deploy token missing read_repository — deploy tokens have their own scope list (registry, packages, repository); make sure read_repository is checked.

See also