feat: support use_immutable_subject and sub_claim_prefix on repository OIDC subject claim template

[madriaanse377]

Summary

Wires use_immutable_subject and sub_claim_prefix — already present on go-github v89's OIDCSubjectClaimCustomTemplate struct — through to github_actions_repository_oidc_subject_claim_customization_template.

This lets a repository created before GitHub's July 15, 2026 immutable-subject-claims rollout opt in individually via Terraform, instead of requiring an org-wide toggle or an out-of-band REST call that Terraform can't track.

Changes

• use_immutable_subject (bool, optional, computed) and sub_claim_prefix (string, optional, computed) added to the resource schema
• Both fields wired into CreateOrUpdate and Read, following the existing GetOk + new(...) pattern already used elsewhere in this resource (include_claim_keys) and in sibling resources (e.g. resource_github_enterprise_actions_workflow_permissions.go)
• Docs (docs/resources/...md and its .tmpl source) and the example under examples/resources/... updated to cover both new arguments
• New acceptance test subtest asserting both fields round-trip correctly

Scoped to the repository-level resource only, matching the issue — the organization-level resource and this resource's Delete behavior are unchanged.

Closes #3548

Test plan

• Maintainer-run acceptance suite (TestAccGithubActionsRepositoryOIDCSubjectClaimCustomizationTemplate), since these require a live GitHub token this environment doesn't have
• Manual diff review against the existing use_default/include_claim_keys and can_approve_pull_request_reviews patterns for consistency

[github-actions]

👋 Hi, and thank you for this contribution!

This repo is maintained by GitHub and community members on a best-effort basis. We'll get to this as soon as we can.

You can help us prioritize by joining the discussion on open issues and PRs, sharing details on the changes you need, and reviewing other contributions.

---

_{🤖 This is an automated message.}

[RulerOf]

Just an FYI, I got bit by this today trying to resolve an issue with a new microservice's OIDC config. The API publishes use_immutable_subject but that value seems to lie.

In this older repo, the UI and API agree:

╰─❯ gh api /repos/BuyerQuest/redacted-old-repo/actions/oidc/customization/sub
{
  "use_default": true,
  "use_immutable_subject": false,
  "sub_claim_prefix": "repo:BuyerQuest/redacted-old-repo"
}

But this newer repo created after the compulsive switchover they disagree entirely:

gh api /repos/BuyerQuest/redacted-new-repo/actions/oidc/customization/sub
{
  "use_default": true,
  "use_immutable_subject": false,
  "sub_claim_prefix": "repo:BuyerQuest@123445689/redacted-new-repo@987654321"
}

I bring this up because what I wanted to do was inspect the true/false of use_immutable_subject from the data source to construct the sub, but it doesn't appear to be reliable via the API.

I'm using this as a workaround:

data "github_repository" "this" {
  full_name = "${local.github_org}/${var.github_repository}"
}

data "github_rest_api" "repo_oidc" {
  endpoint = "repos/${data.github_repository.this.full_name}/actions/oidc/customization/sub"
}

module "github_actions_role" {
  source  = "philips-labs/github-oidc/aws"
  version = "0.8.1"

  openid_connect_provider_arn = "arn:aws:iam::${data.aws_caller_identity.current.account_id}:oidc-provider/token.actions.githubusercontent.com"
  repo                        = data.github_repository.this.full_name
  role_name                   = "${local.name_prefix}-deploy"
  role_path                   = "/github-actions/"

  default_conditions = [
    "deny_pull_request",
  ]

  // GitHub reports the exact prefix it uses for this repository. This handles both the
  // name-based and immutable name@id formats without duplicating GitHub's selection logic.
  conditions = [
    {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:sub"
      values = [
        "${jsondecode(data.github_rest_api.repo_oidc.body).sub_claim_prefix}:environment:${github_repository_environment.this.environment}",
      ]
    },
  ]

Unless I'm mistaken, for the data source it may be worth computing it based on the qualities of sub_claim_prefix (e.g. an @ symbol in it anywhere means it should be true), or possibly disabling it until github fixes whatever the problem is.

[dekokun]

Not a maintainer, just helping with review triage, so this is a comment rather than a review.

Building on what @RulerOf found above: I checked the write side too, and sub_claim_prefix isn't just unreliable to read, it can't be set at all. It isn't a documented body parameter for PUT /repos/{owner}/{repo}/actions/oidc/customization/sub (it only appears in the GET response), and sending it is silently ignored. On a throwaway repo:

$ gh api -X PUT repos/OWNER/REPO/actions/oidc/customization/sub \
    --input - <<< '{"use_default": false, "include_claim_keys": ["repo"], "sub_claim_prefix": "test-prefix"}'
{}

$ gh api repos/OWNER/REPO/actions/oidc/customization/sub
{"use_default": false, "use_immutable_subject": false, "include_claim_keys": ["repo"],
 "sub_claim_prefix": "repo:OWNER@108519/REPO@1356554838"}

Same derived value before and after, exactly as in @RulerOf's examples.

That has two consequences for this PR specifically. The attribute is Optional + Computed, so a config value of "custom-prefix" against a read-back of the derived value should give "Provider produced inconsistent result after apply" - which means the example added to the docs wouldn't work as written. And the new acceptance subtest asserts sub_claim_prefix equals "custom-prefix", so I'd expect it to fail when someone runs it. Computed-only looks like the right shape for this field.

Separately, use_immutable_subject = false never reaches the API, because d.GetOk can't tell an explicit false from an unset bool. With a scratch test against a mocked API and use_immutable_subject = false in the config, the PUT body is:

{"use_default":false,"include_claim_keys":["repo"]}

The field is dropped. This matters because opting back out does work at the API level: on the same throwaway repo I set it to true and then back to false, and both took effect. Since the attribute is also Computed, the Read after apply writes true back into state, so someone trying to opt out via Terraform gets a silent no-op and a permanent diff.

There's an existing idiom for this in the repo: d.GetOkExists with a nolint comment, e.g. resource_github_repository_pages.go:193 ("necessary for bool fields") and resource_github_repository.go:636/645/1001.

I haven't run the acceptance tests.