Skip to main content

GitLab

GitLab is a complete DevOps platform that provides source code management, CI/CD pipelines, issue tracking, merge request reviews, container registry, and project management capabilities. It supports both cloud-hosted (gitlab.com) and self-hosted instances, making it ideal for teams of all sizes who want an all-in-one solution for their software development lifecycle.

Authentication Types​

GitLab supports 1 authentication method:

  • OAuth - Create a GitLab OAuth application and connect users with their GitLab accounts.
    • Pros: Secure, per-user permissions, works with both gitlab.com and self-hosted instances, granular scope control, automatic token refresh
    • Cons: Requires admin access to create application or user must create their own
    • Best for: Team collaboration, production deployments, and organizations using self-hosted GitLab

General Settings​

Before using the connector, you need to configure:

  • Instance URL - Your GitLab instance URL (e.g., https://gitlab.com for GitLab.com or https://gitlab.yourcompany.com for self-hosted)
tip

For GitLab.com, use https://gitlab.com as the Instance URL. For self-hosted GitLab, use your custom domain without any path (e.g., https://gitlab.example.com, not https://gitlab.example.com/api/v4).

Setting up OAuth​

To use GitLab with Webrix, you need to create a GitLab OAuth application.

1. Create a GitLab Application​

  1. Log in to your GitLab account (gitlab.com or your self-hosted instance)

  2. Click on your avatar in the top right corner

  3. Select Preferences from the dropdown menu

  4. In the left sidebar, click Applications

  5. Click Add new application button

  6. Fill in the application details:

    • Name: Enter a descriptive name (e.g., "Webrix Integration")
    • Redirect URI: Copy the Redirect URI from Webrix and paste it here
    tip

    You can find the Redirect URI in Webrix when configuring the GitLab connector under the OAuth settings. Make sure to copy it exactly, including the protocol (https://) and any trailing paths.

  7. Select the Scopes you want to grant. For full functionality, we recommend:

    • api - Complete read/write access (includes all operations)

    Or for more granular control, select specific scopes:

    • read_api - Read-only API access
    • read_user - Read user profile information
    • read_repository - Read repository via Git-over-HTTP
    • write_repository - Write repository via Git-over-HTTP
    • read_registry - Read container registry images
    warning

    The api scope is the most powerful and grants full access. Use more granular scopes if you want to limit what operations users can perform.

  8. Leave Confidential checked (recommended for server-side applications)

  9. Click Save application

  10. Copy the Application ID and Secret that are displayed

    warning

    The Secret is only shown once. Make sure to copy it immediately. If you lose it, you'll need to regenerate it.

2. Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select GitLab and click Use

  3. Under General Settings:

    • Instance URL: Enter your GitLab instance URL (e.g., https://gitlab.com)

  4. Under Authentication Type, select OAuth

  5. Paste your Application ID in the Client ID field

  6. Paste your Secret in the Client Secret field

  7. Select the Scopes that match what you configured in GitLab

  8. Click Save Changes

3. Test the Connection​

  1. After saving, click Connect to test the OAuth flow

  2. You'll be redirected to GitLab to authorize the application

  3. Review the permissions requested and click Authorize

  4. You'll be redirected back to Webrix with a successful connection

  5. The connector is now ready to use!

Troubleshooting​

Redirect URI Mismatch Error​

If you see a redirect_uri error during OAuth authorization.

Cause: The redirect URL configured in your GitLab application doesn't match the one being used during the OAuth flow.

Solution:

  1. Copy the exact Redirect URI from Webrix (found in the OAuth configuration)
  2. Go to your GitLab account → Preferences → Applications
  3. Edit your application
  4. Ensure the Redirect URI matches exactly (including protocol, domain, path, and any trailing slashes)
  5. Save the changes and try connecting again

Invalid Credentials Error​

Authentication fails with "invalid_client" or "invalid_grant" error.

Cause: The Client ID or Secret is incorrect, or the application has been deleted/regenerated in GitLab.

Solution:

  1. Verify that you copied the correct Application ID and Secret from GitLab
  2. Check that the application still exists in GitLab (Preferences → Applications)
  3. If the Secret was regenerated, update it in Webrix with the new value
  4. Ensure there are no extra spaces or characters when pasting credentials

Self-Hosted Instance Configuration​

Connection fails or tools don't work with self-hosted GitLab.

Cause: Incorrect Instance URL format or self-hosted instance requires additional configuration.

Solution:

  1. Ensure the Instance URL is your GitLab domain without any paths
    • Correct: https://gitlab.example.com
    • Incorrect: https://gitlab.example.com/api/v4
  2. Verify your self-hosted GitLab instance is accessible from the internet (or from Webrix's network)
  3. Check that your GitLab instance has API access enabled (it's enabled by default)
  4. Ensure your GitLab version is 13.0 or later for best compatibility
  5. If behind a firewall, configure necessary firewall rules to allow connections

Insufficient Scope Permissions​

API requests fail with 403 Forbidden or scope-related errors.

Cause: The OAuth application doesn't have the necessary scopes for the operation you're trying to perform.

Solution:

  1. Review which scopes are granted to your application in GitLab (Preferences → Applications)
  2. Add the missing scopes:
    • For project operations: api or read_api + write_repository
    • For user operations: read_user
    • For registry operations: read_registry
  3. After adding scopes, disconnect and reconnect the integration in Webrix
  4. Users will need to re-authorize to grant the new permissions

Rate Limiting​

API requests fail with 429 (Too Many Requests) errors.

Cause: GitLab enforces rate limits to ensure platform stability. Default limits are 300 requests per minute for authenticated users.

Solution:

  1. GitLab.com has a rate limit of 2,000 requests per minute for authenticated users
  2. Self-hosted instances can configure their own rate limits
  3. Implement retry logic with exponential backoff in your workflows
  4. Batch operations where possible (e.g., use list operations instead of multiple get requests)
  5. For self-hosted, administrators can adjust rate limits in GitLab settings

Project or Issue IDs vs IIDs​

Getting 404 errors when trying to access issues or merge requests.

Cause: Using the wrong identifier type. GitLab uses both IDs (global) and IIDs (project-internal).

Solution:

  1. For issues and merge requests, use the IID (internal ID), not the global ID
    • IID is the number shown in the project (e.g., #42 or !15)
    • Example: Use 42 for issue #42, not the global ID
  2. For projects, you can use either:
    • Numeric ID (e.g., 12345)
    • URL-encoded path (e.g., namespace%2Fproject-name or simply namespace/project-name)
  3. Use the List tools first to find the correct IDs/IIDs for the resources you want to access

OAuth Token Expiration​

Users are repeatedly prompted to reconnect or get "unauthorized" errors.

Cause: Access tokens expire after 2 hours by default, and the refresh token may have failed or been revoked.

Solution:

  1. GitLab OAuth tokens expire after 2 hours but are automatically refreshed
  2. If refresh fails, disconnect and reconnect the integration in Webrix
  3. Verify that the OAuth application hasn't been deleted in GitLab
  4. Check that the Secret hasn't changed in GitLab (if regenerated, update in Webrix)
  5. Ensure the offline_access scope is implicitly granted (included with OAuth)