integrations / integrations/terraform-provider-github
Support use_immutable_subject on github_actions_repository_oidc_subject_claim_customization_template
- Dominant language
- Go
- Stars
- 1.2k
- Forks
- 1k
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 8
Description
## Problem
As of July 15, 2026, GitHub automatically uses immutable OIDC subject claims for newly created repositories (and repos that are renamed/transferred). The `sub` claim now includes both the owner ID and repository ID:
```
repo:my-org@123456/my-repo@789012:ref:refs/heads/main
```
GitHub also provides a **per-repository opt-in** via the REST API field `use_immutable_subject` on `PUT /repos/{owner}/{repo}/actions/oidc/customization/sub`:
```json
{
"use_default": false,
"include_claim_keys": ["repo"],
"use_immutable_subject": true
}
```
This allows repositories created **before** July 15, 2026 to adopt the immutable format without an org-wide change.
The underlying Go SDK (`google/go-github` v89) already carries both `UseImmutableSubject` and `SubClaimPrefix` on the `OIDCSubjectClaimCustomTemplate` struct:
```go
type OIDCSubjectClaimCustomTemplate struct {
UseDefault *bool `json:"use_default,omitempty"`
IncludeClaimKeys []string `json:"include_claim_keys,omitempty"`
UseImmutableSubject *bool `json:"use_immutable_subject,omitempty"`
SubClaimPrefix *string `json:"sub_claim_prefix,omitempty"`
}
```
However, the Terraform resource `github_actions_repository_oidc_subject_claim_customization_template` only exposes `repository`, `use_default`, and `include_claim_keys` — the `use_immutable_subject` and `sub_claim_prefix` fields are not wired through.
## Impact
Organizations that:
- Use Azure (or other cloud) federated identity credentials matching the OIDC `sub` claim
- Have a **mixed fleet** of repositories (some created before July 15, some after)
- Cannot enable immutable subjects org-wide (shared org with other teams)
...have no way to **per-repo opt in** to immutable subjects via Terraform. This forces them to either:
- Use out-of-band REST API calls (losing drift detection and state management)
- Switch to non-human-readable ID-only claims (`repository_id`) to get a uniform subject format
Both are workarounds for a missing Terraform capability.
## Proposed Solution
Add two optional attributes to the `github_actions_repository_oidc_subject_claim_customization_template` resource:
```hcl
resource "github_actions_repository_oidc_subject_claim_customization_template" "example" {
repository = "my-repo"
use_default = false
include_claim_keys = ["repo"]
# NEW: opt this repo into immutable subject claims
use_immutable_subject = true
# NEW: optional prefix for the sub claim
sub_claim_prefix = "custom-prefix"
}
```
### Implementation notes
The resource's `CreateOrUpdate` function already builds an `OIDCSubjectClaimCustomTemplate` struct and calls `SetRepoOIDCSubjectClaimCustomTemplate`. The change is:
1. Add `use_immutable_subject` (`TypeBool`, `Optional`, `Computed`) to the schema
2. Add `sub_claim_prefix` (`TypeString`, `Optional`, `Computed`) to the schema
3. Set both fields on the struct in `CreateOrUpdate` when provided
4. Read both fields back in `Read`
This should be ~12-15 lines of code change in the resource file.
## References
- [GitHub OIDC docs — Immutable subject claims](https://docs.github.com/en/actions/reference/security/oidc#immutable-subject-claims)
- [REST API — Set customization template for a repository](https://docs.github.com/en/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)
- Related SDK: `google/go-github` v89 `OIDCSubjectClaimCustomTemplate` struct in `github/actions_oidc.go`
## Willingness to contribute
I'm happy to submit a PR for this if the maintainers agree with the approach.
Contributor guide
Research direction
Start with the resource's CreateOrUpdate and Read functions, then inspect the OIDCSubjectClaimCustomTemplate struct in github/actions_oidc.go to confirm the SDK fields and JSON names. Add the two schema attributes and wire them through the resource; done means Terraform can configure and read back both values for a repository.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, go, terraform
- Domain
- devops, security
- Issue type
- Feature
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 74/100