Profile matching

Profile matching restricts access to specific Buildkite pipelines using claim-based rules. Match rules evaluate JWT claims from the Buildkite OIDC token against configured patterns, providing fine-grained access control.

Both pipeline profiles and organization profiles support the same matching syntax.

Match rule syntax

Match rules are optional. Omit the match field entirely to make a profile available to all pipelines.

When present, the match field contains a list of conditions that must all be satisfied (AND logic) for a pipeline to use the profile.

pipeline:
  profiles:
    - name: "release"
      match:
        - claim: build_branch
          value: "main"
        - claim: pipeline_slug
          valuePattern: ".*-prod"
      permissions: ["contents:write"]

Tip

Profiles offer a great deal of flexibility through claim-based matching, and this can be harmful if misused.

Establish clear rules for profile usage in your organization, and automate profile configuration checks to ensure compliance. For example, highlight additions or changes that broaden access, or those that affect profiles that are globally available (have no match rules).

Chinmina Bridge is deliberately unopinionated about the kinds of profiles that are appropriate, as this will vary per organization.

Exact matching

Use value for known strings. This is the fastest match type.

match:
  - claim: pipeline_slug
    value: "silk-prod" # Matches only "silk-prod"

Regex matching

Use valuePattern for flexible patterns. Supports RE2 regex syntax.

match:
  - claim: pipeline_slug
    valuePattern: ".*-release" # Matches any pipeline ending in "-release"

Anchoring

Patterns are automatically anchored to match the entire value. Chinmina wraps patterns with \A(?: and )\z around the pattern, forcing full-string matches. This prevents accidental partial matches.

For example:

1. Pattern prod matches only “prod”, not “not-prod”.
2. For partial matches: .*-prod matches “silk-prod” and “cotton-prod”.

Tip

While pattern matching allows flexibility, prefer exact matches when possible for simplicity.

Multiple conditions

All conditions must match (AND logic).

match:
  - claim: pipeline_slug
    valuePattern: "silk-.*"
  - claim: build_branch
    value: "main"
# Both conditions required

Available claims

Match rules can evaluate the following JWT claims from the Buildkite OIDC token:

Claim	Description
pipeline_slug	Pipeline’s slug
pipeline_id	Pipeline UUID
build_number	Build number (as string)
build_branch	Git branch name
build_tag	Git tag (if present)
build_commit	Git commit SHA
cluster_id, cluster_name	Cluster identifiers
queue_id, queue_key	Queue identifiers
agent_tag:NAME	Dynamic agent tags (e.g., agent_tag:queue)

Tip

_id claims are UUIDs and are not vulnerable to misuse through renaming. Use them if you need stable identifiers (this will depend on your organization’s pipeline management practices). They are not human-friendly when they appear in the profile however, so balance usability and stability as needed.

If you use the UUID and the string variant in the same profile, you get the security of one and the readability of the other.

Note also that if you rely on build_branch or build_tag, you will need to back this with GitHub controls on their usage for it to be effective.

Common patterns

Release pipelines only

match:
  - claim: pipeline_slug
    valuePattern: ".*-release"

Main branch only

match:
  - claim: build_branch
    value: "main"

Production pipelines on main

match:
  - claim: pipeline_slug
    valuePattern: "(silk|cotton)-prod"
  - claim: build_branch
    value: "main"

Specific cluster

match:
  - claim: cluster_name
    value: "production-us-east"

Tagged releases

match:
  - claim: build_tag
    valuePattern: "v[0-9]+\\.[0-9]+\\.[0-9]+" # v1.2.3 format

Troubleshooting

Profile returns 403 (access denied)

Pipeline doesn’t match profile conditions.

The HTTP response returns a generic “Forbidden” message. Check audit logs for token.attemptedPatterns to see which condition failed and the error field for detailed information. Verify the pipeline’s claim values match the configured patterns.

Profile returns 404 (unavailable: validation failed)

The profile failed validation and was excluded. Common causes:

• An invalid regex pattern in a match rule.
• An app naming a GitHub App that is not configured, or that is disabled.
• An empty app value.

The cause is recorded in the audit entry error field as profile "name" unavailable: <cause>.

It also appears under invalid_profiles in the warning log organization profile: some profiles failed validation and were ignored, or pipeline profile: some profiles failed validation and were ignored for pipeline profiles. The warning is emitted on every refresh while the profile remains invalid.

The caller sees only the generic message.

Correct the profile configuration to fix it. For a disabled app, fix the installation and restart the service; see disabled apps.

Profile matches too broadly

Pattern is overly permissive.

Review audit logs to identify unexpected matches. Make the pattern more specific. Patterns are automatically anchored, but .* can still match broadly. Replace .* with more specific patterns when possible.

Regex pattern rejected at startup

Invalid RE2 regex syntax.

Consult the RE2 syntax guide for supported patterns. Common issues:

• Backreferences are not supported
• Some Perl regex features are unavailable
• Escape special characters with backslash