On March 12, 2026, GitHub announced a seemingly technical update to its Actions platform: OpenID Connect (OIDC) tokens can now include custom properties defined at the repository level. While the original changelog post succinctly outlines the mechanics, this evolution represents a critical inflection point in DevOps security, cloud identity management, and the pursuit of eliminating long-lived secrets. This analysis delves deep into why this update matters far beyond the code snippet.
Key Takeaways
- Granular, Context-Aware Permissions: Cloud roles (AWS IAM, Azure Managed Identity, GCP Service Account) can now be assumed based on dynamic repository metadata (e.g.,
environment,cost-center,team), moving beyond static repository names. - Death Knell for Hardcoded Secrets: This advancement further obsoletes the need for storing static AWS_ACCESS_KEY_ID or AZURE_CREDENTIALS in GitHub Secrets, significantly reducing the attack surface.
- Policy as Code Enforcement: Infrastructure teams can encode governance rules directly into cloud IAM policies using these custom claims, enabling "shift-left" security for cloud resource access.
- Financial & Operational Accountability: Custom properties like
project-idorbusiness-unitallow for precise cloud cost attribution and audit trails tied to specific workflows and repositories.
Top Questions & Answers Regarding GitHub OIDC Custom Properties
What exactly changed, and how do I use it?
GitHub Actions' OIDC provider now includes any key-value pair defined in a repository's custom properties within the JSON Web Token (JWT) it issues to a running workflow. To use it, first set a custom property (like environment: production) in your repository settings. Then, in your cloud provider's trust policy (e.g., an AWS IAM AssumeRole policy), you can add a condition that checks for the presence and value of the repository_property_environment claim in the incoming JWT. This allows you to grant the production role only to workflows from repositories explicitly tagged as environment: production.
Why is this better than just using the repository name in the policy?
Using only the repository name (repo: owner/repo-name) is a binary, static control. Custom properties add a multidimensional, dynamic layer of context. A single repository might contain code for multiple environments (staging, production) or be used by different teams. A property like deploy-target: eu-prod-cluster allows you to grant specific cluster permissions based on intent, not just source. It also simplifies policy management—instead of updating IAM roles every time you create a new repo, you assign a property and let the existing, property-aware policy handle it.
Does this work with all major cloud providers?
Yes, in principle. The OIDC token with custom claims is generated by GitHub regardless of the cloud provider. The implementation burden lies in configuring the cloud provider's identity federation to understand and trust these custom claims. AWS IAM, Azure AD, and Google Cloud IAM all support condition-based access using claims in OIDC JWTs. You will need to update your respective trust relationship or entitlement policy to include conditions referencing the new repository_property_* claims. The syntax will vary by platform.
What are the most impactful use cases for this feature?
1. Multi-Environment Governance: Enforce that only workflows from repositories tagged environment: production can assume roles with production database write access.
2. Cost Allocation & Tagging: Automatically tag all cloud resources created by a workflow with the repository's cost-center property for precise showback/chargeback.
3. Compliance & Audit: For regulated industries, prove that access to sensitive data (e.g., PII) is gated by a compliance-tier: high property, creating an immutable audit trail in the JWT itself.
4. Ephemeral Environment Security: Dynamically generate properties (e.g., pr-number: 123) for pull request preview environments, granting short-lived, scoped access to isolated cloud resources.
The Evolution: From Static Secrets to Dynamic, Contextual Identity
The journey to this point reveals a clear trajectory in CI/CD security. Phase 1 was the era of hardcoded, long-lived secrets—a major vulnerability. Phase 2 introduced OIDC federation, replacing static keys with short-lived tokens automatically obtained by GitHub, a massive leap forward. However, these tokens were primarily authenticated based on a few static claims (repository, branch, environment).
This update marks Phase 3: Context-Aware Federation. The identity token now carries rich, user-defined metadata. This transforms the token from a simple "ID card" into a "smart badge" that communicates not just *who* you are (a GitHub Actions workflow), but *what you intend to do* and *under what constraints you're operating* (production, EU region, cost-center X). This context is critical for applying the Principle of Least Privilege (PoLP) dynamically at the moment of access.
Technical Deep Dive: Anatomy of the Enhanced JWT
Let's examine what's happening under the hood. Previously, a GitHub OIDC JWT for a workflow contained standard claims like repository, repository_owner, job_workflow_ref, and environment. With this update, for every custom property key-value pair defined on the repository, a new claim is injected in the format: repository_property_<key>: "<value>".
This structure allows cloud IAM policies to make incredibly granular decisions. An AWS IAM policy condition could now be: "StringEquals": {"token.actions.githubusercontent.com:repository_property_environment": "production"}. This is a cleaner, more scalable model than maintaining a sprawling list of specific repository ARNs in the trust policy.
Strategic Implications for Platform Engineering & Security Teams
1. The Rise of Property-Driven Governance
Platform engineering teams can now define a standardized set of required custom properties (e.g., `tier`, `data-classification`, `owner-email`) as part of their internal developer platform (IDP) contract. Compliance becomes automated—a deployment fails at the identity gate if the requisite properties aren't set, enforcing policy before a single resource is provisioned.
2. Bridging the Developer-Cloud Gap
Developers operate in the context of repositories and pull requests; cloud systems operate in the context of accounts, regions, and services. Custom properties act as a powerful translation layer. A developer tagging a repo with `region: europe-west1` doesn't need to know GCP project IDs; the OIDC trust policy maps that intent to the correct, restricted permissions.
3. Future-Proofing for AI-Driven DevOps
As AI agents begin to manage more of the CI/CD pipeline—automatically creating branches, running tests, and proposing deployments—they will need rich contextual data to make safe permission decisions. A structured property schema provides a machine-readable "bill of materials" for security intent, enabling autonomous systems to operate within guardrails.
Potential Challenges & Considerations
No advancement is without its trade-offs. Organizations must consider:
- Property Sprawl & Management: Without governance, teams may create inconsistent or conflicting properties. A central schema or enforcement via GitHub organization-level tools may be necessary.
- Initial Configuration Complexity: Setting up the OIDC trust relationship with custom claims is more complex than the initial OIDC setup. It requires careful coordination between DevOps, Cloud, and Security teams.
- Token Size Limitations: JWTs have size limits. While unlikely to be hit with typical properties, extremely verbose property values or a very large number of properties could theoretically cause issues.
- Audit Log Interpretation: Cloud audit logs will now contain JWT claims with custom properties. Security teams need to update their SIEM rules and dashboards to parse and alert on these new fields effectively.
Conclusion: A Paradigm Shift in Identity for Automation
GitHub's support for repository custom properties in OIDC tokens is more than a quality-of-life improvement. It is a foundational step towards a future where automated workflows carry verifiable, rich context about their purpose and constraints. This enables true zero-trust principles for CI/CD: never trust, always verify, and enforce minimum privilege based on dynamic needs, not static configurations.
For forward-thinking organizations, the immediate task is to pilot this feature with a high-impact, low-risk workflow. Define a clear property schema, update cloud IAM policies, and measure the reduction in overly permissive roles. The long-term payoff is a more secure, compliant, and agile software delivery lifecycle where identity is not a barrier, but an intelligent enabler of innovation.