Add a GitLab self-managed repo

If your project files are stored in a GitLab self-managed repo, you can connect that repository, so you can access, edit, and publish those files in Redocly.

To connect a GitLab self-managed repo:

1. Create an OAuth 2 application in your GitLab self-managed instance.
2. Create your application credentials in Redocly.
3. Create new access token in GitLab.
4. Enter the connection details in Redocly.

Create an application in your GitLab self-managed

Redocly supports OAuth 2.0 to identify your GitLab self-managed users, so they can authenticate and perform operations such as opening or merging your GitLab merge requests from Redocly.

To connect your GitLab self-managed instance to Redocly, you must create an OAuth 2 application on your instance and copy the Application ID and Secret for use in a later step in the process.

The OAuth 2 application must have api scope and use one of the following Redirect URIs depending on your location:

See Create an application for OAuth 2.0 in GitLab's documentation for more information on creating an application in GitLab.

Create your application credentials in Redocly

To create GitLab self-managed application credentials in Redocly, you need to call the Redocly API directly using any HTTP client.

The following inputs are required when calling the Redocly API:

• {TOKEN}: This input is your Redocly access token.

  How to find and copy the Redocly access token in a Google Chrome browser

  1. Log in to Redocly.
  2. Open the browser developer tools by clicking View > Developer > Developer Tools.
  3. Open the Application tab.
  4. On the left side of the page, select Storage > Cookies > Redocly host url.
  5. Find a cookie with a name accessToken, double-click on the Value column to select it, then copy the value.

• {CREDENTIAL_NAME}: This input is the name you select in Redocly to use this credential.

• {GITLAB_SELF_MANAGED_URL} This input is the URL of your GitLab self-managed instance (without a subpath).

• {APPLICATION_ID} This input is your OAuth 2 Client ID, or the Application ID in GitLab (copied from the previous step).

• {APPLICATION_SECRET}: This input is your OAuth 2 Client Secret or the Secret field in GitLab (copied from the previous step).

• {ORGANIZATION_SLUG}: This input is your Redocly organization slug.

Example request

The following example uses curl to create GitLab self-managed credentials:

curl -XPOST -H 'cookie: accessToken={TOKEN}' -H "content-type: application/json" -d '{
   "type": "GITLAB_SELF_MANAGED_APP",
   "name": "{CREDENTIAL_NAME}",
   "publicData": {
     "url": "{GITLAB_SELF_MANAGED_URL}",
     "appId": "{APPLICATION_ID}",
   },
   "secretData": {
     "appSecret": "{APPLICATION_SECRET}",
   }
}' 'https://app.cloud.redocly.com/api/orgs/{ORGANIZATION_SLUG}/credentials'

Update existing GitLab self-managed credential

If your GitLab self-managed credential is misconfigured, you can update it by sending a patch request to the Redocly API using any HTTP client.

To update your GitLab self-managed credentials in Redocly:

1. List all existing GitLab self-managed credentials by making a request to the Redocly API using the following format:

   • US residency
   • EU residency

   curl -XGET -H 'cookie: accessToken={TOKEN}' 'https://app.cloud.redocly.com/api/orgs/{ORGANIZATION_SLUG}/credentials?type=GITLAB_SELF_MANAGED_APP'
   

2. Copy the id of the credential and use it as the {CREDENTIAL_ID} in the next step.

3. Update the credential by sending a patch request to the Redocly API using the following format:

   • US residency
   • EU residency

   curl -XPATCH -H 'cookie: accessToken={TOKEN}' -H "content-type: application/json" -d '{
     "name": "{CREDENTIAL_NAME}",
     "publicData": {
       "url": "{GITLAB_SELF_MANAGED_URL}",
       "appId": "{APPLICATION_ID}",
     },
     "secretData": {
       "appSecret": "{APPLICATION_SECRET}",
     }
   }' 'https://app.cloud.redocly.com/api/orgs/{ORGANIZATION_SLUG}/credentials/{CREDENTIAL_ID}'
   

Create new access token in GitLab

Before you enter the connection details in Redocly, you need to create and copy a new access token for your account in GitLab. Redocly uses this access token to establish a connection to your repository. GitLab offers multiple types of access tokens. The access token you use needs to have api scope and at least Maintainer role.

See the GitLab documentation for creating the following access token types with the API scope option:

• Create a personal access token
• Create a project access token

Enter the connection details in Redocly

1. From your project, select Settings > Git hosting > GitLab.

2. Select the provider with the CREDENTIAL_NAME you used when you created your application credentials.

3. Enter a Credential name that identifies this GitLab self-managed connection.

4. Enter the Access token you saved from the Create new access token in GitLab step and select Next.

5. Select the Namespace > Project > Branch.

6. (Optional) Select the Monorepo folder, if your project files are part of a monorepo, and you want to include only a specific folder from the repository.

   Monorepo folder

   If you select to only include a specific folder from a monorepo:

   • Only files listed in file tree are cloned, no other files are included
   • Project builds are started only when branch contains changes to connected folder
   • Remote content is allowed to add to connected folder only

7. Select Next > Connect.

   Warning

   This step deletes the files currently in the Redocly project and replaces them with the files in GitLab self-managed.