GitLab SaaS

Prerequisites

Creating an access token

When integrating SCM repositories, you will need an access token you create in GitLab.

Authentication between GitLab and Polaris is managed with an access token that you create in GitLab. If you haven't done so already, create an access token. For additional information: GitLab Docs > GitLab token overview.

Important: Must be created in GitLab SaaS (Premium or Ultimate). Free version does not allow users to create webhooks.
Important: Token must be created by a GitLab Organization Owner or users with the "Manage organization webhooks" permission, who are authorized to manage organization webhooks. Although other GitLab users may be able to select the scope requirements when creating a token, the token will not work due to permission requirements in GitLab to manage organization webhooks.
When creating an access token:
  • Select your avatar.
  • Select Edit profile.
  • On the left sidebar, select Access tokens.
  • Select Add new token.
  • Set the token's expiration date. We recommend setting a maximum expiration period, to avoid issues.
  • Select the role (for Project/Group Access Tokens). Select any role above “Guest”.
  • Under Select scopes, select read_repository, read_api, write_repository and api.

Important: Store your token in a secure location. Each time you modify a project's SCM integration, you'll need to reenter the token to save your changes.

SCM bulk onboard to create applications and projects

See General Prerequisites before starting.
  1. On the Portfolio page, select + Create > New Application(s) with SCM.
  2. Connect to your SCM:
    1. Select GitLab.
    2. Enter the token created in GitLab, (see Prerequisites) under Repository Access Token.
      Note: The access token provided here will be used to complete the onboarding process and will be subject to rate limits enforced by GitLab.
    3. Click Connect.

      You should receive a Connection Successful message and the Quick Start options should be visible. If your connection test is unsuccessful, check the following:

      • Your network connection is stable.
      • Check the Repository Access Token to make sure it is accurate.
      • Check that the Repository Access Token is still valid and has not expired.
      • Check that you selected the correct provider for your source repository.
      • Check that you have authorized use of access token outside SSO (if applicable).
  3. Under Quick Start, Select method: (Repository Mapping is different depending on the selection).
    • Matching Organization Names (Automatic)
    • Mapping Repositories (Custom)
  4. Repository Mapping: This will be different according to which method is selected.
    1. Automatic Mapping: Lists the group/subgroup/repository names as applications and projects. You can view repositories to be imported by using the pulldowns (read only).
    2. Custom Mapping: Select New (type application name) or Existing (select application from pulldown), then select repositories from pulldowns under Projects. If an arrow is next to a name, you can click to select repositories within it. Click Add More to map repositories to multiple applications.
    Note: In GitLab
    Quick Start

    GitLab mapped to Polaris


    Quick Start

Customizing onboarding (optional)

  1. Assign Policies: Choose Issue Policies, Pull/Merge Request Policy, Component Policy and/or Test Schedule Policies. All the projects created with this import will be assigned these policies.
    Note: For pull request comments, create or assign a pull/merge request policy (see Pull/merge request policies) and enable "A new pull request is created or updated" in your test automation (see Event-Based Test Automation in Polaris for SCM Integrations).
  2. Assign Application Role: Grant users access to all of the applications and projects you create with an application level role (administrator, contributor, member, observer, or custom roles).
    • The application level roles you select are applied to all of the applications that are being created.
    • Double-check that the user being assigned has access to the repositories in your SCM provider.
  3. Under Integrations: Allows you to sync your SCM provider with Polaris and include non-default branches in your onboarding and sync. After onboarding is complete, you can manage these setting on the application level. See Synchronizing Polaris with your SCM Provider.
    1. Keep repositories and branches synchronized with SCM: Polaris will actively monitor repository updates, deletions, renames, and branch modifications, including updates, deletions, and renames, on the SCM provider. It will then implement the necessary changes to the corresponding Projects and Branches.
      Note: If this is selected without the additional branches option below, this will apply only to default branches.
      Note: Monitoring and updates for renaming is not supported for GitLab.

    2. Continue to import new repositories for above organization. For example, if you create a new repo in GitHub, Polaris will create a new project in Polaris. This is not available when you use custom matching during bulk onboarding.

    3. Import additional branches matching substrings. Default branches are automatically imported but this allows you to import/sync non-default branches.

      1. When selected, a new input field will appear. Enter substrings separated by commas (i.e. -release, -demo)

      2. When selected, a checkbox is available if you want to Continue to import new branches matching substrings after the initial integration. Polaris will monitor for branch creation events on all the repos under the organization/application that match the specified substrings.

  4. Click Import Repositories.
  5. On your Portfolio page, a progress bar with a percentage done will track your progress.

    If the onboarding fails, an email notification will be sent to the user who initiated the onboarding. Detailed information on any synchronization failures can be obtained in Audit Logs.

    Click Cancel to cancel the import. Any repository in the process of being imported at the time of cancellation will complete in the background after the cancel is accepted. Then all onboarding will be stopped immediately. For example, if you import ten repositories and cancel at 50%, five repositories would be imported and five repositories would not.

  6. You can now set up event-based test automation. See Event-Based Test Automation in Polaris for SCM Integrations.

SCM bulk onboarding projects into an application

See General Prerequisites before starting.
  1. On the Portfolio page, select an application by clicking on its name.
  2. On the Application page, select + Create > New Project(s) with SCM.
  3. Connect to your SCM:
    1. Select GitLab
    2. Enter the access token created in GitLab (see Prerequisites) under Repository Access Token.
      Note: The access token provided here will be used to complete the onboarding process and will be subject to rate limits enforced by GitLab.
    3. Click Connect.

      You should receive a Connection Successful message. If your connection test is unsuccessful, check the following:

      • Your network connection is stable.
      • Check the Repository Access Token to make sure it is accurate.
      • Check that the Repository Access Token is still valid and has not expired.
      • Check that you selected the correct provider for your source repository.
      • Check that you have authorized use of access token outside SSO (if applicable).
  4. Assign Policies (optional): Choose Issue Policies, Pull/Merge Request Policy, Component Policy and/or Test Schedule Policies. All the projects created with this import will be assigned these policies.
    Note: For pull request comments, create or assign a pull/merge request policy (see Pull/merge request policies) and enable "A new pull request is created or updated" in your test automation (see Event-Based Test Automation in Polaris for SCM Integrations).
  5. Repository Mapping: Select subgroups or repositories to import as new projects from pulldowns. If an arrow is next to a name, you can click to select repositories within it.
  6. Click Import Repositories.