Managing Forgejo / Codeberg 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.

Applies to Codeberg and to any self-hosted Forgejo or Gitea instance: the access-token screens are the same.

The Forgejo workflow¶


Can Muppy cancel an authorization here?	No. Forgejo offers an application no way to cancel its own authorization. You remove it yourself, and Muppy reminds you until you say you have.
Can a token describe itself?	Only an All repositories token carrying `user: Read`. A repo-limited token cannot, and no checkbox changes that — it needs a Muppy connection.
Do tokens expire?	No. A Forgejo access token has no expiry field at all. It lives until you delete it.
The trap	`user: Read` is not a small permission — it lists every token on your account.

Two of those cost you an afternoon if you meet them by surprise, so they get a section each below. The third is quieter and worth stating plainly: a Forgejo token you forget about never lapses. Muppy will never report one as Expired, because there is nothing to expire. It still reports Revoked — a token you delete at Codeberg disappears from your token list, and that absence is how Muppy sees it is gone.

Creating the tokens¶

Avatar → Settings → Applications → Manage Access Tokens → Generate New Token.

Token name — anything; use the box it is for, e.g. appserver-m3-ro.
Repository access — Specific repositories, and pick the one this token is for. This is what Muppy's vault field Token scope = Repo-scoped records, and it is what makes a Dev box's reads free of an approval window: a repo-scoped read-only token is already contained, so Muppy serves it with no session and no prompt.
Select permissions — repository set to Read, or Read and Write if this token will push.
Generate it, copy the value (Forgejo shows it once), and store it in Muppy as a Git PAT vault — Access level Read-only or Read-write, Token scope Repo-scoped.
Press Introspect token on the vault. Muppy asks Codeberg what the token really is and rewrites those two fields from the answer.

A repo-limited token needs a Muppy git connection to be verified

Forgejo restricts a Specific repositories token to four permissions — read:issue, write:issue, read:repository, write:repository — and its own token screen says so. The list Muppy reads to verify a token requires the user permission, which is not among them.

So a repo-limited token cannot describe itself. Introspect token on one goes through your Muppy git connection instead, which reads the list on your behalf. Set that up once (below) and every repo-limited token you own becomes verifiable.

An All repositories token can carry user: Read, and one that does describes itself with no connection involved.

What user: Read actually grants

A token carrying it can list every access token on your account — each one's name, permissions, repositories and last eight characters, including credentials that have nothing to do with Muppy.

That is the endpoint Muppy has to call to verify a token, so the reach is inherent rather than something Muppy chose. It is also the argument for the connection: you grant it once, you can see it listed under Authorized OAuth2 Applications, and no long-lived token in your vault has to carry account-reading power to be verifiable.

Setting up the connection¶

A Muppy git connection to Forgejo is an OAuth link to your account, and it is what makes Introspect token work on a repo-limited token — the tier that cannot describe itself. The connection reads your token list on your behalf, because an OAuth token carries no per-token scope restriction and is therefore allowed where the PAT is not.

You can skip it only if every token you keep in Muppy is All repositories and carries user: Read.

It has one prerequisite Muppy cannot ship for you: an administrator must register an OAuth2 application on the Forgejo instance and put its Client ID and Client Secret on the Git Provider record in Muppy. Until that is done, Connect has nothing to talk to.

Registering it: Settings → Applications → Manage OAuth2 Applications → Create a new OAuth2 Application, with the redirect URI Muppy shows on the Git Provider form.

A Forgejo connection is full-account

Forgejo implements no OAuth2 scopes, so the connection Muppy obtains acts as you, with everything your account can do — Muppy asks for nothing narrower because nothing narrower exists. It never leaves Muppy and never reaches a box; it is used only for provider API calls like the token listing above.

Codeberg tells you this itself, on the screen where you approve it:

If you grant access, it will be able to access and write to all your account information, including private repos and organizations.

With scopes: .

That empty scope list is not a rendering fault — there is nothing to put in it. Read that screen before you press Authorize Application: it is the most accurate description of the grant you will get, and it comes from your provider rather than from us.

Ending a connection: two ways out, and only one leaves you a job¶

This is the part with no equivalent on GitLab, and the part to plan around. On Forgejo, Muppy can never cancel an authorization — it can only let go of its own copy. What differs is whether you asked for it to end.

Muppy lets go on its own — nothing for you to do¶

A connection that sits unused past its keep-alive is released by Muppy: the tokens are purged, and it holds nothing until you connect again. Your authorization at Codeberg is untouched — it has been there since you approved it and stays until you remove it, whatever Muppy does with its cached copy.

So the form says exactly that, as a statement rather than a task: Muppy's access is closed — your authorization at the provider is unaffected. Press Connect and you are back in one click, with nothing to re-approve.

A Closed badge shows how long it has been sitting released — green, then amber, then red over some weeks. That is there so an authorization you have genuinely finished with becomes visible as one, rather than standing at Codeberg unnoticed for a year. It asks nothing of you; it just stops the fact being invisible.

You press Disconnect — now there is a job, and it is yours¶

Disconnect means this is over. Muppy cannot finish it, so it hands you the half it cannot do and keeps the record until you say it is done:

the connection stays in My Git Connections, marked Remove at provider, with a red block naming what is outstanding, since when, and a link straight to the page;
deleting the connection is refused while it stands. Deleting cancels nothing at Codeberg — it would only make Muppy forget, which is the one thing worth keeping;
when you have removed it there, press I removed it. That is what ends it.

Muppy takes your word for it, and the reason is mechanical

When the connection ended, Muppy purged its credentials — the refresh token and the cached access token are gone. It therefore holds nothing it could ask Codeberg with, and keeping a live credential purely to poll with would be the one thing this design exists to avoid.

Nor can it ask indirectly: an OAuth prompt=none check, which on some providers reports whether a grant still exists, is ignored by Codeberg — it shows the approval screen instead. Measured, not assumed.

So remove it at the provider first. Pressing I removed it before you have leaves an authorization standing that Muppy will no longer mention to anyone.

You are also warned before any of this happens: a connection to a provider Muppy cannot cancel says so on its form while it is still working, not once it is too late.

What Muppy can and cannot do for you here¶


Check what a token really is	Yes — Introspect token reads the scopes and the repository limitation from Forgejo, and corrects your entry in place.
Cancel a Muppy authorization	No. Forgejo offers no revocation API at all, so removing it is yours to do — see above.