Workload Identity

Starts With, Ends With, and Contains compare the requirement string against the claim value as literal text. The boundary character is not a special or stripped token. It is the character that bounds a segment in the claim’s own format, matched as part of the required string. For example, the / in a Jenkins job URL and the @ in a GitHub workflow ref both follow from the claim’s own format. Any character can serve as the boundary as long as it naturally ends a segment in the real claim value.

Claim requirements decide which workloads a rule admits, so build them from values that a workload cannot choose for itself.

On a shared issuer such as GitHub.com or GitLab.com, any repository can request a token with your audience. Always require your organization or namespace there, and require it on its ID claim, such as repository_owner_id or namespace_id, rather than on its name. After a rename or deletion, someone else can register the freed name, and a requirement on the name then admits their workloads. A single-tenant issuer, such as Jenkins or a self-managed GitLab instance, serves your own CI system and no one else. It does not need this requirement, because it issues tokens to your own workloads alone.

Whoever can create repositories, branches, or jobs chooses the other names in a token. Those names are the repository, project path, branch or ref, workflow path, or Jenkins job URL. Prefer an ID claim where one exists. An Equals requirement on a name is an acceptable trade for readability when the same rule pins the organization by ID. That is safe because no one outside your organization can create names under it. A branch requirement can be no stronger than the control over who can push to that branch, so protect the branch in your CI provider.

Use Equals wherever you can. Starts With, Ends With, Contains, and Regular Expression accept any value crafted to fit them. For example, a repository Ends With /acme-app requirement also matches evil/acme-app, a repository anyone can create. A Regular Expression must match the entire claim value, and . in it matches any character, so escape a literal dot as \..

The audience the CI job requests becomes the token’s aud claim, and it must match the rule’s Audience character for character. Develocity does not normalize case, scheme, or a trailing slash, so a token issued for https://develocity.example.com/ does not match a rule whose Audience is https://develocity.example.com.

If your CI provider lets the job choose the audience, use your Develocity server URL. Give the scheme and hostname, include the port only if it is not the default, and omit any path or trailing slash. Do not rely on the audience a provider assigns when the job requests none. GitHub Actions, for example, defaults to the repository owner URL, which other services that trust your organization’s tokens also accept.

If the provider sets a fixed audience, enter the value its tokens carry as the rule’s Audience.

The audience stops anyone from replaying a token issued for another service against Develocity. It does not limit who can get a token: on GitHub.com or GitLab.com, any repository can request one with your audience. Claim requirements are what restrict access, as Choosing Claim Requirements explains.

Develocity displays an admin notice when it cannot refresh signing keys from a configured issuer. Develocity fetches signing keys (JWKS) from each configured issuer and retries every minute if the fetch fails. Develocity shows the admin notice once an issuer has been unreachable for 15 minutes. After 24 hours without a successful refresh, Develocity drops the cached keys and token validation for that issuer fails, breaking any builds that use it.

To diagnose:

Common causes:

Fix the issuer URL or network path, or add the CA certificate to Develocity’s trusted store if TLS is the cause. Develocity retries every minute and clears the notice once a fetch succeeds.

Sometimes a build fails to authenticate even though the issuer’s JWKS status is healthy and the claim requirements look correct. In that case, compare the token’s audience with the rule’s. Develocity skips a rule whose Audience does not appear in the token’s aud claim. Develocity rejects a token that matches no rule as an invalid credential. The error does not say whether the audience or a claim requirement failed.

Common causes:

To see what the token carries, decode its payload in the CI job and print the aud claim alone, never the token itself. Change whichever side is wrong so the two strings are identical, following Choosing the Audience Value.

Trusted artifact isolation decides what a build can read and write from the levels on the rule its credentials matched. A mistake in those levels therefore surfaces as a cache problem rather than an authentication one. Three symptoms share that shape: a build that starts missing every cache key, a cache response of 409 Conflict carrying an X-Cache-Isolation-Conflict header, and a job whose Artifact Cache summary reports zero trusted entries. In each, the token validated and the rule matched, and the isolation levels alone are wrong.

Diagnose these from Trusted Artifact Isolation, which gives the cause and the remedy for each.