Add documentation for new OIDC claims, default variables, and contexts (

#33719)

Co-authored-by: Lucas Costi <[email protected]>

content/actions/learn-github-actions/contexts.md

@@ -191,6 +191,9 @@ The `github` context contains information about the workflow run and the event t
 | `github.action_repository` | `string` | For a step executing an action, this is the owner and repository name of the action. For example, `actions/checkout`. |
 | `github.action_status` | `string` | For a composite action, the current result of the composite action. |
 | `github.actor` | `string` | {% ifversion actions-stable-actor-ids %}The username of the user that triggered the initial workflow run. If the workflow run is a re-run, this value may differ from `github.triggering_actor`. Any workflow re-runs will use the privileges of `github.actor`, even if the actor initiating the re-run (`github.triggering_actor`) has different privileges.{% else %}The username of the user that initiated the workflow run.{% endif %} |
+{%- ifversion actions-oidc-custom-claims %}
+| `github.actor_id` | `string` | {% data reusables.actions.actor_id-description %} |
+{%- endif %}
 | `github.api_url` | `string` | The URL of the {% data variables.product.prodname_dotcom %} REST API. |
 | `github.base_ref` | `string` | The `base_ref` or target branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is either `pull_request` or `pull_request_target`. |
 | `github.env` | `string` | Path on the runner to the file that sets environment variables from workflow commands. This file is unique to the current step and is a different file for each step in a job. For more information, see "[Workflow commands for {% data variables.product.prodname_actions %}](/actions/learn-github-actions/workflow-commands-for-github-actions#setting-an-environment-variable)." |
@@ -200,16 +203,25 @@ The `github` context contains information about the workflow run and the event t
 | `github.graphql_url` | `string` | The URL of the {% data variables.product.prodname_dotcom %} GraphQL API. |
 | `github.head_ref` | `string` | The `head_ref` or source branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is either `pull_request` or `pull_request_target`. |
 | `github.job` | `string` | The [`job_id`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_id) of the current job. <br /> Note: This context property is set by the Actions runner, and is only available within the execution `steps` of a job. Otherwise, the value of this property will be `null`. |
+{%- ifversion actions-oidc-custom-claims %}
+| `github.job_workflow_sha` | `string` | {% data reusables.actions.job-workflow-sha-description %} |
+{%- endif %}
 | `github.ref` | `string` | {% data reusables.actions.ref-description %} |
 {%- ifversion fpt or ghec or ghes > 3.3 or ghae > 3.3 %}
 | `github.ref_name` | `string` | {% data reusables.actions.ref_name-description %} |
 | `github.ref_protected` | `boolean` | {% data reusables.actions.ref_protected-description %} |
 | `github.ref_type` | `string` | {% data reusables.actions.ref_type-description %} |
 {%- endif %}
 | `github.path` | `string` | Path on the runner to the file that sets system `PATH` variables from workflow commands. This file is unique to the current step and is a different file for each step in a job. For more information, see "[Workflow commands for {% data variables.product.prodname_actions %}](/actions/learn-github-actions/workflow-commands-for-github-actions#adding-a-system-path)." |
-| `github.repository` | `string` | The owner and repository name. For example, `Codertocat/Hello-World`. |
-| `github.repository_owner` | `string` | The repository owner's name. For example, `Codertocat`. |
-| `github.repositoryUrl` | `string` | The Git URL to the repository. For example, `git://github.com/codertocat/hello-world.git`. |
+| `github.repository` | `string` | The owner and repository name. For example, `octocat/Hello-World`. |
+{%- ifversion actions-oidc-custom-claims %}
+| `github.repository_id` | `string` | {% data reusables.actions.repository_id-description %} |
+{%- endif %}
+| `github.repository_owner` | `string` | The repository owner's username. For example, `octocat`. |
+{%- ifversion actions-oidc-custom-claims %}
+| `github.repository_owner_id` | `string` | {% data reusables.actions.repository_owner_id-description %} |
+{%- endif %}
+| `github.repositoryUrl` | `string` | The Git URL to the repository. For example, `git://github.com/octocat/hello-world.git`. |
 | `github.retention_days` | `string` | The number of days that workflow run logs and artifacts are kept. |
 | `github.run_id` | `string` | {% data reusables.actions.run_id_description %} |
 | `github.run_number` | `string` | {% data reusables.actions.run_number_description %} |
@@ -224,6 +236,10 @@ The `github` context contains information about the workflow run and the event t
 | `github.token` | `string` | A token to authenticate on behalf of the GitHub App installed on your repository. This is functionally equivalent to the `GITHUB_TOKEN` secret. For more information, see "[Automatic token authentication](/actions/security-guides/automatic-token-authentication)."  <br /> Note: This context property is set by the Actions runner, and is only available within the execution `steps` of a job. Otherwise, the value of this property will be `null`. |{% ifversion actions-stable-actor-ids %}
 | `github.triggering_actor` | `string` | The username of the user that initiated the workflow run. If the workflow run is a re-run, this value may differ from `github.actor`. Any workflow re-runs will use the privileges of `github.actor`, even if the actor initiating the re-run (`github.triggering_actor`) has different privileges. |{% endif %}
 | `github.workflow` | `string` | The name of the workflow. If the workflow file doesn't specify a `name`, the value of this property is the full path of the workflow file in the repository. |
+{%- ifversion actions-oidc-custom-claims %}
+| `github.workflow_ref` | `string` | {% data reusables.actions.workflow-ref-description %} |
+| `github.workflow_sha` | `string` | {% data reusables.actions.workflow-sha-description %} |
+{%- endif %}
 | `github.workspace` | `string` | The default working directory on the runner for steps, and the default location of your repository when using the [`checkout`](https://github.com/actions/checkout) action. |
 
 ### Example contents of the `github` context

content/actions/learn-github-actions/variables.md

@@ -240,6 +240,9 @@ We strongly recommend that actions use variables to access the filesystem rather
 | `GITHUB_ACTION_REPOSITORY` | For a step executing an action, this is the owner and repository name of the action. For example, `actions/checkout`. |
 | `GITHUB_ACTIONS` | Always set to `true` when {% data variables.product.prodname_actions %} is running the workflow. You can use this variable to differentiate when tests are being run locally or by {% data variables.product.prodname_actions %}.
 | `GITHUB_ACTOR` | The name of the person or app that initiated the workflow. For example, `octocat`. |
+{%- ifversion actions-oidc-custom-claims %}
+| `GITHUB_ACTOR_ID` | {% data reusables.actions.actor_id-description %} |
+{%- endif %}
 | `GITHUB_API_URL` | Returns the API URL. For example: `{% data variables.product.api_url_code %}`.
 | `GITHUB_BASE_REF` | The name of the base ref or target branch of the pull request in a workflow run. This is only set when the event that triggers a workflow run is either `pull_request` or `pull_request_target`. For example, `main`. |
 | `GITHUB_ENV` | The path on the runner to the file that sets variables from workflow commands. This file is unique to the current step and changes for each step in a job. For example, `/home/runner/work/_temp/_runner_file_commands/set_env_87406d6e-4979-4d42-98e1-3dab1f48b13a`. For more information, see "[Workflow commands for {% data variables.product.prodname_actions %}](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable)." |
@@ -256,7 +259,13 @@ We strongly recommend that actions use variables to access the filesystem rather
 | `GITHUB_REF_TYPE` | {% data reusables.actions.ref_type-description %} |
 {%- endif %}
 | `GITHUB_REPOSITORY` | The owner and repository name. For example, `octocat/Hello-World`. |
+{%- ifversion actions-oidc-custom-claims %}
+| `GITHUB_REPOSITORY_ID` | {% data reusables.actions.repository_id-description %} |
+{%- endif %}
 | `GITHUB_REPOSITORY_OWNER` | The repository owner's name. For example, `octocat`. |
+{%- ifversion actions-oidc-custom-claims %}
+| `GITHUB_REPOSITORY_OWNER_ID` | {% data reusables.actions.repository_owner_id-description %} |
+{%- endif %}
 | `GITHUB_RETENTION_DAYS` | The number of days that workflow run logs and artifacts are kept. For example, `90`. |
 | `GITHUB_RUN_ATTEMPT` | A unique number for each attempt of a particular workflow run in a repository. This number begins at 1 for the workflow run's first attempt, and increments with each re-run. For example, `3`. |
 | `GITHUB_RUN_ID` | {% data reusables.actions.run_id_description %} For example, `1658821493`. |
@@ -267,6 +276,10 @@ We strongly recommend that actions use variables to access the filesystem rather
 | `GITHUB_STEP_SUMMARY` | The path on the runner to the file that contains job summaries from workflow commands. This file is unique to the current step and changes for each step in a job. For example, `/home/rob/runner/_layout/_work/_temp/_runner_file_commands/step_summary_1cb22d7f-5663-41a8-9ffc-13472605c76c`. For more information, see "[Workflow commands for {% data variables.product.prodname_actions %}](/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary)." |
 {%- endif %}
 | `GITHUB_WORKFLOW` | The name of the workflow. For example, `My test workflow`. If the workflow file doesn't specify a `name`, the value of this variable is the full path of the workflow file in the repository. |
+{%- ifversion actions-oidc-custom-claims %}
+| `GITHUB_WORKFLOW_REF` | {% data reusables.actions.workflow-ref-description %} |
+| `GITHUB_WORKFLOW_SHA` | {% data reusables.actions.workflow-sha-description %} |
+{%- endif %}
 | `GITHUB_WORKSPACE` | The default working directory on the runner for steps, and the default location of your repository when using the [`checkout`](https://github.com/actions/checkout) action. For example, `/home/runner/work/my-repo-name/my-repo-name`. |
 {%- ifversion actions-runner-arch-envvars %}
 | `RUNNER_ARCH` | {% data reusables.actions.runner-arch-description %} |

data/features/actions-oidc-custom-claims.yml

@@ -0,0 +1,7 @@
+# Reference: #8927
+# General versioning for new OIDC custom claims
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.9'
+  ghae: '>=3.9'

data/reusables/actions/actor_id-description.md

@@ -0,0 +1 @@
+The account ID of the person or app that triggered the initial workflow run. For example, `1234567`. Note that this is different from the actor username.

data/reusables/actions/job-workflow-sha-description.md

@@ -0,0 +1 @@
+For jobs using a reusable workflow, the commit SHA for the reusable workflow file.

data/reusables/actions/repository_id-description.md

@@ -0,0 +1 @@
+The ID of the repository. For example, `123456789`. Note that this is different from the repository name.

data/reusables/actions/repository_owner_id-description.md

@@ -0,0 +1 @@
+The repository owner's account ID. For example, `1234567`. Note that this is different from the owner's name.

data/reusables/actions/workflow-ref-description.md

@@ -0,0 +1 @@
+The ref path to the workflow. For example, `octocat/hello-world/.github/workflows/my-workflow.yml@refs/heads/my_branch`.

data/reusables/actions/workflow-sha-description.md

@@ -0,0 +1 @@
+The commit SHA for the workflow file.