integrations / integrations/terraform-provider-github

Support use_immutable_subject on github_actions_repository_oidc_subject_claim_customization_template

Open Beginner friendly
#3,548 1 comment 44 reactions 0 assignees View on GitHub
r/repo_oidc_subject_claim_customization_tmpl Status: Triage Type: Feature
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.