Connect GitLab to Superhuman Docs

Superhuman Connectors let you bring the tools your organization relies on directly into Superhuman. With the GitLab connector, you can sync data from your on-premises GitLab instance — projects, issues, merge requests, pipelines, commits, and members — into Superhuman Docs. From there, you can organize, visualize, and analyze the data right within your doc.

Note: The GitLab connector is only available to customers on our Enterprise tier. You must be an Enterprise admin to complete the setup and configuration steps outlined in this article.

Configure the GitLab connector for your org

Before you can use the GitLab connector in your organization, an admin must complete a few initial steps to create a connector configuration. This process has two main parts: creating an OAuth application in GitLab, and configuring the connector in Superhuman.

Part 1: Create an OAuth application in GitLab

For this part, you will need to be a GitLab administrator or have permission to create applications.

1. Log in to your GitLab instance (e.g., https://gitlab.yourcompany.com) as an admin.
2. For an org-wide integration, navigate to Admin Area → Applications (found under the wrench/gear icon). Alternatively, an individual user can create one under User Settings → Applications.
3. Click New application.
4. Fill in the following info for the new application:
   • Name: For instance, “Superhuman GitLab connector.”
   • Redirect URI: https://coda.io/packsAuth/oauth2/11867
   • Confidential: Leave this checked so a client secret is issued.
   • Scopes: Select api for read/write access based on the user’s permissions, or read_api to allow read-only access.
5. Click Save application.
6. On the application’s details page, note the following pieces of info — you’ll need these for the second part of the configuration:
   • Application ID
   • Secret (you may need to click Reveal or regenerate the secret to view it)

Keep this info handy while you head back to Superhuman to complete the configuration.

Part 2: Configure the connector in Superhuman

With the necessary info from GitLab, you can now complete the configuration in Superhuman:

1. Go to the Connectors page.
2. In the search field in the upper-right corner, enter GitLab, then click on the GitLab Self-Managed connector to start configuring it.

3. On the page that opens, click on the menu next to Connector access and select Custom.

   

4. In the window that appears, click Confirm.

5. In the Configurations section, click Edit to change the existing configuration, or click + Add Configuration below to create a new one.

   

6. Enter or edit the configuration name, then under Groups with access, choose whether the configuration applies to everyone or to selected groups.
7. Under Read permissions, select Allow, Always ask, or Deny.
8. Under Write permissions, also select Allow, Always ask, or Deny.
9. Optionally, check the box next to Allow only private connections to write to GitLab.
10. Optionally, check the box next to Doc sharing to enforce configuration permissions for it.
11. Next, in the OAuth app credentials section, enter your Client ID and Client secret — the Application ID and Secret from your GitLab OAuth application.
12. For the Authorization URL, enter your URL in this format: https://{your-gitlab-domain}/oauth/authorize
13. For Token URL, enter your URL in this format: https://{your-gitlab-domain}/oauth/token
14. In the Permissions section, click Edit JSON.

15. Add the following code, replacing the URL value with your GitLab instance domain — the URL you use to access GitLab in the browser (for example, https://gitlab.yourcompany.com). Do not include a trailing slash.

    {
      "connection": {
        "endpoint": {
          "url": "https://gitlab.yourcompany.com"
        }
      }
    }

16. Click Save configuration.

That’s it. You’ve now successfully connected GitLab to Superhuman Docs.

Start using GitLab in Superhuman Docs

Once the connector configuration is created, workspace members can begin using the connector in Superhuman Docs.

To get started, simply type /GitLab on any blank line in your doc. Select the GitLab connector from the options, and click Add to doc.

You’ll be prompted to sign in to GitLab. The connector uses OAuth2, so after authenticating, it will act on your behalf using your GitLab permissions.

After connecting, you can add sync tables to pull data from GitLab:

• Projects — the projects available to the authenticated user.
• Issues — issues for a given project.
• Merge Requests — merge requests for a given project.
• Pipelines — CI/CD pipelines and their statuses for a given project.
• Commits — commit history for a given project or branch.
• Members — members and their roles for a given project or group.

To add a sync table, find it in the connector settings panel and drag it onto the canvas, or type / followed by the table name on any blank line of your doc. You’ll be prompted to provide the necessary parameters (for example, a Project URL or Project ID).