GitSync Wiki

OAuth for Self-Hosted Instances

OAuth login is not available for self-hosted Forgejo, Gitea, GitLab or Git servers. Use a personal access token or an SSH key instead.

This comes up regularly, so here’s the reasoning and what to use in its place.

Why it isn’t feasible

OAuth requires a client application registered on the server you’re logging in to. That registration lives in that server’s own database, and it produces a client ID and a redirect URI that only that server recognises.

GitSync ships with one registered application per public provider:

  • github.com
  • gitlab.com
  • gitea.com
  • codeberg.org

Those client IDs are compiled into the app and are meaningless on any other host. Pointing GitSync’s Gitea OAuth flow at git.example.com would send a client ID that instance has never seen, and the login would be rejected before you ever got to the consent screen.

For OAuth to work against a self-hosted instance, every instance would need its own registration, which means:

  • An admin registering a GitSync OAuth application on that instance
  • Adding gitsync://auth as an allowed redirect URI there
  • The resulting client ID being supplied to the app somehow

There is no way to ship that ahead of time for servers that don’t exist yet, and no central registry to look it up from.

This is a limitation of how OAuth works, not of a specific provider. It applies equally to self-hosted Forgejo, Gitea, GitLab CE/EE and anything else.

What to use instead

Personal access tokens and SSH keys work today on any instance, and give the same level of access as an OAuth token would.

Personal Access Token (HTTP/S)

  1. On your instance, go to Applications
  2. Generate a token and copy it (it is only shown once)
  3. In GitSync, choose HTTP/S authentication and enter your username and the token as the password

SSH Key

  1. In GitSync, choose SSH authentication and generate an ED25519 key pair (RSA, DSA and ECDSA are also supported)
  2. Copy the public key
  3. Add it to your instance under Settings > SSH / GPG Keys
  4. Clone using the SSH remote URL

See Authentication Methods for more on both options.

See also: Authentication Methods, Repository Settings, Troubleshooting

Graph View

Backlinks