Connecting a Repository

Create an OAuth Application in GitLab

Before connecting, register an OAuth application in the GitLab instance you want to use:

1. Go to User Settings → Applications (or Admin Area → Applications for instance-wide apps)

2. Set Name to anything recognisable, e.g. Cratly Editor

3. Set Redirect URI to the address of the editor you are going to use, plus /callback. For the hosted editor at editor.cratly.io that is:

   https://editor.cratly.io/callback

   Running your own instance? Use its address instead — the rule is always the editor's origin followed by /callback.

   Additional addresses go on their own line. To use the editor locally during development as well, add both spellings of the dev server — the redirect URI has to match the address in the browser's bar exactly, and vite dev prints the first one while many people type the second:

   http://127.0.0.1:5174/callback
   http://localhost:5174/callback

4. Under Scopes, enable api

5. Save — copy the Application ID (this is the client ID you will enter in the editor)

Why the api scope?

The api scope is the minimum GitLab offers that allows reading and writing repository content. The editor needs it to:

• Read file trees and file contents
• Create commits (save changes)
• Read and create branches
• Open merge requests
• Read branch protection and merge-request permissions (for role detection and the setup check)

GitLab does not provide a narrower scope that covers repository writes. The read_repository and write_repository scopes cover Git operations over HTTP but not the API endpoints the editor relies on for branch management and merge requests.

Your access token is stored only in your browser's session storage and is never sent anywhere other than your GitLab instance.

Instance-wide vs. user-level applications

Type	Where to register	Who can use it
User-level	User Settings → Applications	Only your account
Instance-wide	Admin Area → Applications	Any user on the instance

For a shared deployment (e.g. a team using the same Cratly Editor URL), register an instance-wide application so each team member can authenticate with their own GitLab account.

Connect from the Editor

Open the editor and fill in the connection form:

Field	Value
GitLab Instance URL	e.g. https://gitlab.com or your self-hosted URL
Application ID	The client ID from the step above
Repository Path	group/project as shown in the GitLab URL

Click Connect via OAuth — you will be redirected to GitLab to authorise, then returned automatically.

Saved Connections

After a successful connection the credentials are saved in your browser's local storage. On the next visit you can reconnect with one click from the saved list.

To remove a saved connection, click the × next to it.