Skip to main content

Integrate a new Azure DevOps Repos source

GitGuardian can integrate with Azure Repos in two different ways: at the instance level or at the organization/collection level.

note

In Azure Repos the wordings Organization and Collections refer to the same concept depending on the version of your Azure DevOps. In GitGuardian's dashboard, we use the wording Organization as it is the most common, but don't be embarrassed if you have Collections in your Azure Repos instance.

This integration supports Azure Repos for any version of Azure DevOps supporting the Rest API ≥ 4.1. This includes both Azure DevOps Services and Azure Devops Server 2019 and 2020.

info

Both integrations require a personal access token for GitGuardian to be able to access your Azure Repos organizations/collections for analysis.
You will need Owner or Manager rights in GitGuardian to set up an integration or customize your settings.

GitGuardian doesn't provide a real time monitoring of the Azure DevOps Repos. We run an initial scan when the organizations are installed, then you can launch a manual scan anytime you want from the perimeter page.

Setup#

Create a Personal Access Token#

tip

We highly recommend that you use a bot user in order to generate personal access tokens.

  1. Go to your “User setting” section on Azure DevOps.
  2. For Azure Repos Service, Dive into “Personal access tokens” section and create a new token. For Azure Repos Server, you first need to dive into "Security", and then select the Personal access tokens page on the left side bar.
  3. Set a name (ex: “gitguardian”).
  4. Select if you want to provide access for the current organization or for the entire instance.
  5. IMPORTANT: You must check the “Read” scope for Code.
  6. We recommend you set the expiration date to 1 year, this is the maximum allowed.
caution

Azure DevOps has a limit of 1 year maximum for the validity of a token. It means you'll have to renew the token if you want to keep the integration up and running.

The personal token enables GitGuardian to access your repos through your Azure DevOps permissions.

Azure Repos personal access token

caution

This integration doesn't monitor disabled repositories. If you include disabled repositories in your perimeter, they won't be checked and they will appear with the status Unknown.

Azure Repos disabled repo

Please refer to the Azure DevOps documentation for more information about personal access tokens.

Instance-level integration#

This integration mode will automatically monitor all projects and repositories on the instance. When a new project or a new repository is created on any organization, it will be automatically included in the perimeter by GitGuardian.

Requirements#

  • Azure DevOps Service or self-managed Azure DevOps Server: minimum assured compatible version 2019
  • A personal access token with Read scope for "Code".

Guidelines#

  1. Navigate to Settings > Workspace > Integrations.
  2. Click on Configure for Azure Repos.
  3. Click on Start for the instance-level option: "Monitor the entire Azure Repos instance"
    Azure Repos installation selection
  4. Submit your Azure Repos instance url, and the personal access token created.
    Azure Repos token form
    caution

    Azure instance URL must be prefixed with https://, instances without a secure connection won't be monitored. The URL used should be of type scheme+basename (eg: https://azuredevops.gitguardian.example).

  5. GitGuardian will start scanning your Azure Repos instance. You can view the projects and repositories monitored in your Azure Repos settings page by clicking on See my Azure Repos perimeter.

Troubleshooting#

  • You can submit new personal access tokens if you want to monitor more Azure Repos instances.
  • GitGuardian automatically detects if the Personal access token becomes invalid (by expiring or being revoked) and will send an email to notify you. All of your existing data will remain accessible.
  • In case you have a lot of repositories, they may take some time to show up on your perimeter.

Project-level integration#

This integration will only monitor organizations you select. When a new project is added to a monitored organization, it will be automatically added to the perimeter. However, new organizations added to the Azure Repos instance will not be automatically included to the GitGuardian perimeter.

Requirements#

  • Azure Devops Service or self-managed Azure DevOps Server/Data Center: minimum assured compatible version 2019
  • A personal access token with Read scope for "Code".

Guidelines#

  1. Navigate to Settings > Workspace > Integrations.
  2. Click on Configure for Azure Repos.
  3. Click on Start for the instance level option: "Monitor certain Azure Repos organizations only"
    Azure Repos installation selection
  4. Submit your Azure DevOps instance url and the personal access token created. If you're willing to install only one organization, submit also the name of this organization.
    Azure Repos token form
    caution

    Azure instance URL must be prefixed with https://, instances without a secure connection won't be monitored. The URL used should be of type scheme+basename (eg: https://azuredevops.gitguardian.example).

  5. GitGuardian will display the organization available for monitoring.
    Clicking Install, GitGuardian will access the organization and scan the content of the repositories.
    ADO install form
  6. You can view the projects and repositories monitored in your Azure Repos settings page by clicking on See my Azure Repos perimeter:

Troubleshooting#

  • You can submit new personal access tokens if you want to monitor more Azure Repos instances or organizations.
  • GitGuardian automatically detects if the Personal access token becomes invalid (by expiring or being revoked) and will send an email to notify you. All of your existing data will remain accessible.
  • In case you have a lot of repositories, they may take a short time to show up on your perimeter

Automatic historical scan#

By default, GitGuardian performs a historical scan for each new Azure Repos repository added to your perimeter.

You can deactivate this behavior in your Azure Repos settings if you are a Manager of the workspace.

Autoscan settings

Customize your monitored perimeter#

Once you have set up your Azure Repos integration, you have the possibility to configure which projects and repositories to monitor in the Azure Repos settings section of your workspace.

ADO perimeter

If you deselect a repository from your monitored perimeter, GitGuardian will not receive any commit for your futur scans.