Synchronizing Polaris with your SCM Provider

Overview

Polaris provides seamless synchronization with your SCM provider. These settings can be enabled either during the onboarding process or for an existing organization or application. You can customize these settings at both the organization and application levels.

These settings allow automatic tracking and monitoring which will:

  • Onboard a repository created on the SCM provider to Polaris which will create a project with a default branch. When onboarding a branch from the SCM provider, Polaris will create a corresponding branch for the specified project.
  • Update a project or branch name whenever the repository or branch name is modified on the SCM provider.
  • Update the default branch whenever changes are made to it on the SCM provider.
  • Delete a project and its associated branches when the repository is deleted from the SCM Provider.
  • Delete a branch when it is deleted on the SCM Provider.
  • Import and sync non-default branches by using matching substrings (default branches are automatically included).
Note: Editing or deleting synced projects and branches in Polaris is not allowed.

Prerequisites and limitations

  • GitHub or GitHub Enterprise.
  • On-prem deployments will need to allow IPs for Polaris.
  • An SCM integration that supports synchronization (see Integrate Multiple SCM Repositories for more information).
  • When integrating the repository, the personal access token you create needs the scope to include the admin:org_hook permission. This is required to create a webhook in GitHub so that Polaris can start listening to the events. See Integrate Multiple SCM Repositories.
  • Limitation due to type of subscription:
    • For an application subscription you can auto onboard the number of projects based on the quantity purchased. One example would be only ten branches per project being auto onboarded based on the selected criteria.
    • If you have a concurrent entitlement, there is no limitation on project and branches.

The following roles can manage synchronization:

  • Organization Admin
  • Organization Application Manager
  • Application Admin (only for applications they are the admin for)

Synchronizing Polaris with your SCM Provider

  1. Select the appropriate level to sync.

    You can configure synchronization at two levels:

    • During onboarding: Use either Automatic or Custom Matching. Custom matching does not allow for importing new repositories for the whole organization.
    • Application: Select Application name > Settings > Integrations.

    Mapping bulk import
  2. Select Edit (if existing integration).
  3. Select appropriate boxes.
    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.
      Important: If this is selected without the additional branches option below, this will apply only to default branches.
    2. Continue to import new repositories for above organization: For example, if you create a new repository 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 (for example: -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.
      Note: Organization Administrators will receive failure notifications for project/branch creation/update operations as part of auto onboarding. Project/branch create/update/delete events can be found in audit logs.
      CAUTION: After synchronization is disabled, projects and branches can be edited as usual at the user's discretion. This is not advised if synchronization will be enabled again later.
  4. Select Save or Import Repository.
    Your synchronization settings are saved and applied.
  5. Now, you can set up event-based test automation.
    See Event-Based Test Automation in Polaris for SCM Repositories for more information.