docs(actions): Add OIDC repository custom properties claims (Public Preview) (#60122)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Steve-Glass <84886334+Steve-Glass@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: hubwriter <hubwriter@github.com>

Author: 4 people

assets/images/help/actions/actions-oidc-settings.png

@@ -75,7 +75,8 @@ The following example OIDC token uses a subject (`sub`) that references a job en
   "base_ref": "",
   "event_name": "workflow_dispatch",{% ifversion actions-OIDC-custom-claim-enterprise %}
   "enterprise": "avocado-corp",{% endif %}{% ifversion actions-OIDC-enterprise_id-claim %}
-  "enterprise_id": "2",{% endif %}
+  "enterprise_id": "2",{% endif %}{% ifversion oidc-custom-properties %}
+  "repo_property_workspace_id": "ws-abc123",{% endif %}
   "ref_type": "branch",
   "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
   "iss": "{% ifversion ghes %}https://HOSTNAME/_services/token{% else %}https://token.actions.githubusercontent.com{% endif %}",
@@ -113,6 +114,50 @@ For more information, see [AUTOTITLE](/actions/reference/openid-connect-referenc
 
 {% data variables.product.prodname_actions %} workflows can use OIDC tokens instead of secrets to authenticate with cloud providers. Many popular cloud providers offer official login actions that simplify the process of using OIDC in your workflows. For more information about updating your workflows with specific cloud providers, see [AUTOTITLE](/actions/how-tos/security-for-github-actions/security-hardening-your-deployments).
 
+{% ifversion oidc-custom-properties %}
+
+## Using repository custom properties as OIDC claims
+
+> [!NOTE]
+> This feature is currently in public preview and is subject to change.
+
+Organization and enterprise admins can include repository custom properties as claims in OIDC tokens. Once added, every repository in the organization or enterprise that has a value set for that custom property will automatically include it in its OIDC tokens, prefixed with `repo_property_`.
+
+This allows you to create granular access policies that bind directly to your repository metadata, reducing configuration drift and eliminating the need to duplicate governance information across multiple systems.
+
+### Prerequisites
+
+* Custom properties must already be defined at the organization or enterprise level.
+* You must be an organization admin or enterprise admin.
+
+### Adding a custom property to OIDC token claims
+
+To include a custom property in OIDC tokens, use the REST API or the settings UI for your organization or enterprise.
+
+**Using the settings UI:** Navigate to your organization or enterprise's Actions OIDC settings page to view and manage which custom properties are included in OIDC tokens.
+
+![Screenshot of the OIDC settings for an organization or enterprise.](/assets/images/help/actions/actions-oidc-settings.png)
+
+
+* **Using the REST API:** Send a `POST` request to add a custom property to the OIDC token claims for your organization:
+
+### Example OIDC token with a custom property
+
+The following example shows an OIDC token that includes the `workspace_id` custom property:
+
+```json
+{
+  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
+  "aud": "https://github.com/my-org",
+  "repository": "my-org/my-repo",
+  "repo_property_workspace_id": "ws-abc123"
+}
+```
+
+You can use the `repo_property_*` claims in your cloud provider's trust conditions to create flexible, attribute-based access control policies. For more information, see [AUTOTITLE](/actions/reference/openid-connect-reference#including-repository-custom-properties-in-oidc-tokens).
+
+{% endif %}
+
 ## OIDC support for {% data variables.product.prodname_dependabot %}
 
 {% data variables.product.prodname_dependabot %} can use OIDC to authenticate with private registries, eliminating the need to store long-lived credentials as repository secrets. With OIDC-based authentication, {% data variables.product.prodname_dependabot %} update jobs can dynamically obtain short-lived credentials from your cloud identity provider.

content/actions/concepts/security/openid-connect.md

@@ -68,6 +68,9 @@ The OIDC token includes the following claims.
 | `repository_id`| The ID of the repository from where the workflow is running.  |
 | `repository_owner`| The name of the organization in which the `repository` is stored.                   |
 | `repository_owner_id`| The ID of the organization in which the `repository` is stored.            |
+| {% ifversion oidc-custom-properties %} |
+| `repo_property_*`| Custom properties defined at the organization or enterprise level that are included as claims in the OIDC token, prefixed with `repo_property_`. For more information, see [AUTOTITLE](#including-repository-custom-properties-in-oidc-tokens).                  |
+| {% endif %} |
 | `run_id`| The ID of the workflow run that triggered the workflow.                   |
 | `run_number`| The number of times this workflow has been run.                   |
 | `run_attempt`| The number of times this workflow run has been retried.                    |
@@ -177,6 +180,9 @@ You can security harden your OIDC configuration by customizing the claims that a
 * You can customize values for {% ifversion ghec %}`issuer` or {% endif %}`audience` claims. See {% ifversion ghec %}[Customizing the `issuer` value for an enterprise](#customizing-the-issuer-value-for-an-enterprise) and {% endif %}[Customizing the `audience` value](#customizing-the-audience-value).
 * You can customize the format of your OIDC configuration by setting conditions on the subject (`sub`) claim that require JWT tokens to originate from a specific repository, reusable workflow, or other source.
 * You can define granular OIDC policies by using additional OIDC token claims, such as `repository_id` and `repository_visibility`. See [AUTOTITLE](/actions/concepts/security/openid-connect#understanding-the-oidc-token).
+{% ifversion oidc-custom-properties %}
+* You can include repository custom properties as claims in OIDC tokens, enabling attribute-based access control policies. See [AUTOTITLE](#including-repository-custom-properties-in-oidc-tokens).
+{% endif %}
 
 ### Customizing the `audience` value
 
@@ -214,6 +220,52 @@ After this setting is applied, the JWT will contain the updated `iss` value. In
 
 {% endif %}
 
+{% ifversion oidc-custom-properties %}
+
+### Including repository custom properties in OIDC tokens
+
+> [!NOTE]
+> This feature is currently in public preview and is subject to change.
+
+Organization and enterprise admins can select repository custom properties to include as claims in Actions OIDC tokens. Once a custom property is added to the OIDC configuration, every repository in the organization or enterprise that has a value set for that property will automatically include it in its OIDC tokens. The property name appears in the token prefixed with `repo_property_`.
+
+This allows you to create attribute-based access control (ABAC) policies in your cloud provider that bind directly to your repository metadata, reducing configuration drift and eliminating the need to manage separate access configuration for each repository.
+
+#### Prerequisites for including custom properties
+
+* Custom properties must already be defined at the organization or enterprise level.
+* You must be an organization admin or enterprise admin.
+* After adding a custom property to the OIDC configuration, all repositories in the organization or enterprise that have a value set for that property will automatically include it in their OIDC tokens.
+
+#### Adding a custom property to OIDC token claims
+
+You can manage which custom properties are included in OIDC tokens using the settings UI or the REST API.
+
+* **Using the settings UI:** 
+
+  Navigate to your organization's or enterprise's Actions OIDC settings to view and configure which custom properties are included in OIDC tokens.
+
+* **Using the REST API:** 
+
+  To add a custom property to your organization's OIDC token claims, send a `POST` request to:
+
+#### Example token with a custom property
+
+After a custom property is added to the OIDC configuration, repositories with a value set for that property will include it in their tokens. In the following example, the `workspace_id` custom property appears as `repo_property_workspace_id` in the token:
+
+```json
+{
+  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
+  "aud": "https://github.com/my-org",
+  "repository": "my-org/my-repo",
+  "repo_property_workspace_id": "ws-abc123"
+}
+```
+
+You can use these `repo_property_*` claims as conditions in your cloud provider's trust policy. For an example, see [Example: Filtering on a repository custom property](#example-filtering-on-a-repository-custom-property).
+
+{% endif %}
+
 ### Customizing the subject claims for an organization or repository
 
 To help improve security, compliance, and standardization, you can customize the standard claims to suit your required access conditions. If your cloud provider supports conditions on subject claims, you can create a condition that checks whether the `sub` value matches the path of the reusable workflow, such as `"job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"`. The exact format will vary depending on your cloud provider's OIDC configuration. To configure the matching condition on {% data variables.product.prodname_dotcom %}, you can use the REST API to require that the `sub` claim must always include a specific custom claim, such as `job_workflow_ref`. You can use the REST API to apply a customization template for the OIDC subject claim; for example, you can require that the `sub` claim within the OIDC token must always include a specific custom claim, such as `job_workflow_ref`. For more information, see [AUTOTITLE](/rest/actions/oidc).
@@ -368,6 +420,26 @@ This example demonstrates how to handle context value with `:`. For example, whe
 In your cloud provider's OIDC configuration, configure the `sub` condition to require that claims must include a specific value for `environment` and `repository_owner`. For example: `"sub": "environment:production%3Aeastus:repository_owner:octo-org"`.
 {% endif %}
 
+{% ifversion oidc-custom-properties %}
+
+#### Example: Filtering on a repository custom property
+
+This example template allows the `sub` claim to include a repository custom property claim. Custom properties included in OIDC tokens appear prefixed with `repo_property_` in the token, but the `include_claim_keys` value uses the full claim name as it appears in the token.
+
+{% data reusables.actions.use-request-body-api %}
+
+```json
+{
+   "include_claim_keys": [
+       "repo_property_workspace_id"
+   ]
+}
+```
+
+In your cloud provider's OIDC configuration, configure the `sub` condition to require that claims must include a specific value for `repo_property_workspace_id`. For example: `"sub": "repo_property_workspace_id:ws-abc123"`.
+
+{% endif %}
+
 #### Resetting organization template customizations
 
 This example template resets the subject claims to the default format. This template effectively opts out of any organization-level customization policy.

content/actions/reference/security/oidc.md

@@ -0,0 +1,3 @@
+versions:
+  fpt: '*'
+  ghec: '*'