From d3db7d3e25300ccac7335bea508514b61c24727f Mon Sep 17 00:00:00 2001 From: eric sciple Date: Wed, 23 Jun 2021 09:30:07 -0500 Subject: [PATCH] Detail where each context can be used within a workflow (#19900) * Detail where each context can be used within a workflow * tweak * Update cross-ref to new information This reusable is used in two articles: 'Context and expression syntax for GitHub Actions' and 'Environment variables'. In the first of these the current link point to the same section that the link is added to (which is not useful). In both articles I think the new section about context availability is a more appropriate link. * Update content/actions/reference/context-and-expression-syntax-for-github-actions.md Co-authored-by: hubwriter * Update content/actions/reference/context-and-expression-syntax-for-github-actions.md Co-authored-by: hubwriter * Update content/actions/reference/context-and-expression-syntax-for-github-actions.md Co-authored-by: hubwriter Co-authored-by: Matt Pollard Co-authored-by: hubwriter --- ...nd-expression-syntax-for-github-actions.md | 39 +++++++++++++++++++ .../using-context-or-environment-variables.md | 2 +- 2 files changed, 40 insertions(+), 1 deletion(-) diff --git a/content/actions/reference/context-and-expression-syntax-for-github-actions.md b/content/actions/reference/context-and-expression-syntax-for-github-actions.md index 6e0bbed14b76..a006b007a860 100644 --- a/content/actions/reference/context-and-expression-syntax-for-github-actions.md +++ b/content/actions/reference/context-and-expression-syntax-for-github-actions.md @@ -502,3 +502,42 @@ For example, consider an array of objects named `fruits`. ``` The filter `fruits.*.name` returns the array `[ "apple", "orange", "pear" ]` + +## Context availability + +Different contexts are available throughout a workflow run. For example, the `secrets` context may only be used at certain places within a job. + +In addition, some functions may only be used in certain places. For example, the `hashFiles` function is not available everywhere. + +The following table indicates where each context and special function can be used within a workflow. Unless listed below, a function can be used anywhere. + +| Path | Context | Special functions | +| ---- | ------- | ----------------- | +| concurrency | github | | +| env | github, secrets | | +| jobs.<job_id>.concurrency | github, needs, strategy, matrix | | +| jobs.<job_id>.container | github, needs, strategy, matrix | | +| jobs.<job_id>.container.credentials | github, needs, strategy, matrix, env, secrets | | +| jobs.<job_id>.container.env.<env_id> | github, needs, strategy, matrix, job, runner, env, secrets | | +| jobs.<job_id>.continue-on-error | github, needs, strategy, matrix | | +| jobs.<job_id>.defaults.run | github, needs, strategy, matrix, env | | +| jobs.<job_id>.env | github, needs, strategy, matrix, secrets | | +| jobs.<job_id>.environment | github, needs, strategy, matrix | | +| jobs.<job_id>.environment.url | github, needs, strategy, matrix, job, runner, env, steps | | +| jobs.<job_id>.if | github, needs | always, cancelled, success, failure | +| jobs.<job_id>.name | github, needs, strategy, matrix | | +| jobs.<job_id>.outputs.<output_id> | github, needs, strategy, matrix, job, runner, env, secrets, steps | | +| jobs.<job_id>.runs-on | github, needs, strategy, matrix | | +| jobs.<job_id>.services | github, needs, strategy, matrix | | +| jobs.<job_id>.services.<service_id>.credentials | github, needs, strategy, matrix, env, secrets | | +| jobs.<job_id>.services.<service_id>.env.<env_id> | github, needs, strategy, matrix, job, runner, env, secrets | | +| jobs.<job_id>.steps.continue-on-error | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles | +| jobs.<job_id>.steps.env | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles | +| jobs.<job_id>.steps.if | github, needs, strategy, matrix, job, runner, env, steps | always, cancelled, success, failure, hashFiles | +| jobs.<job_id>.steps.name | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles | +| jobs.<job_id>.steps.run | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles | +| jobs.<job_id>.steps.timeout-minutes | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles | +| jobs.<job_id>.steps.with | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles | +| jobs.<job_id>.steps.working-directory | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles | +| jobs.<job_id>.strategy | github, needs | | +| jobs.<job_id>.timeout-minutes | github, needs, strategy, matrix | | diff --git a/data/reusables/github-actions/using-context-or-environment-variables.md b/data/reusables/github-actions/using-context-or-environment-variables.md index 563f39603b0d..c1b33b040741 100644 --- a/data/reusables/github-actions/using-context-or-environment-variables.md +++ b/data/reusables/github-actions/using-context-or-environment-variables.md @@ -1,7 +1,7 @@ {% data variables.product.prodname_actions %} includes a collection of variables called _contexts_ and a similar collection of variables called _default environment variables_. These variables are intended for use at different points in the workflow: - **Default environment variables:** These variables exist only on the runner that is executing your job. For more information, see "[Default environment variables](/actions/reference/environment-variables#default-environment-variables)." -- **Contexts:** You can use most contexts at any point in your workflow, including when _default environment 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 more information, see "[Contexts](/actions/reference/context-and-expression-syntax-for-github-actions#contexts)." +- **Contexts:** You can use most contexts at any point in your workflow, including when _default environment 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 "[Context availability](/actions/reference/context-and-expression-syntax-for-github-actions#context-availability)." The following example demonstrates how these different types of environment variables can be used together in a job: