Onboard GitLab to DevOps Change Velocity — Workspace

Connect to your GitLab instance using the DevOps Change Workspace playbook to discover plans, repositories, and pipelines.

Before you begin

Complete the tasks specified in the Getting started with DevOps Change Velocity topic.

Role required: sn_devops.admin or sn_devops.tool_owner

Procedure

Navigate to Workspaces > DevOps Change Workspace and use one of the following options to open the Playbook to onboard GitLab.

Option	Steps
Homepage	Select Connect a tool. From the Connect to a tool modal, select the tool from the appropriate category. For example, if you want to connect to GitLab as coding tool, you'd select GitLab under the Code category.
Applications module	Select Applications ( Image omitted: applications-icon.png Applications icon.) from the primary navigation.</li> Select an existing application, or create one. To create an application, see Create an application - Workspace. From the  Recommended actions  pane, select the  Connect a tool  card. From the Connect to a tool modal, select the tool from the appropriate category. For example, if you want to connect to GitLab as coding tool, you'd select GitLab under the Code category.
Tools module	Select Tools ( Image omitted: tools-icon-wkspc.png Tools icon.) from the primary navigation.</li> From the Capability list, select the appropriate category. For example, if you want to connect to GitLab as coding tool, you'd select the Coding category. Select Connect a tool. On the  Connect to a tool  modal, select GitLab.

**Important:** If you want to discover and track tool objects like plans, pipelines, or repositories while connecting to the tool, you must connect your tool from the Application module.

In the Tool name field, enter a name for the tool.

Image omitted: gitlab-connect-workspace-1.png
Connect to GitLab tool screen

Select Next.

The DevOps playbook opens to help you complete the onboarding tasks.
Enter your GitLab instance details.
1. Enter your GitLab instance URL.
2. In the Credential type field, select one.
  - Basic Auth
  - OAuth 2.0
    1. Enter the credentials.
  - Basic Auth: Enter the username and password/access token of your GitLab instance.
    
    Note: Only personal access token is supported. When you generate the token, select the scope API and grant read/write access including all the groups and projects, container registry, and package registry.
  - OAuth 2.0: Enter your OAuth credential.
    
    For more information on OAuth2.0 credentials, see Setting up GitLab OAuth 2.0 credentials for DevOps.
3. If your GitLab instance is attached to a MID Server, select the MID Server option and enter its details.
  
  For more information about MID server, see MID Server selection
4. Select Connect.

Image omitted: gitlab-connect-workspace-2.png
Connect to Gitlab tool - Enter instance details screen

Permission checks are run on the credentials that you entered.

Permissions required and permissions that are available are displayed. If you want to enter credentials with better permissions, select Re-enter credentials. For detailed information on all the required permissions, see GitLab permissions in Permissions required for DevOps tools.

You can choose to continue with the tool connection even if you don't have all the required permissions.

Image omitted: gitlab-connect-workspace-3.png
Connect to Gitlab tool - permission checks screen

Select Next.
Specify the access for the tool.
1. If you want to control access to the tool, add the groups that must be given access to the tool in the Maintained by field.
  
  The tasks these users in the groups can perform depends on the role assigned to them.
  - DevOps Tool Owner role: Can view and edit the tool.
  - DevOps App Owner role: Can view the tool and can associate, discover, import historical data, and modify pipeline steps (if applicable) of the tool's objects (such as plans, repositories, and pipelines).
  - DevOps Administrator role: Can edit all tools.
  - Other DevOps roles: Can view the tool. Note: If you don't select a group and skip this step, all users with the DevOps Tool Owner role will be able to edit the tool.
2. If you choose to control access to the tool, the All App Owners can view and associate tool objects to applications option becomes available for selection.
  
  This option enables all users having the DevOps App Owner role to access the tool. If selected, they’ll be able to view, associate, discover, import historical data, and modify pipeline steps (if applicable) of the tool's objects.
3. Select Assign.

Image omitted: gitlab-connect-workspace-6.png
Specify tool access

Select the projects for which you want to configure webhooks automatically.

You can also choose to enable nightly polling to retrieve data for any tracked pipelines by selecting the Enable Polling property option in the Administration module. See DevOps Change Velocity properties.
Select Configure.

Image omitted: gitlab-connect-workspace-4.png
Connect to the Gitlab tool - configure screen

To configure manually, select **Configure manually**. See [Configure webhooks in GitLab manually](configure-webhooks-in-gitlab.md) for more information.

**Important:**

-   If you're connecting from the Home page or Tools module, the connection is complete and you're taken to the Summary page.
-   If you're connecting from the Applications module, then plans, repositories, and pipelines available in your project are discovered. You can track and import historical data from them.

Select the pipelines that you want to associate to the application, and select Associate pipelines.

For each selected pipeline, all steps are imported for the last successful execution.
In the Assign services to pipeline steps activity, specify Step type and Service for each pipeline step.

Completing this step as part of tool onboarding enables the DevOps Insights dashboards to show more meaningful data immediately.
Select the plans you want to associate to the application, and select Associate plans.
Select the repositories you want to associate to the application, and select Associate repositories.
In the Import historical data step, select the date range in the Start date and End date fields and select Import data.

Note: You can import up to 90 days of data.
Select Next.
From the Summary page, review the details of the successfully connected GitLab tool.

Select View tool record to review the details of the connected instance.

Result

You’ve successfully onboarded your GitLab tool to DevOps Change Velocity.

Note: If your tool credential changes, you must also update the credentials in DevOps Change. For more information, see Update third-party tool credentials in DevOps Change Velocity.

Parent Topic:GitLab integration with DevOps Change Velocity

Related topics

Configure webhooks from the tool record