Last updated

Add remote files from GitLab self-managed

If your project files are stored in a GitLab self-managed repo, you can connect that repository, so you can access 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. Create a new branch in Redocly.
  5. Enter the connection details in Redocly.
  6. Merge open pull request 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:

  • Redirect URI: https://app.cloud.redocly.com/callback/oauth2.
  • Scopes: api.

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.

How to find and copy the Redocly organization or project slugs
  1. Log in to Redocly.
  2. Select your organization and project.
  3. Copy the value of the {ORGANIZATION_SLUG} or {PROJECT_SLUG} from the page URL in your browser, based on the following structure, https://{REDOCLY_HOST}/org/{ORGANIZATION_SLUG}/project/{PROJECT_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:

    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:

    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 a 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 new branch in Redocly

Before you make any changes to your project, you should create a new branch. This new branch is a place where you can make changes without affecting the published site until you are ready. After you have iterated on your changes based on reviews by your team and the updates have been approved, you can merge your changes into the published site.

To create a new branch:

  1. Go to the project editor.

  2. Click the name of the current branch.

    Screenshot where current branch is on project page

  3. Enter the name for your new branch and select Create Branch.

Enter the connection details in Redocly

  1. In the file tree, select the folder (or click on the empty space to select the root directory) where you want to add the remote content folder.
  2. Select + > New remote folder > Add Git repository.
  3. Enter a name for the new remote content folder and press Enter or Return key.
  4. Select the provider with the CREDENTIAL_NAME you used when you created your application credentials.
  5. Enter a Connection name that identifies this GitLab connection.
  6. Enter the Access token you saved from the Create a new access token in GitLab step and select Next.
  7. Select the Namespace > Project > Branch.
  8. (Optional) Select the Folder, if you want to include only a specific folder from the repository.
  9. Select the Auto-sync or Auto-merge toggles to turn off either option.
  10. Select Add remote. This action opens a pull request in Redocly automatically. After refreshing your browser, you should see a View Pull Request button next to your new branch name.

Merge the open pull request in Redocly

After you enter the connection details in Redocly, a pull request to merge your updates with the default branch opens.

  1. Refresh your browser to see a View Pull Request button next to your new branch name.
  2. Select View Pull Request.
  3. Review your updates in the Review tab.
  4. After the tests have run and your pull request has been approved, click the Merge button to merge your updates with the default branch.
 
Next page