idcat.toml.example

bind-address = "0.0.0.0:8080"
# Optional: serve HTTPS instead of HTTP using PEM-formatted certificate and key
# files. Change bind-address to the desired HTTPS port when enabling this block.
#
# [tls]
# certificate-file = "/var/run/secrets/idcat/tls.crt"
# private-key-file = "/var/run/secrets/idcat/tls.key"
key-source = "local"
private-key-directory = "/var/run/secrets/idcat"
# Optional: shared NATS connection used by any github-app that opts into
# publishing its webhook callbacks (see webhook-target below). The connection
# block is defined once here; each github-app decides whether to use it.
#
# [nats]
# endpoint = "nats://nats.example.com:4222"
# subject-base = "idcat.github.webhook"
# token-path = "/var/run/secrets/idcat/nats-token"

[[role]]
name = "kubernetes-default"
audience = "idcat"
issuer = "https://kubernetes.default.svc"

[role.claims]
sub = "system:serviceaccount:default:default"

[[role]]
name = "buildkite-deploy-idcat"
audience = "idcat"
issuer = "https://agent.buildkite.com"

[role.claims]
organization_slug = "my-buildkite-org"
pipeline_slug = "deploy-idcat"

[[role]]
name = "kubernetes-release-bot"
audience = "idcat"
issuer = "https://kubernetes.default.svc"

[role.claims]
sub = "system:serviceaccount:release:release-bot"

[[role]]
name = "github-workflow"
audience = "idcat"
issuer = "https://token.actions.githubusercontent.com"

[[github-app]]
name = "deployments"
app-id = 123456
secret-key = "deployments-private-key.pem"
allowed-roles = ["buildkite-deploy-idcat", "kubernetes-default"]
# Optional: publish this app's webhook callbacks to the shared [nats] connection.
# GitHub should be configured to POST deliveries to /webhook/deployments.
# webhook-target = "nats"
# Optional: validate incoming webhook deliveries using the shared secret
# configured on the GitHub App. The value is a path to a file containing that
# secret; deliveries whose X-Hub-Signature-256 header does not match are
# rejected. See
# https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
# webhook-validation-secret-file = "/var/run/secrets/idcat/deployments-webhook-secret"

[[github-app]]
name = "release-bot"
app-id = 234567
secret-key = "release-bot-private-key.pem"
allowed-roles = ["kubernetes-release-bot"]

[[installation-policy]]
github-app = "deployments"
repository = "myorg/alfa"
role = "github-workflow"

[installation-policy.required-claims]
repository = "myorg/gamma"

[installation-policy.permissions]
contents = "read"

[[installation-policy]]
github-app = "deployments"
repositories = ["myorg/beta", "myorg/delta"]
role = "github-workflow"

[installation-policy.required-claims]
repository = "myorg/epsilon"

[installation-policy.permissions]
contents = "write"

# `repository` and each `repositories` entry accepts a glob where `*` matches
# any characters (including `/`); so `"myorg/*"` matches any repo under
# `myorg/`, `"*"` matches any repo at all, and a literal like `"myorg/alfa"`
# matches exactly that repo. Use either `repository` or `repositories`, not both.
#
# `allow-self-access = true` makes idcat synthesise a `repository`
# required-claim equal to the `owner/repo` in the request URL, so the JWT
# must come from a workflow running in the same repo it asks a token for —
# semantically equivalent to writing `required-claims = { repository = <the
# URL's owner/repo> }` for every request that arrives. Pair it with a
# wildcard `repository` to express "any repo in this org, but a caller may
# only mint a token for its own repo".
[[installation-policy]]
github-app = "deployments"
repository = "myorg/*"
role = "github-workflow"
allow-self-access = true

[installation-policy.permissions]
contents = "read"

# The `[installation-policy.permissions]` table is required and must name at
# least one permission — it down-scopes what the minted token can DO, so
# there is no way to ask for the App's full installation permissions.
# Keys are GitHub permission names in snake_case (forwarded to GitHub verbatim
# — deliberately NOT kebab-case like the rest of this config); values are
# read/write/admin. Unrecognised names or values only emit a startup warning
# and are still forwarded; GitHub is authoritative. The token is always scoped
# to the requested repository, as for any installation-policy.
#
# Example — a CI workflow may mint a read-only token for its own repo:
[[installation-policy]]
github-app = "deployments"
repository = "myorg/*"
role = "github-workflow"
allow-self-access = true

[installation-policy.permissions]
contents = "read"
pull_requests = "read"

# An `[[owner-policy]]` grants an installation-wide token for an ACCOUNT rather
# than a token scoped to one repository. It is served by its own endpoint,
# `POST /installation-token/{github-app}/{owner}`, which names no repository —
# so the scope of the token you get always matches the path you asked for. Use
# it for account-level resources, such as org-owned packages, that a
# single-repository token cannot read.
#
# `owner` (or `owners = [...]`) is an account name or glob, never `owner/repo`.
# idcat resolves the installation from the account itself, trying
# `/orgs/{owner}/installation` and falling back to
# `/users/{owner}/installation`, so either kind of account works.
#
# `allow-self-access = true` synthesises a `repository_owner` required-claim
# equal to the owner in the request URL — the account-level counterpart of the
# `repository` claim an installation-policy constrains. It means "a caller may
# only mint a token for the account its own workflow belongs to". Note this is
# a weaker fence than the repository version: any workflow in the account
# qualifies.
#
# `[owner-policy.permissions]` is REQUIRED. An owner-wide token with no
# narrowed permissions is exactly what `allowed-roles` already grants, so idcat
# refuses to start rather than mint one from a policy.
#
# Example — any workflow in myorg may mint an org-wide read-only packages token:
[[owner-policy]]
github-app = "deployments"
owner = "myorg"
role = "github-workflow"
allow-self-access = true

[owner-policy.permissions]
packages = "read"