EDI - Actions contexts (#56465)

Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com>

Author: jc-clark

content/actions/concepts/workflows-and-actions/contexts.md

@@ -0,0 +1,53 @@
+---
+title: Contexts
+shortTitle: Contexts
+intro: 'Learn about contexts in {% data variables.product.prodname_actions %}.'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghec: '*'
+type: overview
+topics:
+  - Actions
+  - Workflows
+---
+
+## About contexts
+
+{% data reusables.actions.actions-contexts-about-description %} Each context is an object that contains properties, which can be strings or other objects.
+
+{% data reusables.actions.context-contents %} For example, the `matrix` context is only populated for jobs in a [matrix](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix).
+
+You can access contexts using the expression syntax. For more information, see [AUTOTITLE](/actions/learn-github-actions/expressions).
+
+{% raw %}
+`${{ <context> }}`
+{% endraw %}
+
+{% data reusables.actions.context-injection-warning %}
+
+## Determining when to use contexts
+
+{% data variables.product.prodname_actions %} includes a collection of variables called _contexts_ and a similar collection of variables called _default variables_. These variables are intended for use at different points in the workflow:
+
+* **Default environment variables:** These environment variables exist only on the runner that is executing your job. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables).
+* **Contexts:** You can use most contexts at any point in your workflow, including when _default variables_ would be unavailable. For example, you can use contexts with expressions to perform initial processing before the job is routed to a runner for execution; this allows you to use a context with the conditional `if` keyword to determine whether a step should run. Once the job is running, you can also retrieve context variables from the runner that is executing the job, such as `runner.os`. For details of where you can use various contexts within a workflow, see [AUTOTITLE](/actions/reference/accessing-contextual-information-about-workflow-runs#context-availability).
+
+The following example demonstrates how these different types of variables can be used together in a job:
+
+{% raw %}
+
+```yaml copy
+name: CI
+on: push
+jobs:
+  prod-check:
+    if: ${{ github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Deploying to production server on branch $GITHUB_REF"
+```
+
+{% endraw %}
+
+In this example, the `if` statement checks the [`github.ref`](/actions/learn-github-actions/contexts#github-context) context to determine the current branch name; if the name is `refs/heads/main`, then the subsequent steps are executed. The `if` check is processed by {% data variables.product.prodname_actions %}, and the job is only sent to the runner if the result is `true`. Once the job is sent to the runner, the step is executed and refers to the [`$GITHUB_REF`](/actions/learn-github-actions/variables#default-environment-variables) variable from the runner.

content/actions/concepts/workflows-and-actions/index.md

@@ -10,6 +10,7 @@ children:
   - /variables
   - /avoiding-duplication
   - /about-custom-actions
+  - /contexts
   - /about-monitoring-workflows
   - /notifications-for-workflow-runs
   - /about-troubleshooting-workflows

content/actions/reference/accessing-contextual-information-about-workflow-runs.md renamed to content/actions/reference/contexts-reference.md

@@ -1,7 +1,7 @@
 ---
-title: Accessing contextual information about workflow runs
-shortTitle: Contexts
-intro: You can access context information in workflows and actions.
+title: Contexts reference
+shortTitle: Contexts reference
+intro: 'Find information about contexts available in {% data variables.product.prodname_actions %} workflows, including available properties, access methods, and usage examples.'
 redirect_from:
   - /articles/contexts-and-expression-syntax-for-github-actions
   - /github/automating-your-workflow-with-github-actions/contexts-and-expression-syntax-for-github-actions
@@ -11,27 +11,14 @@ redirect_from:
   - /actions/learn-github-actions/contexts
   - /actions/writing-workflows/choosing-what-your-workflow-does/contexts
   - /actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs
+  - /actions/reference/accessing-contextual-information-about-workflow-runs
 versions:
   fpt: '*'
   ghes: '*'
   ghec: '*'
 ---
 
-{% data reusables.actions.enterprise-github-hosted-runners %}
-
-## About contexts
-
-{% data reusables.actions.actions-contexts-about-description %} Each context is an object that contains properties, which can be strings or other objects.
-
-{% data reusables.actions.context-contents %} For example, the `matrix` context is only populated for jobs in a [matrix](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix).
-
-You can access contexts using the expression syntax. For more information, see [AUTOTITLE](/actions/learn-github-actions/expressions).
-
-{% raw %}
-`${{ <context> }}`
-{% endraw %}
-
-{% data reusables.actions.context-injection-warning %}
+## Available contexts
 
 | Context name | Type | Description |
 |---------------|------|-------------|
@@ -174,7 +161,7 @@ jobs:
 
 ## `github` context
 
-The `github` context contains information about the workflow run and the event that triggered the run. You can also read most of the `github` context data in environment variables. For more information about environment variables, see [AUTOTITLE](/actions/learn-github-actions/variables).
+The `github` context contains information about the workflow run and the event that triggered the run. You can read most of the `github` context data in environment variables. For more information about environment variables, see [AUTOTITLE](/actions/learn-github-actions/variables).
 
 {% data reusables.actions.github-context-warning %}
 {% data reusables.actions.context-injection-warning %}
@@ -877,3 +864,7 @@ jobs:
 ```
 
 {% endraw %}
+
+## Further reading
+
+* [AUTOTITLE](/actions/concepts/workflows-and-actions/contexts)

content/actions/reference/index.md

@@ -12,7 +12,7 @@ children:
   - /workflow-commands-for-github-actions
   - /variables-reference
   - /evaluate-expressions-in-workflows-and-actions
-  - /accessing-contextual-information-about-workflow-runs
+  - /contexts-reference
   - /metadata-syntax-for-github-actions
   - /actions-limits
   - /dockerfile-support-for-github-actions