This guide walks you through setting up a GitLab application to enable GitLab integration for your Plane workspace on a self-hosted instance. Since self-hosted environments don’t come pre-configured for GitLab, you’ll need to create an application, configure authentication, and set the necessary permissions to ensure seamless integration.

In this guide, you’ll:

  1. Create and configure a GitLab Application
  2. Configure your Plane instance

​
Create GitLab Application

  1. On the left sidebar in GitLab, select your avatar.

  2. Select Preferences tab.

  3. Navigate to the Applications tab.

  4. Click on Add new application to begin the setup.

  5. Provide a Name for your application.

  6. Enter the following Redirect URI, replacing [YOUR_DOMAIN] with your actual domain:

    https://[YOUR_DOMAIN]/silo/api/gitlab/auth/callback

  7. You can choose to check or leave the Confidential box unchecked—both options work for Plane.

  8. Set permissions by selecting the required Scopes. The table below explains each scope:

    PermissionExplanation
    apiGrants full read/write access to the API, including all groups, projects, container registry, dependency proxy, and package registry. Required for API requests.
    read_apiAllows read-only access to all groups, projects, container registry, and package registry.
    read_userGrants read-only access to user profiles via the /user API endpoint, including username, public email, and full name. Also provides access to /users endpoints.
    read_repositoryEnables read-only access to repositories in private projects via Git-over-HTTP or the Repository Files API.
    write_repositoryAllows read/write access to repositories on private projects via Git-over-HTTP (not through the API).
    profileGrants read-only access to the user’s profile data using OpenID Connect.
    emailProvides read-only access to the user’s primary email address using OpenID Connect.

  9. Click Save Application to finalize the setup.

​
Configure Plane instance

  1. Copy the Application ID and Secret from the newly created application.

  2. Add these environment variables with the values to your Plane instance’s .env file.

    GITLAB_CLIENT_ID=<application_id>
GITLAB_CLIENT_SECRET=<secret>

  3. Save the file and restart the instance.

  4. Once you’ve completed the instance configuration, activate the GitLab integration in Plane.