Adding Azure DevOps Repositories

This guide includes steps for creating and configuring an Azure DevOps user personal access token, authorizing an Azure DevOps account with HackerOne Code, installing, and syncing repositories.

To complete this setup, a user designated as an organization owner for the relevant Azure DevOps organization will need to create an account with HackerOne’s Code application. See Step 4 ("Authorize and Sync Organization Projects"). They will also be responsible for configuring the personal access token in Step 8.

Step 1: Invite a HackerOne Code service user

HackerOne recommends creating a dedicated service user to run the Code service. While highly recommended for an optimal developer experience, this step is optional because the only requirement is that a personal access token is created (Step 2) by someone in the target organization with Basic permissions.

Some notable caveats for not using a dedicated service user:

• The user that supplies the PAT will have their name displayed when feedback is posted to pull requests, which would likely create a confusing experience for development teams. A new user will grant the ability to configure the posting user with a name like “HackerOne Code”.

• The user could change roles or leave the organization, which could cause a temporary outage until a new user can be identified to take their place. An IT-managed service user could be beneficial for this reason.

A user, whether a dedicated service user or an existing user, will be required to allow Code to post comments to your team’s pull requests via its personal access token. Ensure that this user has access to all repositories intended to be in scope of the HackerOne Code service. If possible, we recommend selecting "Add all" Project access so there's no disruption in service as coverage is needed. Control for restricting and enabling service for certain repositories will be available through the product dashboard (see Step 6).

Step 2: Creating a Personal Access Token

Whether using a dedicated service user (as recommended in Step 1) or using an existing user, a personal access token (PAT) will need to be created and later supplied (see Step 8) to complete setup of the Code service.

Note: Some users may not be capable of creating PATs for their organization. Review Azure DevOps documentation on prerequisites here.

From Azure DevOps, do the following to create a PAT to be used for HackerOne Code:

1. Navigate to User settings → Personal access tokens

2. Add “New Token”

3. Configure the following details:

   1. Name: “HackerOne Code” or similar

   2. Organization: Select Relevant Organization(s)

   3. Expiration: Select the expiration date that aligns with your organization’s policies. Azure DevOps will notify the owner of the PAT via email when it is nearing its expiration date.

   4. Scopes: Custom defined

      1. Code Read

      2. (Show all scopes) Pull Request Threads Read & Write

Required Permissions for the Personal Access Token

Required Permissions for Azure DevOps Integration

Code (read)

To enable our service to verify which projects are in scope, it requires the vso.code scope.

Pull Request Threads (Read & write)

To enable our service allow HackerOne engineers to read and interact with end users via pull request comments, it requires the vso.threads_full scope.

Step 3: Create a user account by authenticating with Azure DevOps

If it hasn't been done already, visit https://app.pullrequest.com/signup and create a user account by authenticating with Azure DevOps.

Note: Any user can create an account, but only organization owners for the relevant Azure DevOps organization can create the "owner" user account needed to install repositories and complete initial setup.

Step 4: Authorize and Sync Organization Projects

After signing up, you'll be prompted to authorize and connect with a version control hosting provider. Click the Sync with Azure DevOps option.

You'll then be prompted to authorize your Microsoft account with the HackerOne Code's PullRequest app, click Accept.

Required Permissions for Authenticating with Azure DevOps

Our integration adheres to the principle of least privilege, ensuring that it only has the access necessary to perform its intended function—providing valuable insights in pull request discussions. Here are the permissions we require and how we use them.

Required Permissions for Azure DevOps Integration Code (read) To enable our service to verify which projects are in scope, it requires the vso.code scope. Code (status)

The vso.code.status scope is required to create and get statuses associated with a pull request or an iteration. This is necessary for our system to post back results of automated scans and communicate workflow state to end-users in the Azure DevOps interface.

Project and team (read)

To keep project, repository and team information up-to-date in our dashboard tools, the service requires the vso.project Project and Team scope.

Graph (read)

Dashboard visibility and access to configuration settings in our dashboard are based on the end-user's permissions in Azure DevOps. Our system relies on the vso.graph Graph & Identity scope to ensure access within the service is based on access within Azure DevOps and is always up-to-date.

Step 5: Configuring scope of Azure DevOps projects

After authorizing with your Microsoft account, you'll be directed to a page to select the Azure DevOps Organization(s) in scope of service.

NOTE: Some Microsoft user accounts are treated like as Organization and will be shown in this list. It's likely you'll need to connect to your company's Organization instead of your Microsoft username (see below).

Be sure to select the Azure DevOps Organization your team uses rather than your Microsoft username.

Step 6: Select Repositories

You'll be asked to allow to access All repositories or Only select repositories.

If practical, we recommend selecting the All repositories option so you won't need to repeat this step each time your team creates a new repository. Note that new repository installations would require that the Azure DevOps user with the owner permissions return to complete these same steps to connect.

After you've made your selection, click the Connect button.

Step 7: View Repositories

Your repositories should now appear on the dashboard page when the Azure DevOps Organization is selected from the Organizations drop-down menu at the top-left portion of the screen.

Step 8: Configure the Posting User Personal Access Token (PAT)

From the Code dashboard, navigate to Settings → Owner Settings. Take the personal access token generated in Step 2 and enter it in the field under "Configure posting user personal access token" before saving.

Azure DevOps development teams are now ready to start running Code. Projects in scope of the Code service may now be selected to start by toggling them to “Auto” from Review Settings (Settings → Review Settings). Any repositories installed can be turned off or on at any time through this view.