Permissions necessary to view VCS Roots via REST API

Question

What permissions are required to query VCS roots via the REST API?

Answer

When querying VCS roots through endpoints such as:

GET /app/rest/changes?locator=vcsRoot:(id:<VCS_ROOT_ID>),count:1

The account requires the View build configuration settings permission for the project where the VCS root is defined.

Option 1: Use the built-in Project Developer role

Assign the Project Developer role to the account for the relevant project, or for the Root project if access is required for all projects.

This role includes the required permission, but it also grants broader access, such as running builds, stopping builds, and viewing additional project details. However, it is the minimum suitable built-in role.

Option 2: Create a custom role

For least-privilege access, create a custom role containing only:

• View project and all parent projects
• View build configuration settings

Assign the role to the account on the project that owns the VCS root. Assigning it at the Root project level will also apply it to all projects.

This allows the account to query VCS roots and retrieve commit information without granting unnecessary build-management permissions.