GitHub’s new support for repository custom properties inside Actions OIDC tokens is one of those changes that looks small until you have spent a year untangling cloud trust policies. On paper, the update is simple: admins can include repository custom properties as claims in OIDC tokens, and those values flow into cloud-provider trust policies without editing every workflow. In practice, that shifts identity design from enumerating repositories toward describing repository attributes.
That is a much better operating model. Allowlists age badly. Repository metadata, if governed well, scales. A platform team can finally say “all repositories marked production and payments get this role shape” without maintaining a fragile sprawl of one-off subject strings.
What actually changed
GitHub now lets organization and enterprise administrators add repository custom properties into Actions OIDC token claims. Once configured, repositories that have those property values set automatically emit claims prefixed with repo_property_. Those claims can then be referenced in AWS, Azure, GCP, or other trust policies that consume GitHub-issued OIDC tokens.
The key operational improvement is centralization. Instead of editing per-repository workflows just to express identity context, you can attach the context to the repository itself and let the token inherit it.
Why this matters more than the changelog makes it sound
Most GitHub-to-cloud federation setups begin as a relief from static credentials and then gradually become their own governance mess. Teams move from long-lived secrets to OIDC, which is good, but then pile policy logic into giant subject matches, repository-name patterns, environment exceptions, and special cases for every new service. Eventually the identity boundary is technically secretless and operationally miserable.
Custom property claims are interesting because they let you bind access to durable metadata instead of string parsing. That pushes organizations toward attribute-based access control rather than a long tail of implicit naming conventions.
My read is blunt: this feature is not mainly about convenience. It is about finally giving GitHub organizations a sane place to express deployment identity at scale.
Goal
Use repository custom properties in GitHub Actions OIDC tokens so cloud trust policies can target repository attributes consistently, with less per-workflow drift and less manual policy sprawl.
Prereqs
- GitHub organization or enterprise control over repository custom properties
- Existing GitHub Actions OIDC federation with at least one cloud provider
- A small, agreed metadata vocabulary such as environment, data sensitivity, business unit, or deployment tier
- A willingness to clean up bad repository metadata rather than automate around it forever
Steps
1) Pick attributes that mean something operationally. Do not start by mirroring org charts or ticketing fields just because they exist. The most useful custom properties are the ones your trust policies can actually reason about: environment class, production eligibility, compliance boundary, workload owner, or whether a repo is allowed to deploy infrastructure.
2) Normalize the values before you wire policy to them. If one team writes prod, another writes production, and a third writes prd, you have not built ABAC. You have built a prettier failure mode. Decide on allowed values and treat repository metadata like a contract.
# Example conceptual property set
environment = production
cloud_access = deploy
compliance_zone = regulated
service_tier = tier13) Add the properties to the OIDC token claim configuration. GitHub’s update adds both API support and a preview UI for doing this at repository, organization, or enterprise scope. The important design choice is scope: if you want consistency, configure claims where the metadata standard is owned, not where individual repos can quietly diverge.
4) Rewrite trust policies around attributes, not repository lists. This is where the real value appears. Instead of saying “these 57 repositories may assume role X,” define role X for repositories where repo_property_environment is production and repo_property_cloud_access is deploy. The exact syntax differs by provider, but the control idea is the same.
# Pseudocode trust condition
allow if
token.issuer == "https://token.actions.githubusercontent.com" and
token.repo_property_environment == "production" and
token.repo_property_cloud_access == "deploy"5) Separate “who can deploy” from “who owns the repo.” Repository ownership metadata is useful, but it should not be the only determinant of cloud privilege. Plenty of repositories are business-critical without needing broad infrastructure rights. Use this feature to sharpen privilege boundaries, not to flatten them.
6) Treat metadata changes as privileged events. Once claims affect trust policy, editing a repository property is functionally similar to editing access control. That means approvals, auditability, and ideally automation that detects unexpected value changes.
7) Roll out on a narrow slice first. Pick one cloud account or one deployment class and prove the governance loop before trying to retrofit the whole estate. ABAC is powerful, but it gets sloppy fast when organizations skip schema discipline.
One table worth keeping in the runbook
| Property | Meaning | Recommended default |
|---|---|---|
environment | Deployment target class | nonprod unless explicitly promoted |
cloud_access | Whether the repo may assume deployment roles | none |
compliance_zone | Regulatory or data boundary | standard |
service_tier | Operational criticality | tier3 |
Common pitfalls
- Using bad metadata to drive good policy. If the inputs are messy, the trust model will just become elegantly incorrect.
- Keeping the old allowlists forever. That defeats the point. Migrate in phases, but actually migrate.
- Letting any maintainer edit security-significant properties. If metadata controls privilege, metadata needs governance.
- Encoding too much meaning in one property. A single field like
classification=goldis less useful than a few explicit attributes with clear semantics. - Ignoring cloud-side policy readability. ABAC helps only if future operators can still understand why access was granted.
Verify
- Confirm the emitted OIDC token contains the expected
repo_property_*claims for a test repository. - Validate that a repository without the required property values cannot assume the cloud role.
- Change a non-production repository property to the production value only through the intended approval path and verify audit records exist.
- Review at least one cloud trust policy and ensure it reads like attribute logic, not like an accidental pile of repository names.
The best identity systems are boring because the intent is visible. That is what GitHub’s custom-property claims make possible. If your platform team uses them well, cloud trust starts looking less like an exception list and more like an operating model.