1
0
mirror of synced 2026-01-10 09:02:35 -05:00

Merge branch 'main' into jules-4510

This commit is contained in:
Jules Parker
2021-11-24 15:27:09 +01:00
committed by GitHub
8 changed files with 199 additions and 53 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 70 KiB

View File

@@ -18,12 +18,6 @@ topics:
{% data reusables.actions.enterprise-beta %}
{% data reusables.actions.enterprise-github-hosted-runners %}
{% note %}
**Note:** Reusable workflows are currently in beta and subject to change.
{% endnote %}
## About reusable workflows
Rather than copying and pasting deployment jobs from one workflow to another, you can create a reusable workflow that performs the deployment steps. A reusable workflow can be used by another workflow if it meets one of the access requirements described in "[Reusing workflows](/actions/learn-github-actions/reusing-workflows#access-to-reusable-workflows)."

View File

@@ -5,9 +5,9 @@ intro: Learn how to avoid duplication when creating a workflow by reusing existi
miniTocMaxHeadingLevel: 3
versions:
fpt: '*'
ghec: '*'
ghes: '>=3.4'
ghae: issue-4757
ghec: '*'
type: how_to
topics:
- Workflows
@@ -17,41 +17,59 @@ topics:
{% data reusables.actions.enterprise-github-hosted-runners %}
{% data reusables.actions.ae-beta %}
{% note %}
**Note:** Reusable workflows are currently in beta and subject to change.
{% endnote %}
## Overview
Rather than copying and pasting from one workflow to another, you can make workflows reusable. You and anyone with access to the reusable workflow can then call the reusable workflow from another workflow.
Reusing workflows avoids duplication. This makes workflows easier to maintain and allows you to create new workflows more quickly by building on the work of others, just as you do with actions. Workflow reuse also promotes best practice by helping you to use workflows that are well designed, have already been tested, and have been proved to be effective. Your organization can build up a library of reusable workflows that can be centrally maintained.
The diagram below shows three build jobs on the left of the diagram. After each of these jobs completes successfully a dependent job called "Deploy" runs. This job calls a reusable workflow that contains three jobs: "Staging", "Review", and "Production." The "Production" deployment job only runs after the "Staging" job has completed successfully. Using a reusable workflow to run deployment jobs allows you to run those jobs for each build without duplicating code in workflows.
![Diagram of a reusable workflow for deployment](/assets/images/help/images/reusable-workflows-ci-cd.png)
A workflow that uses another workflow is referred to as a "caller" workflow. The reusable workflow is a "called" workflow. One caller workflow can use multiple called workflows. Each called workflow is referenced in a single line. The result is that the caller workflow file may contain just a few lines of YAML, but may perform a large number of tasks when it's run. When you reuse a workflow, the entire called workflow is used, just as if it was part of the caller workflow.
If you reuse a workflow from a different repository, any actions in the called workflow run as if they were part of the caller workflow. For example, if the called workflow uses `actions/checkout`, the action checks out the contents of the repository that hosts the caller workflow, not the called workflow.
When a reusable workflow is triggered by a caller workflow, the `github` context is always associated with the caller workflow. The called workflow is automatically granted access to `github.token` and `secrets.GITHUB_TOKEN`. For more information about the `github` context, see "[Context and expression syntax for GitHub Actions](/actions/reference/context-and-expression-syntax-for-github-actions#github-context)."
### Reusable workflows and workflow templates
Workflow templates allow everyone in your organization who has permission to create workflows to do so more quickly and easily. When people create a new workflow, they can choose a template and some or all of the work of writing the workflow will be done for them. Inside workflow templates, you can also reference reusable workflows to make it easy for people to benefit from reusing centrally managed workflow code. If you use a tag or branch name when referencing the reusable workflow then you can ensure that everyone who reuses that workflow will always be using the same YAML code. However, if you reference a reusable workflow by a tag or branch, be sure that you can trust that version of the workflow. For more information, see "[Security hardening for {% data variables.product.prodname_actions %}](/actions/security-guides/security-hardening-for-github-actions#reusing-third-party-workflows)."
For more information, see "[Creating workflow templates](/actions/learn-github-actions/creating-workflow-templates)."
## Access to reusable workflows
A reusable workflow can be used by another workflow if any of the following is true:
A reusable workflow can be used by another workflow if {% ifversion ghes or ghec or ghae %}any{% else %}either{% endif %} of the following is true:
* Both workflows are in the same repository.
* The called workflow is stored in a public repository.
* The called workflow is stored in an internal repository and the settings for that repository allow it to be accessed. For more information, see "[Managing {% data variables.product.prodname_actions %} settings for a repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-an-internal-repository)."
* The called workflow is stored in a public repository.{% ifversion ghes or ghec or ghae %}
* The called workflow is stored in an internal repository and the settings for that repository allow it to be accessed. For more information, see "[Managing {% data variables.product.prodname_actions %} settings for a repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-an-internal-repository)."{% endif %}
## Using runners
### Using GitHub-hosted runners
{% ifversion fpt or ghes or ghec %}
The assignment of {% data variables.product.prodname_dotcom %}-hosted runners is always evaluated using only the caller's context. Billing for {% data variables.product.prodname_dotcom %}-hosted runners is always associated with the caller. The caller workflow cannot use {% data variables.product.prodname_dotcom %}-hosted runners from the called repository. For more information, see "[About {% data variables.product.prodname_dotcom %}-hosted runners](/actions/using-github-hosted-runners/about-github-hosted-runners)."
{% endif %}
{% ifversion ghae %}
The assignment of {% data variables.actions.hosted_runner %}s is always evaluated using only the caller's context. Billing for {% data variables.actions.hosted_runner %}s is always associated with the caller. The caller cannot use {% data variables.actions.hosted_runner %}s from the called repository. For more information, see "[About {% data variables.actions.hosted_runner %}s](/github-ae@latest/actions/using-github-hosted-runners/about-ae-hosted-runners)."
{% endif %}
### Using self-hosted runners
Called workflows can access self-hosted runners from caller's context. This means that a called workflow can access self-hosted runners that are:
* In the caller repository
* In the caller repository's organization{% ifversion ghes or ghec or ghae %} or enterprise{% endif %}, provided that the runner has been made available to the caller repository
## Limitations
* Reusable workflows can't call other reusable workflows.
* Reusable workflows stored within a private repository can only be used by workflows within the same repository.
* Any environment variables set in an `env` context defined at the workflow level in the caller workflow are not propagated to the called workflow. For more information about the `env` context, see "[Context and expression syntax for GitHub Actions](/actions/reference/context-and-expression-syntax-for-github-actions#env-context)."
The following limitations will be removed when workflow reuse moves out of beta:
* You can't set the concurrency of a called workflow from the caller workflow. For more information about `jobs.<job_id>.concurrency`, see "[Workflow syntax for GitHub Actions](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idconcurrency)."
* Outputs generated by a called workflow can't be accessed by the caller workflow.
## Creating a reusable workflow
@@ -64,30 +82,55 @@ on:
workflow_call:
```
You can define inputs and secrets, which can be passed from the caller workflow and then used within the called workflow. The following example, from a reusable workflow, defines two inputs (called "ring" and "environment") and one secret (called "token"):
### Using inputs and secrets in a reusable workflow
```yaml
on:
workflow_call:
inputs:
ring:
description: 'Identifier for the target deployment ring'
default: 'ring-0'
required: false
type: string
environment:
required: false
type: string
secrets:
token:
required: false
```
You can define inputs and secrets, which can be passed from the caller workflow and then used within the called workflow. There are three stages to using an input or a secret in a reusable workflow.
For details of the syntax for defining inputs and secrets, see [on.workflow_call.inputs](/actions/reference/workflow-syntax-for-github-actions#onworkflow_callinputs) and [on.workflow_call.secrets](/actions/reference/workflow-syntax-for-github-actions#onworkflow_callsecrets).
1. In the reusable workflow, use the `inputs` and `secrets` keywords to define inputs or secrets that will be passed from a caller workflow.
{% raw %}
```yaml
on:
workflow_call:
inputs:
username:
required: true
type: string
secrets:
envPAT:
required: true
```
{% endraw %}
For details of the syntax for defining inputs and secrets, see [`on.workflow_call.inputs`](/actions/reference/workflow-syntax-for-github-actions#onworkflow_callinputs) and [`on.workflow_call.secrets`](/actions/reference/workflow-syntax-for-github-actions#onworkflow_callsecrets).
1. Reference the input or secret in the reusable workflow.
{% raw %}
```yaml
jobs:
reusable_workflow_job:
runs-on: ubuntu-latest
environment: production
steps:
- uses: ./.github/actions/my-action@v1
with:
username: ${{ inputs.username }}
token: ${{ secrets.envPAT }}
```
{% endraw %}
In the example above, `envPAT` is an environment secret that's been added to the `production` environment. This environment is therefore referenced within the job.
{% note %}
**Note**: Environment secrets are encrypted strings that are stored in an environment that you've defined for a repository. Environment secrets are only available to workflow jobs that reference the appropriate environment. For more information, see "[Using environments for deployment](/actions/deployment/targeting-different-environments/using-environments-for-deployment#environment-secrets)."
{% endnote %}
1. Pass the input or secret from the caller workflow.
{% indented_data_reference reusables.actions.pass-inputs-to-reusable-workflows spaces=3 %}
### Example reusable workflow
This reusable workflow file named `workflow-B.yml` (we'll refer to this later) takes an input string and a secret from the caller workflow and uses them in an action.
This reusable workflow file named `workflow-B.yml` (we'll refer to this later in the [example caller workflow](#example-caller-workflow)) takes an input string and a secret from the caller workflow and uses them in an action.
{% raw %}
```yaml{:copy}
@@ -131,16 +174,7 @@ You can call multiple workflows, referencing each in a separate job.
### Passing inputs and secrets to a reusable workflow
Use the `with` keyword in a job to pass named inputs to the called workflow. Use the `secrets` keyword to pass named secrets. The inputs and secrets you pass must be defined in the called workflow. For inputs, the data type of the input value must match the type specified for that input in the called workflow (boolean, number, or string).
{% raw %}
```yaml
with:
username: mona
secrets:
token: ${{ secrets.TOKEN }}
```
{% endraw %}
{% data reusables.actions.pass-inputs-to-reusable-workflows%}
### Supported keywords for jobs that call a reusable workflow
@@ -167,7 +201,7 @@ When you call a reusable workflow, you can only use the following keywords in th
### Example caller workflow
This workflow file calls two workflow files. The second of these, `workflow-B.yml` (shown above), is passed an input, `username`, and a secret, `token`.
This workflow file calls two workflow files. The second of these, `workflow-B.yml` (shown in the [example reusable workflow](#example-reusable-workflow)), is passed an input (`username`) and a secret (`token`).
{% raw %}
```yaml{:copy}
@@ -191,6 +225,82 @@ jobs:
```
{% endraw %}
## Using outputs from a reusable workflow
A reusable workflow may generate data that you want to use in the caller workflow. To use these outputs, you must specify them as the outputs of the reusable workflow.
The following reusable workflow has a single job containing two steps. In each of these steps we set a single word as the output: "hello" and "world." In the `outputs` section of the job, we map these step outputs to job outputs called: `output1` and `output2`. In the `on.workflow_call.outputs` section we then define two outputs for the workflow itself, one called `firstword` which we map to `output1`, and one called `secondword` which we map to `output2`.
{% raw %}
```yaml{:copy}
name: Reusable workflow
on:
workflow_call:
# Map the workflow outputs to job outputs
outputs:
firstword:
description: "The first output string"
value: ${{ jobs.example_job.outputs.output1 }}
secondword:
description: "The second output string"
value: ${{ jobs.example_job.outputs.output2 }}
jobs:
example_job:
name: Generate output
runs-on: ubuntu-latest
# Map the job outputs to step outputs
outputs:
output1: ${{ steps.step1.outputs.firstword }}
output2: ${{ steps.step2.outputs.secondword }}
steps:
- id: step1
run: echo "::set-output name=firstword::hello"
- id: step2
run: echo "::set-output name=secondword::world"
```
{% endraw %}
We can now use the outputs in the caller workflow, in the same way you would use the outputs from a job within the same workflow. We reference the outputs using the names defined at the workflow level in the reusable workflow: `firstword` and `secondword`. In this workflow, `job1` calls the reusable workflow and `job2` prints the outputs from the reusable workflow ("hello world") to standard output in the workflow log.
{% raw %}
```yaml{:copy}
name: Call a reusable workflow and use its outputs
on:
workflow_dispatch:
jobs:
job1:
uses: octo-org/example-repo/.github/workflows/called-workflow.yml@v1
job2:
runs-on: ubuntu-latest
needs: job1
steps:
- run: echo ${{ needs.job1.outputs.firstword }} ${{ needs.job1.outputs.secondword }}
```
{% endraw %}
For more information on using job outputs, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idoutputs)."
## Monitoring which workflows are being used
You can use the {% data variables.product.prodname_dotcom %} REST API to monitor how reusable workflows are being used. The `prepared_workflow_job` audit log action is triggered when a workflow job is started. Included in the data recorded are:
* `repo` - the organization/repository where the workflow job is located. For a job that calls another workflow, this is the organization/repository of the caller workflow.
* `@timestamp` - the date and time that the job was started, in Unix epoch format.
* `job_name` - the name of the job that was run.
* `job_workflow_ref` - the workflow file that was used, in the form `{owner}/{repo}/{path}/{filename}@{ref}`. For a job that calls another workflow, this identifies the called workflow.
For information about using the REST API to query the audit log for an organization, see "[Organizations](/rest/reference/orgs#get-the-audit-log-for-an-organization)."
{% note %}
**Note**: Audit data for `prepared_workflow_job` can only be viewed using the REST API. It is not visible in the {% data variables.product.prodname_dotcom %} web interface, or included in JSON/CSV exported audit data.
{% endnote %}
## Next steps
To continue learning about {% data variables.product.prodname_actions %}, see "[Events that trigger workflows](/actions/learn-github-actions/events-that-trigger-workflows)."

View File

@@ -68,7 +68,9 @@ In addition to the usage limits, you must ensure that you use {% data variables.
{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 or ghec %}
## Billing for reusable workflows
If you reuse a workflow, billing is always associated with the caller workflow. For more information see, "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)."
If you reuse a workflow, billing is always associated with the caller workflow. Assignment of {% ifversion fpt or ghes or ghec %}{% data variables.product.prodname_dotcom %}-hosted runners{% endif %}{% ifversion ghae %}{% data variables.actions.hosted_runner %}s{% endif %} is always evaluated using only the caller's context. The caller cannot use {% ifversion fpt or ghes or ghec %}{% data variables.product.prodname_dotcom %}-hosted runners{% endif %}{% ifversion ghae %}{% data variables.actions.hosted_runner %}s{% endif %} from the called repository.
For more information see, "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)."
{% endif %}
## Artifact and log retention policy

View File

@@ -226,6 +226,31 @@ For more information, see "[Reusing workflows](/actions/learn-github-actions/reu
Required if input is defined for the `on.workflow_call` keyword. The value of this parameter is a string specifying the data type of the input. This must be one of: `boolean`, `number`, or `string`.
## `on.workflow_call.outputs`
A map of outputs for a called workflow. Called workflow outputs are available to all downstream jobs in the caller workflow. Each output has an identifier, an optional `description,` and a `value.` The `value` must be set to the value of an output from a job within the called workflow.
In the example below, two outputs are defined for this reusable workflow: `workflow_output1` and `workflow_output2`. These are mapped to outputs called `job_output1` and `job_output2`, both from a job called `my_job`.
### Example
{% raw %}
```yaml
on:
workflow_call:
# Map the workflow outputs to job outputs
outputs:
workflow_output1:
description: "The first job output"
value: ${{ jobs.my_job.outputs.job_output1 }}
workflow_output2:
description: "The second job output"
value: ${{ jobs.my_job.outputs.job_output2 }}
```
{% endraw %}
For information on how to reference a job output, see [`jobs.<job_id>.outputs`](#jobsjob_idoutputs). For more information, see "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)."
## `on.workflow_call.secrets`
A map of the secrets that can be used in the called workflow.

View File

@@ -77,7 +77,8 @@ To search for specific events, use the `action` qualifier in your query. Actions
| [`secret_scanning_new_repos`](#secret_scanning_new_repos-category-actions) | Contains organization-level configuration activities for secret scanning for new repositories created in the organization. {% ifversion fpt or ghec %}
| [`sponsors`](#sponsors-category-actions) | Contains all events related to sponsor buttons (see "[Displaying a sponsor button in your repository](/articles/displaying-a-sponsor-button-in-your-repository)"){% endif %}
| [`team`](#team-category-actions) | Contains all activities related to teams in your organization.
| [`team_discussions`](#team_discussions-category-actions) | Contains activities related to managing team discussions for an organization.
| [`team_discussions`](#team_discussions-category-actions) | Contains activities related to managing team discussions for an organization.{% ifversion fpt or ghec or ghes > 3.1 or ghae-next %}
| [`workflows`](#workflows-category-actions) | Contains activities related to {% data variables.product.prodname_actions %} workflows.{% endif %}
You can search for specific sets of actions using these terms. For example:
@@ -743,10 +744,11 @@ For more information, see "[Managing the publication of {% data variables.produc
| `disable` | Triggered when an organization owner disables team discussions for an organization. For more information, see "[Disabling team discussions for your organization](/articles/disabling-team-discussions-for-your-organization)."
| `enable` | Triggered when an organization owner enables team discussions for an organization.
{% ifversion fpt or ghec or ghes > 3.1 or ghae-next %}
### `workflows` category actions
{% data reusables.actions.actions-audit-events-workflow %}
{% endif %}
## Further reading
- "[Keeping your organization secure](/articles/keeping-your-organization-secure)"{% ifversion fpt or ghec or ghes > 3.3 or ghae-issue-5146 %}

View File

@@ -7,6 +7,6 @@
| `disable_workflow` | Triggered when a workflow is disabled.
| `enable_workflow` | Triggered when a workflow is enabled, after previously being disabled by `disable_workflow`.
| `rerun_workflow_run` | Triggered when a workflow run is re-run. For more information, see "[Re-running a workflow](/actions/managing-workflow-runs/re-running-a-workflow)."{% endif %}{% ifversion fpt or ghec or ghes > 3.2 or ghae-issue-4963 %}
| `prepared_workflow_job` | Triggered when a workflow job is started. Includes the list of secrets that were provided to the job. Can only be viewed using the REST API; not visible in the UI or the JSON/CSV export. For more information, see "[Events that trigger workflows](/actions/reference/events-that-trigger-workflows)."{% endif %}{% ifversion fpt or ghes > 3.1 or ghae-issue-1157 or ghec %}
| `prepared_workflow_job` | Triggered when a workflow job is started. Includes the list of secrets that were provided to the job. Can only be viewed using the REST API. It is not visible in the the {% data variables.product.prodname_dotcom %} web interface or included in the JSON/CSV export. For more information, see "[Events that trigger workflows](/actions/reference/events-that-trigger-workflows)."{% endif %}{% ifversion fpt or ghes > 3.1 or ghae-issue-1157 or ghec %}
| `approve_workflow_job` | Triggered when a workflow job has been approved. For more information, see "[Reviewing deployments](/actions/managing-workflow-runs/reviewing-deployments)."
| `reject_workflow_job` | Triggered when a workflow job has been rejected. For more information, see "[Reviewing deployments](/actions/managing-workflow-runs/reviewing-deployments)."{% endif %}

View File

@@ -0,0 +1,13 @@
To pass named inputs to a called workflow, use the `with` keyword in a job. Use the `secrets` keyword to pass named secrets. For inputs, the data type of the input value must match the type specified in the called workflow (either boolean, number, or string).
{% raw %}
```yaml
jobs:
call-workflow-passing-data:
uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
with:
username: mona
secrets:
envPAT: ${{ secrets.envPAT }}
```
{% endraw %}