Skip to main content

Docfiy supports OAuth-based authorization for self-hosted GitLab instances, in addition to gitlab.com. OAuth lets the Docfiy agent act as a GitLab user during automation runs: cloning repositories, pushing commits, opening merge requests, and registering project webhooks.

You must configure OAuth authorization for self-hosted GitLab instances to support automations.

Unlike gitlab.com, where Docfiy ships a single OAuth application that every customer authorizes against, each self-hosted instance must register its own OAuth application. Create the application on your GitLab instance, share its credentials with Docfiy, and then go through an OAuth authorization to connect a user.

This guide is only for the OAuth integration that powers automations. You must configure the deployment-side connection (used for content sync and previews) separately with a deploy token, see the GitLab guide. The OAuth integration depends on the deployment-side connection.

Prerequisites

  • Admin access to your self-hosted GitLab instance.
  • Your GitLab instance must be reachable from https://app.docfiy.com. Instances behind a VPN or behind a firewall that blocks public ingress do not work.
  • A Docfiy organization that has the self-hosted GitLab feature enabled. Contact support if you don't see the Self-hosted GitLab section in your Git settings dashboard page.

Set up the connection

1

Register an OAuth application on your GitLab instance

In your self-hosted GitLab, sign in as an admin and navigate to Admin Area > Applications > Add new application.

Configure the application with these values:

  • Name: Docfiy
  • Redirect URI: https://app.docfiy.com/api/gitlab-oauth/callback
  • Trusted: leave unchecked. Trusting the application skips the consent screen for every user; leaving it unchecked surfaces a normal authorization prompt the first time each user connects.
  • Confidential: checked. Docfiy is a server-side client and keeps the secret confidential.
  • Scopes: select api, read_repository, and write_repository. The agent uses these to read project metadata, clone repositories, and push commits.

Click Save application.

Editing an OAuth application on GitLab can rotate the client secret silently. If you make changes later, click Renew secret and update the new value in Docfiy.

2

Copy the application credentials

After saving, GitLab displays the application's Application ID and Secret. Keep this page open—the secret is only shown once.

3

Register the instance in Docfiy

In your Docfiy dashboard, open Settings > Git settings and find the Self-hosted GitLab section under GitLab OAuth.

Click Connect Self-Hosted GitLab and enter:

  • GitLab instance URL: the public URL of your GitLab instance, for example https://gitlab.your-company.com. Docfiy reaches your instance through this URL when exchanging tokens and calling the GitLab API.
  • OAuth application client ID: the Application ID from the previous step.
  • OAuth application client secret: the Secret from the previous step.

Click Save instance. Docfiy encrypts the secret at rest and never returns it to the browser after saving.

4

Authorize

Click Authorize self-hosted GitLab. You'll be redirected to your GitLab instance, prompted to sign in if needed, and shown a consent screen listing the requested scopes.

After you click Authorize on GitLab, you'll be redirected back to Docfiy and the new connection appears in the installations list, badged with your instance hostname.

5

Choose projects

Expand the connection in the dashboard. Docfiy lists every group your authorizing user has Maintainer or higher access to, plus a Personal projects entry for projects in the user's personal namespace.

Check the box next to each project that should participate in automations. Docfiy registers a webhook on the project, generates a secret token, and stores it encrypted. From then on, Docfiy receives push and merge-request events from your instance for that project.

The connecting user must have Maintainer role on a project for Docfiy to mint short-lived project access tokens during automation runs. Without Maintainer, the agent can read but cannot push commits or open merge requests.

Rotate credentials

If you need to change the registered application's client secret—for example after renewing it on GitLab—remove the saved instance in Docfiy and add it again with the new values. You must revoke active OAuth connections first; otherwise Docfiy blocks the removal.

1

Revoke each connection

Click Revoke on every installation listed under the self-hosted instance. This removes the webhook on every connected project and revokes the OAuth token on GitLab.

2

Remove the instance

In the Self-hosted GitLab card, click Remove instance.

3

Re-add with new credentials

Follow the Set up the connection steps described earlier with the new client secret.

Troubleshooting

invalid_client after authorizing

GitLab rejected the token-exchange step because the client secret Docfiy sent doesn't match what's registered on the application. The most common cause is that a secret rotated on GitLab—by an explicit Renew secret, or silently when someone edited the application—and the value in Docfiy is stale.

Fix: rotate credentials following the Rotate credentials steps with the current secret.

Webhook registration failed: Invalid url given

GitLab refused to register the webhook because the URL Docfiy sent (https://app.docfiy.com/gitlab-oauth-webhook) was rejected by GitLab's outbound-request allowlist. Self-hosted instances reject "local" URLs unless the admin explicitly allows them.

Fix: in your GitLab admin area, go to Settings > Network > Outbound requests and enable Allow requests to the local network from webhooks and integrations. If your network policy blocks app.docfiy.com, contact your network admin to allow outbound HTTPS to that host.

If you don't see GitLab's consent dialog when authorizing, either:

  • The application is marked Trusted on GitLab. Trusted applications skip consent for all users. Uncheck Trusted in the application settings if you want users to see and confirm scopes.
  • Your GitLab user has previously authorized the application with the same scopes. GitLab remembers prior grants and skips consent on subsequent authorizes. Revoke the application authorization in User settings > Applications > Authorized applications to see consent again.