Profiles

Profile types

Two profile types are available:

Pipeline profiles - grant elevated permissions to the pipeline’s own repository
Organization profiles - provide access to other repositories across the organization

Configuration

Profiles are configured via a YAML file hosted in a GitHub repository. The location is specified using the GITHUB_ORG_PROFILE environment variable.

The configuration file contains both profile types:

pipeline:
  defaults:
    permissions: ["contents:read"]
  profiles:
    - name: "pr-commenter"
      permissions: ["contents:read", "pull_requests:write"]

organization:
  profiles:
    - name: "shared-plugins"
      repositories: ["plugin-1", "plugin-2"]
      permissions: ["contents:read"]

Automatic permissions

All tokens include metadata:read permission regardless of configured permissions. This mirrors GitHub’s default behavior for fine-grained tokens, where repository metadata access is always granted.

Configured permissions are additive: specifying ["contents:read"] results in a token with both metadata:read and contents:read.

Access control

Both profile types support claim-based matching to restrict which pipelines can use a profile. Match rules evaluate JWT claims from the Buildkite OIDC token, enabling fine-grained authorization based on pipeline identity, branch, cluster, or agent tags.

API access

Profiles are accessed via HTTP endpoints:

Pipeline profiles: /token/{profile} and /git-credentials/{profile}
Organization profiles: /organization/token/{profile} and /organization/git-credentials/{profile}

The special name default accesses pipeline default permissions.