Source: https://manu-tests-all-orgs.docs-staging.pageloop.ai/integrations/development-it-operations/gitlab # GitLab # GitLab ## GitLab: Overview and setup Automate projects, issues, CI/CD pipelines, and group access with the GitLab integration. Connect GitLab to Atomicwork to automate project management, issue tracking, CI/CD pipeline operations, and team access management as part of your IT and developer workflows. ### Use cases By connecting GitLab, your teams can: - **Automate project management:** Create and manage GitLab projects, and control team membership by adding or removing users with specific access levels (Guest, Reporter, Developer, Maintainer). - **Streamline issue tracking:** Create, update, and track GitLab issues from Atomicwork workflows — for example, automatically creating a GitLab issue when an incident is reported or a change request is approved. - **Trigger CI/CD pipelines:** Trigger and monitor GitLab pipelines as part of deployment or release workflows. - **Manage group access:** Invite users to GitLab groups with specific roles and optional access expiration, making it easy to manage access during onboarding and offboarding. ### Permissions To connect GitLab to Atomicwork, you need: - **Org admin access** in Atomicwork - **Admin access** to your GitLab instance (or GitLab.com account) with permission to create OAuth applications The integration authenticates via OAuth 2.0 and requests the `api` scope, which provides full read/write access to the GitLab API. For security reviews, the table below lists the equivalent narrower scopes that describe the specific capabilities the integration uses: | **OAuth Scope** | **Purpose** | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`api`** | Full read/write access to the GitLab API. Required for all supported actions — project management, issue tracking, CI/CD pipeline operations, group access, and user management. This is the scope Atomicwork requests during authorization. | | **`read_api`** | Read access to the API. Covers the List projects, Get project, List issues, Get issue, List pipelines, Get pipeline, List groups, and List users actions. | | **`read_user`** | Read user profile information. Covers user lookup operations during member invites and access management. | | **`read_repository`** | Read repository data. Covers project and issue retrieval operations. | | **`write_repository`** | Write access to repositories. Covers Create project, Create issue, Update issue, and Trigger pipeline actions. | > \[!NOTE] > **Note:** The Atomicwork integration authorizes with the `api` scope, which is the GitLab umbrella scope covering all of the narrower scopes listed above. The narrower scopes are documented here so your security team can map the integration's capabilities to your access policy. ### Setup Before connecting, gather the following from your GitLab OAuth application settings: - **Application ID** (Client ID) - **Secret** (Client Secret) For self-hosted GitLab instances, you'll also need your GitLab instance URL. - Navigate to **Settings > App Store > GitLab**. - Click **Connect** to initiate the OAuth flow. - Sign in with your GitLab account and authorize the requested permissions. - Once authorized, the integration is active. ### Supported workflow actions Once connected, you can automate the following GitLab actions within your Atomicwork workflows: | **Action** | **Description** | | ----------------------- | ------------------------------------------------------------------------------------------------- | | **List projects** | List GitLab projects with search and pagination. | | **Create project** | Create a new GitLab project. | | **Get project** | Retrieve detailed information about a specific project. | | **Add project member** | Add a user to a project with a specific access level (Guest, Reporter, Developer, or Maintainer). | | **List issues** | List issues in a project with search and pagination. | | **Create issue** | Create a new issue in a project with title, description, labels, and assignee. | | **Get issue** | Retrieve detailed information about a specific issue. | | **Update issue** | Update an existing issue's title, description, status, assignee, or labels. | | **List pipelines** | List CI/CD pipelines for a project. | | **Trigger pipeline** | Trigger a CI/CD pipeline for a project. | | **Get pipeline** | Retrieve detailed information about a specific pipeline run. | | **List groups** | List GitLab groups with search and pagination. | | **Invite group member** | Invite a user to a group with a specific access level and optional access expiration date. | | **List users** | List GitLab users with search and pagination. | | **Call API** | Make a generic API call to any GitLab endpoint for custom operations. | ### Troubleshoot common issues | **Error** | **Cause** | **Resolution** | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | **Failed to exchange token** | Token acquisition failed — the authorization code may have expired or the redirect URI doesn't match. | Verify the OAuth application configuration in GitLab and re-initiate the connection from **Settings > App Store > GitLab**. | | **Token response missing required fields** | The OAuth response from GitLab is incomplete. | Check your GitLab OAuth application configuration and ensure it's properly set up. | | **Token refresh failure** | The refresh token has expired or been revoked. | Re-authenticate the integration to generate new tokens. | ---