Project-Level Access Control

Project-level access control allows you to isolate build data, cache entries, and acceleration features by project.

This ensures that sensitive build data is only visible to authorized users. It also prevents builds from one project from interfering with or accessing another project’s cache.

Prerequisites

Before configuring project-level access control, ensure you have:

Core Concepts

  • Projects: The basic unit of isolation. Each build must identify itself with a Project ID.

  • Project Groups: A collection of projects. Project groups function like roles. When you assign a project group to a user, you grant that user access to all projects in the group.

  • Build Isolation: Builds associated with Project A can only read cache entries created by other Project A builds.

Configuring Projects and Groups

To manage project access, you must first define the projects and the groups that contain them.

1. Create Projects

To create new projects, sign in with a user that has the Configure projects permission. You can’t create projects with the system user account.

  1. Navigate to Administration  Access control  Projects.

  2. Click Add project.

  3. Enter a Display Name and a Project ID.

    • Note: The Project ID is what developers must use in their build configuration (Gradle, Maven, etc.).

  4. Click Save.

 Projects can’t be deleted.

2. Create Project Groups

  1. On the same Projects tab, scroll to the Project Groups section.

  2. Click Add project group.

  3. Name the group (e.g., Android-Team-Projects) and select the projects to include.

  4. Click Save.

3. Assign Groups to Users

Project groups are assigned to users just like Roles:

  • Manual: Go to Administration  Access control  Users, edit a user, and select the project groups.

  • External: Map project groups from SAML or LDAP groups in the Identity Provider settings.

Applying the configuration updates the system services and may take several minutes to complete.
Keep your configuration safe
Before making major changes to system settings, consider exporting your current configuration via Administration  Import/export.
The Test Distribution Administration page shows usage data for all projects, regardless of a user’s access.

Develocity stores projects and project groups in the application database, rather than in the Develocity configuration file. Use database backups to restore projects and project groups just as you would users, access keys, and other app configuration data migrated with the database.

Enabling Enforcement

Develocity disables project-level access control by default. You can safely configure your projects and groups before turning on enforcement.

  1. Navigate to Administration  Access control  Projects.

  2. Check Enable project-level access control.

  3. Select Save.

Once you enable project-level access control, the "Allow data without an associated project" checkbox appears. This setting controls whether data without an associated project can be submitted to Develocity. It’s enabled by default, and we recommend keeping it that way at least until all of your builds specify a project ID.

 The "Allow data without an associated project" setting controls whether new data without project associations will be accepted by Develocity. The "Access all data without an associated project" permission controls users' access to that data, and the ability to submit it.
When project-level access control is enabled, builds that don’t specify a project will only be able to publish Build Scans and use Develocity features if the "Allow data without an associated project" setting is enabled.

Build Cache Requirement: To use project-level access control with the Build Cache, you must use Authenticated Build Access for authentication. Standard credential-based authentication isn’t supported for per-project cache isolation.
Changes to access control settings may take up to 20 minutes to propagate through the various components of Develocity.

Automated Management (API)

 Project configuration using the Develocity API is in beta, and may change without notice in future releases.

For high-scale environments, you can automate project and group creation using the Develocity API. This is ideal for syncing Develocity with an internal project registry.

For a complete list of project endpoints, see the Develocity API Manual. Managing projects via API requires the Configure projects permission.

Short-Lived Access Tokens

Develocity access keys are long-lived, creating risks if they’re leaked. To avoid this, users can use short-lived access tokens to authenticate with Develocity. See the appropriate manual for your build tool for information on how to generate and use access tokens. Access tokens are only valid for the Develocity instance that created them.

 Changing a Develocity instance’s hostname will cause all existing access tokens to become invalid.

Access tokens are signed JWTs, or JSON Web Tokens, and work like OAuth and OIDC access tokens. There’s no central directory of access tokens that manages their validity. Access token validity is based on their signature and associated signing key.

Revoking Access Tokens

If an access token is leaked, you can use the POST /api/auth/revoke-signing-keys endpoint to revoke all existing access tokens.

 See the API documentation for more details on the /api/auth/revoke-signing-keys endpoint.

Using this endpoint requires the Configure operational settings permission. It will delete any existing access token signing keys, and create a new one. This will invalidate all existing access tokens. This may take a few minutes to complete. It doesn’t affect access keys.

The signing keys used for access tokens are stored in Develocity’s database. They’re automatically rotated every seven days. This won’t cause any interruptions in authentication.

How to Use in Your Build

For enforcement to work, your build scripts must specify the Project ID. Refer to the specific build tool documentation for configuration details: