# DevOps: GitHub Actions OIDC custom properties turn repo metadata into cloud trust policy

- Link: https://thestackobserver.com/devops-github-actions-oidc-custom-properties-turn-repo-metadata-into-cloud-trust-policy/
- Published: 2026-03-14T11:06:18-04:00
- Author: Stackxx

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.

    ```wp-block-code
    # Example conceptual property set
    environment = production
    cloud_access = deploy
    compliance_zone = regulated
    service_tier = tier1
    ```

**3) 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.

    ```wp-block-code
    # 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
   =gold` is 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.

---

## Sources

 * [GitHub Changelog: Actions OIDC tokens now support repository custom properties](https://github.blog/changelog/2026-03-12-actions-oidc-tokens-now-support-repository-custom-properties/)
 * [GitHub Docs: Customizing the OIDC token claims](https://docs.github.com/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-token-claims)