Registering the Muppy OAuth Application¶

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

For administrators. A user who presses Connect on a Git provider is sent to that provider to authorise Muppy. For the provider to have anything to authorise, Muppy must first exist there as an OAuth application — one per Git Provider record, registered once by an administrator. Until that is done, Connect does not appear.

The application is what lets Muppy ask questions of the provider on a user's behalf: what a token really is, whether it is still alive, which of the user's tokens it is. It is an API capability and nothing else — it is never served to a box, and it carries no git access (see OAuth is for talking to your provider). That is why the scopes below are narrow.

Where it applies¶

Provider	Application needed?
GitLab (gitlab.com or self-hosted)	Yes — below.
Forgejo / Gitea (Codeberg or self-hosted)	Yes — below.
GitHub	No. Muppy does not use an OAuth application on GitHub: a connection would have no consumer, since GitHub offers no endpoint to list a user's tokens. Access is by personal access token.
Azure DevOps	No. Muppy builds no OAuth connection for Azure DevOps. Access is by personal access token.

On the two providers where it does not apply, the Git Provider form says so in place of the registration fields.

The three values, wherever you register¶

Every provider asks for the same three things. The Git Provider form in Muppy (Git → Git Providers, group OAuth application, administrators only) gives you the first and receives the other two:

Value	Direction	Where
Redirect URI	Muppy → provider	Copy it from the form's OAuth Redirect URI field. It is derived from Muppy's public URL and must match exactly at the provider, one URI per line.
Client ID	provider → Muppy	Paste it into OAuth Client ID.
Client Secret	provider → Muppy	Paste it into OAuth Client Secret. Only administrators can read that field; the OAuth flow reads it server-side and it never leaves Muppy.

The form's action band carries two shortcuts: Open OAuth Applications at Provider opens the provider page where the application is registered, and Open Provider's OAuth Doc. opens the provider's own instructions.

The Redirect URI follows Muppy's public URL

The URI is computed from the public URL boxes already use to reach Muppy (muppy.dev_server.muppy_api_url, falling back to web.base.url). If that URL changes, the value on the form changes with it and the application at the provider must be updated to match — a mismatch is refused by the provider at the first Connect.

GitLab¶

User Settings → Applications → Add new application (self-hosted: the same page on your instance; an instance-wide application under Admin → Applications also works).

Field	Value	Why
Name	`Muppy` (or the name of your Muppy instance)	Free. It is what users see on the consent screen and under Authorized applications.
Redirect URI	the form's OAuth Redirect URI	Must match exactly.
Confidential	checked	Muppy holds the client secret server-side and presents it when exchanging and revoking tokens.
Scopes	`read_api` — nothing else	Read-only on the account: enough to list and introspect tokens, read project identity and branches. Nothing in it grants git access, and nothing in it writes.

Save, then paste the Application ID into OAuth Client ID and the Secret into OAuth Client Secret on the Git Provider form.

Why not read_repository / write_repository

Those are git scopes. The connection is never used for git — boxes are served the user's own token — so an application carrying them would be asking users to grant repository access Muppy never exercises. Muppy requests read_api at authorisation time; an application that does not carry it is refused by GitLab with an invalid scope error at the first Connect.

Developer-mode testing

Users in Odoo developer mode see a second choice at Connect: the full api scope, for measuring what api allows that read_api does not. It only works if the application also carries api. Do not add it for that reason alone: api writes, and a connection carrying it can mint tokens and install webhooks on the user's account.

Disconnect on GitLab is complete: Muppy revokes the grant at GitLab and nothing is left outstanding for the user to clean up.

Forgejo / Codeberg¶

Avatar → Settings → Applications → Manage OAuth2 Applications → Create a new OAuth2 Application.

Field	Value	Why
Application name	`Muppy` (or the name of your Muppy instance)	Free.
Redirect URIs	the form's OAuth Redirect URI	Must match exactly.
Confidential client	checked	Same reason as on GitLab: the secret is presented server-side.
Scopes	none to choose	Forgejo implements no OAuth2 scopes.

Save, then paste the Client ID and the Client Secret into the Git Provider form.

A Forgejo connection is full-account

Because Forgejo has no scopes, whatever the application is, the connection a user grants acts as them — everything their account can do. Muppy asks for nothing narrower because nothing narrower exists, and never lets that connection reach a box. Users are told so on the consent screen and at Connect; the details, and why a Forgejo Disconnect leaves the user one thing to do, are on Managing Forgejo / Codeberg Tokens.

After registration¶

Connect appears in the form header for every user, and in the Introspect token flow wherever a token cannot describe itself.
Connection idle ceiling (same form, group Connection policy) bounds how long a user's connection may stay open unused — see Git Credential Settings.
Rotating the secret at the provider is one paste into OAuth Client Secret; existing user connections keep working. Changing the application's scopes is not: every user has to Connect again, and the provider re-prompts them because the grant changed.