Documentation for reusable workflows (#21563)
Co-authored-by: Sarah Edwards <skedwards88@github.com>
This commit is contained in:
hubwriter
BIN
assets/images/help/settings/actions-access-settings.png
Normal file
BIN
assets/images/help/settings/actions-access-settings.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 110 KiB |
@@ -24,7 +24,7 @@ topics:
|
||||
|
||||
## About workflow artifacts
|
||||
|
||||
Artifacts allow you to persist data after a job has completed, and share that data with another job in the same workflow. An artifact is a file or collection of files produced during a workflow run. For example, you can use artifacts to save your build and test output after a workflow run has ended.
|
||||
Artifacts allow you to persist data after a job has completed, and share that data with another job in the same workflow. An artifact is a file or collection of files produced during a workflow run. For example, you can use artifacts to save your build and test output after a workflow run has ended. {% data reusables.actions.reusable-workflow-artifacts %}
|
||||
|
||||
{% data reusables.github-actions.artifact-log-retention-statement %} The retention period for a pull request restarts each time someone pushes a new commit to the pull request.
|
||||
|
||||
|
||||
@@ -1,33 +1,37 @@
|
||||
---
|
||||
title: Sharing workflows with your organization
|
||||
shortTitle: Sharing workflows with your organization
|
||||
intro: 'Learn how you can use organization features to collaborate with your team, by sharing workflow templates, secrets, and self-hosted runners.'
|
||||
title: Creating workflow templates
|
||||
shortTitle: Creating templates
|
||||
intro: 'Learn how you can create workflow templates to help people in your team add new workflows more easily.'
|
||||
redirect_from:
|
||||
- /actions/configuring-and-managing-workflows/sharing-workflow-templates-within-your-organization
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
type: how_to
|
||||
type: tutorial
|
||||
topics:
|
||||
- Workflows
|
||||
- CI
|
||||
---
|
||||
|
||||
{% data reusables.actions.enterprise-beta %}
|
||||
{% data reusables.actions.enterprise-github-hosted-runners %}
|
||||
{% data reusables.actions.ae-beta %}
|
||||
|
||||
## Overview
|
||||
|
||||
If you need to share workflows and other {% data variables.product.prodname_actions %} features with your team, then consider collaborating within a {% data variables.product.prodname_dotcom %} organization. An organization allows you to centrally store and manage secrets, artifacts, and self-hosted runners. You can also create workflow templates in the `.github` repository and share them with other users in your organization.
|
||||
{% data reusables.actions.workflow-organization-templates %}
|
||||
|
||||
## Creating a workflow template
|
||||
|
||||
Workflow templates can be created by users with write access to the organization's `.github` repository. The templates can then be used by organization members who have permission to create workflows.
|
||||
|
||||
{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 %}
|
||||
{% note %}
|
||||
|
||||
**Note:** Workflow templates can be used to create new workflows in an organization' s public repository; to use templates to create workflows in private repositories, the organization must be part of an enterprise plan.
|
||||
**Note:** To avoid duplication in workflows created from a template you can call reusable workflows from within a workflow template. This can help make your workflows easier to maintain. For more information, see "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)."
|
||||
|
||||
{% endnote %}
|
||||
{% endif %}
|
||||
|
||||
This procedure demonstrates how to create a workflow template and metadata file. The metadata file describes how the template is presented to users when they are creating a new workflow.
|
||||
|
||||
@@ -84,42 +88,6 @@ To add another workflow template, add your files to the same `workflow-templates
|
||||
|
||||
|
||||
|
||||
## Using a workflow template from your organization
|
||||
|
||||
This procedure demonstrates how a member of your organization can find and use a workflow template to create a new workflow. An organization's workflow templates can be used by anyone who is a member of the organization.
|
||||
|
||||
{% data reusables.repositories.navigate-to-repo %}
|
||||
{% data reusables.repositories.actions-tab %}
|
||||
1. If your repository already has existing workflows: In the upper-left corner, click **New workflow**.
|
||||
|
||||
1. Your organization's workflow templates are located in their own section titled "Workflows created by _organization name_". Under the name of the template you'd like to use, click **Set up this workflow**.
|
||||
|
||||
|
||||
|
||||
## Sharing secrets within an organization
|
||||
|
||||
You can centrally manage your secrets within an organization, and then make them available to selected repositories. This also means that you can update a secret in one location, and have the change apply to all repository workflows that use the secret.
|
||||
|
||||
When creating a secret in an organization, you can use a policy to limit which repositories can access that secret. For example, you can grant access to all repositories, or limit access to only private repositories or a specified list of repositories.
|
||||
|
||||
{% data reusables.github-actions.permissions-statement-secrets-organization %}
|
||||
|
||||
{% data reusables.organizations.navigate-to-org %}
|
||||
{% data reusables.organizations.org_settings %}
|
||||
{% data reusables.github-actions.sidebar-secret %}
|
||||
1. Click **New secret**.
|
||||
1. Type a name for your secret in the **Name** input box.
|
||||
1. Enter the **Value** for your secret.
|
||||
1. From the **Repository access** dropdown list, choose an access policy.
|
||||
1. Click **Add secret**.
|
||||
|
||||
## Share self-hosted runners within an organization
|
||||
|
||||
Organization admins can add their self-hosted runners to groups, and then create policies that control which repositories can access the group.
|
||||
|
||||
For more information, see "[Managing access to self-hosted runners using groups](/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups)."
|
||||
|
||||
|
||||
## Next steps
|
||||
|
||||
To continue learning about {% data variables.product.prodname_actions %}, see "[Security hardening for {% data variables.product.prodname_actions %}](/actions/learn-github-actions/security-hardening-for-github-actions)."
|
||||
To continue learning about {% data variables.product.prodname_actions %}, see "[Using workflow templates](/actions/learn-github-actions/using-workflow-templates)."
|
||||
@@ -62,7 +62,7 @@ For more information, see "[Workflow syntax for {% data variables.product.prodna
|
||||
|
||||
## Sharing data between jobs
|
||||
|
||||
If your job generates files that you want to share with another job in the same workflow, or if you want to save the files for later reference, you can store them in {% data variables.product.prodname_dotcom %} as _artifacts_. Artifacts are the files created when you build and test your code. For example, artifacts might include binary or package files, test results, screenshots, or log files. Artifacts are associated with the workflow run where they were created and can be used by another job.
|
||||
If your job generates files that you want to share with another job in the same workflow, or if you want to save the files for later reference, you can store them in {% data variables.product.prodname_dotcom %} as _artifacts_. Artifacts are the files created when you build and test your code. For example, artifacts might include binary or package files, test results, screenshots, or log files. Artifacts are associated with the workflow run where they were created and can be used by another job. {% data reusables.actions.reusable-workflow-artifacts %}
|
||||
|
||||
For example, you can create a file and then upload it as an artifact.
|
||||
|
||||
|
||||
@@ -165,6 +165,26 @@ on:
|
||||
types: [opened, deleted]
|
||||
```
|
||||
|
||||
{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 %}
|
||||
## Workflow reuse events
|
||||
|
||||
`workflow_call` is a keyword used as the value of `on` in a workflow, in the same way as an event. It indicates that a workflow can be called from another workflow. For more information see, "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)."
|
||||
|
||||
### `workflow_call`
|
||||
|
||||
| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` |
|
||||
| ------------------ | ------------ | ------------ | ------------------|
|
||||
| Same as the caller workflow | n/a | Same as the caller workflow | Same as the caller workflow |
|
||||
|
||||
#### Example
|
||||
|
||||
To make a workflow reusable it must include `workflow_call` as one of the values of `on`. The example below only runs the workflow when it's called from another workflow:
|
||||
|
||||
```yaml
|
||||
on: workflow_call
|
||||
```
|
||||
{% endif %}
|
||||
|
||||
## Webhook events
|
||||
|
||||
You can configure your workflow to run when webhook events are generated on {% data variables.product.product_name %}. Some events have more than one activity type that triggers the event. If more than one activity type triggers the event, you can specify which activity types will trigger the workflow to run. For more information, see "[Webhooks](/webhooks)."
|
||||
|
||||
@@ -32,8 +32,10 @@ children:
|
||||
- /finding-and-customizing-actions
|
||||
- /essential-features-of-github-actions
|
||||
- /managing-complex-workflows
|
||||
- /sharing-workflows-with-your-organization
|
||||
- /sharing-workflows-secrets-and-runners-with-your-organization
|
||||
- /creating-workflow-templates
|
||||
- /using-workflow-templates
|
||||
- /reusing-workflows
|
||||
- /events-that-trigger-workflows
|
||||
- /expressions
|
||||
- /contexts
|
||||
|
||||
@@ -170,6 +170,8 @@ To learn more about self-hosted runner labels, see ["Using labels with self-host
|
||||
To learn more about {% data variables.product.prodname_dotcom %}-hosted runner labels, see ["Supported runners and hardware resources"](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources).
|
||||
{% endif %}
|
||||
|
||||
{% data reusables.actions.reusable-workflows %}
|
||||
|
||||
{% ifversion fpt or ghes > 3.0 %}
|
||||
## Using environments
|
||||
|
||||
@@ -189,4 +191,4 @@ You can configure environments with protection rules and secrets. Each job in a
|
||||
|
||||
## Next steps
|
||||
|
||||
To continue learning about {% data variables.product.prodname_actions %}, see "[Sharing workflows with your organization](/actions/learn-github-actions/sharing-workflows-with-your-organization)."
|
||||
To continue learning about {% data variables.product.prodname_actions %}, see "[Sharing workflows, secrets, and runners with your organization](/actions/learn-github-actions/sharing-workflows-secrets-and-runners-with-your-organization)."
|
||||
|
||||
196
content/actions/learn-github-actions/reusing-workflows.md
Normal file
196
content/actions/learn-github-actions/reusing-workflows.md
Normal file
@@ -0,0 +1,196 @@
|
||||
---
|
||||
title: Reusing workflows
|
||||
shortTitle: Reusing workflows
|
||||
intro: 'Learn how to avoid duplication when creating a workflow by reusing existing workflows.'
|
||||
miniTocMaxHeadingLevel: 3
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '>=3.4'
|
||||
ghae: 'issue-4757'
|
||||
type: how_to
|
||||
topics:
|
||||
- Workflows
|
||||
---
|
||||
|
||||
{% data reusables.actions.enterprise-beta %}
|
||||
{% 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.
|
||||
|
||||
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. 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)."
|
||||
|
||||
## Access to reusable workflows
|
||||
|
||||
A reusable workflow can be used by another workflow if any 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)."
|
||||
|
||||
## 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 be 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:
|
||||
* Reusable workflows can't reference self-hosted runners.
|
||||
* 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
|
||||
|
||||
Reusable workflows are YAML-formatted files, very similar to any other workflow file. As with other workflow files, you locate reusable workflows in the `.github/workflows` directory of a repository. Subdirectories of the `workflows` directory are not supported.
|
||||
|
||||
For a workflow to be reusable, the values for `on` must include `workflow_call`:
|
||||
|
||||
```yaml
|
||||
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"):
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
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).
|
||||
|
||||
### 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.
|
||||
|
||||
{% raw %}
|
||||
```yaml{:copy}
|
||||
name: Reusable workflow example
|
||||
|
||||
on:
|
||||
workflow_call:
|
||||
inputs:
|
||||
username:
|
||||
required: true
|
||||
type: string
|
||||
secrets:
|
||||
token:
|
||||
required: true
|
||||
|
||||
jobs:
|
||||
example_job:
|
||||
name: Pass input and secrets to my-action
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: ./.github/actions/my-action@v1
|
||||
with:
|
||||
username: ${{ inputs.username }}
|
||||
token: ${{ secrets.token }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## Calling a reusable workflow
|
||||
|
||||
You call a reusable workflow by using the `uses` keyword. Unlike when you are using actions within a workflow, you call reusable workflows directly within a job, and not from within job steps.
|
||||
|
||||
[`jobs.<job_id>.uses`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_iduses)
|
||||
|
||||
You reference reusable workflow files using the syntax:
|
||||
|
||||
`{owner}/{repo}/{path}/{filename}@{ref}`
|
||||
|
||||
You can call multiple workflows, referencing each in a separate job.
|
||||
|
||||
{% data reusables.actions.uses-keyword-example %}
|
||||
|
||||
### 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 %}
|
||||
|
||||
### Supported keywords for jobs that call a reusable workflow
|
||||
|
||||
When you call a reusable workflow, you can only use the following keywords in the job containing the call:
|
||||
|
||||
* [`jobs.<job_id>.name`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idname)
|
||||
* [`jobs.<job_id>.uses`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_iduses)
|
||||
* [`jobs.<job_id>.with`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idwith)
|
||||
* [`jobs.<job_id>.with.<input_id>`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idwithinput_id)
|
||||
* [`jobs.<job_id>.secrets`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idsecrets)
|
||||
* [`jobs.<job_id>.secrets.<secret_id>`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idsecretssecret_id)
|
||||
* [`jobs.<job_id>.needs`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idneeds)
|
||||
* [`jobs.<job_id>.if`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idif)
|
||||
* [`jobs.<job_id>.permissions`](/actions/reference/workflow-syntax-for-github-actions#jobsjob_idpermissions)
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:**
|
||||
|
||||
* If `jobs.<job_id>.permissions` is not specified in the calling job, the called workflow will have the default permissions for the `GITHUB_TOKEN`. For more information, see "[Authentication in a workflow](/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token)."
|
||||
* The `GITHUB_TOKEN` permissions passed from the caller workflow can be only downgraded (not elevated) by the called workflow.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
### 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`.
|
||||
|
||||
{% raw %}
|
||||
```yaml{:copy}
|
||||
name: Call a reusable workflow
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
branches:
|
||||
- main
|
||||
|
||||
jobs:
|
||||
call-workflow:
|
||||
uses: octo-org/example-repo/.github/workflows/workflow-A.yml@v1
|
||||
|
||||
call-workflow-passing-data:
|
||||
uses: octo-org/example-repo/.github/workflows/workflow-B.yml@main
|
||||
with:
|
||||
username: mona
|
||||
secrets:
|
||||
token: ${{ secrets.TOKEN }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## Next steps
|
||||
|
||||
To continue learning about {% data variables.product.prodname_actions %}, see "[Events that trigger workflows](/actions/learn-github-actions/events-that-trigger-workflows)."
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Sharing workflows, secrets, and runners with your organization
|
||||
shortTitle: Sharing workflows with your organization
|
||||
intro: 'Learn how you can use organization features to collaborate with your team, by sharing workflow templates, secrets, and self-hosted runners.'
|
||||
redirect_from:
|
||||
- /actions/learn-github-actions/sharing-workflows-with-your-organization
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
type: how_to
|
||||
---
|
||||
|
||||
{% data reusables.actions.enterprise-beta %}
|
||||
{% data reusables.actions.enterprise-github-hosted-runners %}
|
||||
{% data reusables.actions.ae-beta %}
|
||||
|
||||
## Overview
|
||||
|
||||
If you need to share workflows and other {% data variables.product.prodname_actions %} features with your team, then consider collaborating within a {% data variables.product.prodname_dotcom %} organization. An organization allows you to centrally store and manage secrets, artifacts, and self-hosted runners. You can also create workflow templates in the `.github` repository and share them with other users in your organization.
|
||||
|
||||
## Using workflow templates
|
||||
|
||||
{% data reusables.actions.workflow-organization-templates %} For more information, see "[Creating workflow templates](/actions/learn-github-actions/creating-workflow-templates)."
|
||||
|
||||
{% data reusables.actions.reusable-workflows %}
|
||||
|
||||
## Sharing secrets within an organization
|
||||
|
||||
You can centrally manage your secrets within an organization, and then make them available to selected repositories. This also means that you can update a secret in one location, and have the change apply to all repository workflows that use the secret.
|
||||
|
||||
When creating a secret in an organization, you can use a policy to limit which repositories can access that secret. For example, you can grant access to all repositories, or limit access to only private repositories or a specified list of repositories.
|
||||
|
||||
{% data reusables.github-actions.permissions-statement-secrets-organization %}
|
||||
|
||||
{% data reusables.organizations.navigate-to-org %}
|
||||
{% data reusables.organizations.org_settings %}
|
||||
{% data reusables.github-actions.sidebar-secret %}
|
||||
1. Click **New secret**.
|
||||
1. Type a name for your secret in the **Name** input box.
|
||||
1. Enter the **Value** for your secret.
|
||||
1. From the **Repository access** dropdown list, choose an access policy.
|
||||
1. Click **Add secret**.
|
||||
|
||||
## Share self-hosted runners within an organization
|
||||
|
||||
Organization admins can add their self-hosted runners to groups, and then create policies that control which repositories can access the group.
|
||||
|
||||
For more information, see "[Managing access to self-hosted runners using groups](/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups)."
|
||||
|
||||
|
||||
## Next steps
|
||||
|
||||
To continue learning about {% data variables.product.prodname_actions %}, see "[Creating workflow templates](/actions/learn-github-actions/creating-workflow-templates)."
|
||||
@@ -36,7 +36,7 @@ Below is a list of the multiple {% data variables.product.prodname_actions %} co
|
||||
|
||||
### Workflows
|
||||
|
||||
The workflow is an automated procedure that you add to your repository. Workflows are made up of one or more jobs and can be scheduled or triggered by an event. The workflow can be used to build, test, package, release, or deploy a project on {% data variables.product.prodname_dotcom %}.
|
||||
The workflow is an automated procedure that you add to your repository. Workflows are made up of one or more jobs and can be scheduled or triggered by an event. The workflow can be used to build, test, package, release, or deploy a project on {% data variables.product.prodname_dotcom %}. {% ifversion fpt or ghes > 3.3 or ghae-issue-4757 %}You can reference a workflow within another workflow, see "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)."{% endif %}
|
||||
|
||||
### Events
|
||||
|
||||
|
||||
@@ -61,6 +61,12 @@ Usage limits apply to self-hosted runners. For more information, see "[About sel
|
||||
In addition to the usage limits, you must ensure that you use {% data variables.product.prodname_actions %} within the [GitHub Terms of Service](/articles/github-terms-of-service/). For more information on {% data variables.product.prodname_actions %}-specific terms, see the [GitHub Additional Product Terms](/github/site-policy/github-additional-product-terms#a-actions-usage).
|
||||
{% endif %}
|
||||
|
||||
{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 %}
|
||||
## 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)."
|
||||
{% endif %}
|
||||
|
||||
{% ifversion fpt or ghes > 2.22 or ghae %}
|
||||
## Artifact and log retention policy
|
||||
|
||||
|
||||
@@ -25,13 +25,17 @@ topics:
|
||||
|
||||
Anyone with write permission to a repository can set up continuous integration (CI) using {% data variables.product.prodname_actions %}.
|
||||
|
||||
You can use workflow templates to create new workflows in an organization's public repository. To use templates to create workflows in private repositories, the organization must be part of an enterprise plan.
|
||||
|
||||
After you set up CI, you can customize the workflow to meet your needs.
|
||||
|
||||
{% data reusables.repositories.navigate-to-repo %}
|
||||
{% data reusables.repositories.actions-tab %}
|
||||
1. Find the template that matches the language and tooling you want to use, then click **Set up this workflow**.
|
||||
1. If your repository already has existing workflows: In the upper-left corner, click **New workflow**.
|
||||
|
||||
2. Find the template that matches the language and tooling you want to use, then click **Set up this workflow**.
|
||||
|
||||
5. Click **Start commit**.
|
||||
1. Click **Start commit**.
|
||||
|
||||
{% data reusables.files.write_commit_message %}
|
||||
{% data reusables.files.choose_commit_branch %}
|
||||
|
||||
@@ -184,9 +184,91 @@ Diffs are limited to 300 files. If there are files changed that aren't matched i
|
||||
|
||||
For more information, see "[About comparing branches in pull requests](/articles/about-comparing-branches-in-pull-requests)."
|
||||
|
||||
{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 %}
|
||||
## `on.workflow_call.inputs`
|
||||
|
||||
When using the `workflow_call` keyword, you can optionally specify inputs that are passed to the called workflow from the caller workflow. Inputs for reusable workflows are specified with the same format as action inputs. For more information about inputs, see "[Metadata syntax for GitHub Actions](/actions/creating-actions/metadata-syntax-for-github-actions#inputs)." For more information about the `workflow_call` keyword, see "[Events that trigger workflows](/actions/learn-github-actions/events-that-trigger-workflows#workflow-reuse-events)."
|
||||
|
||||
In addition to the standard input parameters that are available, `on.workflow_call.inputs` requires a `type` parameter. For more information, see [`on.workflow_call.<input_id>.type`](#onworkflow_callinput_idtype).
|
||||
|
||||
If a `default` parameter is not set, the default value of the input is `false` for a boolean, `0` for a number, and `""` for a string.
|
||||
|
||||
Within the called workflow, you can use the `inputs` context to refer to an input.
|
||||
|
||||
If a caller workflow passes an input that is not specified in the called workflow, this results in an error.
|
||||
|
||||
### Example
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
on:
|
||||
workflow_call:
|
||||
inputs:
|
||||
username:
|
||||
description: 'A username passed from the caller workflow'
|
||||
default: 'john-doe'
|
||||
required: false
|
||||
type: string
|
||||
|
||||
jobs:
|
||||
print-username:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Print the input name to STDOUT
|
||||
run: echo The username is ${{ inputs.username }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
For more information, see "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)."
|
||||
|
||||
## `on.workflow_call.<input_id>.type`
|
||||
|
||||
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.secrets`
|
||||
|
||||
A map of the secrets that can be used in the called workflow.
|
||||
|
||||
Within the called workflow, you can use the `secrets` context to refer to a secret.
|
||||
|
||||
If a caller workflow passes a secret that is not specified in the called workflow, this results in an error.
|
||||
|
||||
### Example
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
on:
|
||||
workflow_call:
|
||||
secrets:
|
||||
access-token:
|
||||
description: 'A token passed from the caller workflow'
|
||||
required: false
|
||||
|
||||
jobs:
|
||||
pass-secret-to-action:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Pass the received secret to an action
|
||||
uses: ./.github/actions/my-action@v1
|
||||
with:
|
||||
token: ${{ secrets.access-token }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## `on.workflow_call.secrets.<secret_id>`
|
||||
|
||||
A string identifier to associate with the secret.
|
||||
|
||||
## `on.workflow_call.secrets.<secret_id>.required`
|
||||
|
||||
A boolean specifying whether the secret must be supplied.
|
||||
{% endif %}
|
||||
|
||||
## `on.workflow_dispatch.inputs`
|
||||
|
||||
When using `workflow_dispatch` event, you can optionally specify inputs that are passed to the workflow. Workflow dispatch inputs are specified with the same format as action inputs. For more information about the format see "[Metadata syntax for GitHub Actions](/actions/creating-actions/metadata-syntax-for-github-actions#inputs)."
|
||||
When using the `workflow_dispatch` event, you can optionally specify inputs that are passed to the workflow. Workflow dispatch inputs are specified with the same format as action inputs. For more information about the format see "[Metadata syntax for GitHub Actions](/actions/creating-actions/metadata-syntax-for-github-actions#inputs)."
|
||||
|
||||
```yaml
|
||||
on:
|
||||
@@ -1348,6 +1430,70 @@ Additional Docker container resource options. For a list of options, see "[`dock
|
||||
|
||||
{% endwarning %}
|
||||
|
||||
{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 %}
|
||||
## `jobs.<job_id>.uses`
|
||||
|
||||
The location and version of a reusable workflow file to run as a job.
|
||||
|
||||
`{owner}/{repo}/{path}/{filename}@{ref}`
|
||||
|
||||
`{ref}` can be a SHA, a release tag, or a branch name. Using the commit SHA is the safest for stability and security. For more information, see "[Security hardening for GitHub Actions](/actions/learn-github-actions/security-hardening-for-github-actions#reusing-third-party-workflows)."
|
||||
|
||||
### Example
|
||||
|
||||
{% data reusables.actions.uses-keyword-example %}
|
||||
|
||||
For more information, see "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)."
|
||||
|
||||
## `jobs.<job_id>.with`
|
||||
|
||||
When a job is used to call a reusable workflow, you can use `with` to provide a map of inputs that are passed to the called workflow.
|
||||
|
||||
Any inputs that you pass must match the input specifications defined in the called workflow.
|
||||
|
||||
Unlike [`jobs.<job_id>.steps[*].with`](#jobsjob_idstepswith), the inputs you pass with `jobs.<job_id>.with` are not be available as environment variables in the called workflow. Instead, you can reference the inputs by using the `inputs` context.
|
||||
|
||||
### Example
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
call-workflow:
|
||||
uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
|
||||
with:
|
||||
username: mona
|
||||
```
|
||||
|
||||
## `jobs.<job_id>.with.<input_id>`
|
||||
|
||||
A pair consisting of a string identifier for the input and the value of the input. The identifier must match the name of an input defined by [`on.workflow_call.inputs.<inputs_id>`](/actions/creating-actions/metadata-syntax-for-github-actions#inputsinput_id) in the called workflow. The data type of the value must match the type defined by [`on.workflow_call.<input_id>.type`](#onworkflow_callinput_idtype) in the called workflow.
|
||||
|
||||
Allowed expression contexts: `github`, and `needs`.
|
||||
|
||||
## `jobs.<job_id>.secrets`
|
||||
|
||||
When a job is used to call a reusable workflow, you can use `secrets` to provide a map of secrets that are passed to the called workflow.
|
||||
|
||||
Any secrets that you pass must match the names defined in the called workflow.
|
||||
|
||||
### Example
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
jobs:
|
||||
call-workflow:
|
||||
uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
|
||||
secrets:
|
||||
access-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## `jobs.<job_id>.secrets.<secret_id>`
|
||||
|
||||
A pair consisting of a string identifier for the secret and the value of the secret. The identifier must match the name of a secret defined by [`on.workflow_call.secrets.<secret_id>`](#onworkflow_callsecretssecret_id) in the called workflow.
|
||||
|
||||
Allowed expression contexts: `github`, `needs`, and `secrets`.
|
||||
{% endif %}
|
||||
|
||||
## Filter pattern cheat sheet
|
||||
|
||||
You can use special characters in path, branch, and tag filters.
|
||||
|
||||
@@ -183,6 +183,12 @@ You can help mitigate this risk by following these good practices:
|
||||
|
||||
Although pinning to a commit SHA is the most secure option, specifying a tag is more convenient and is widely used. If you’d like to specify a tag, then be sure that you trust the action's creators. The ‘Verified creator’ badge on {% data variables.product.prodname_marketplace %} is a useful signal, as it indicates that the action was written by a team whose identity has been verified by {% data variables.product.prodname_dotcom %}. Note that there is risk to this approach even if you trust the author, because a tag can be moved or deleted if a bad actor gains access to the repository storing the action.
|
||||
|
||||
{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 %}
|
||||
## Reusing third-party workflows
|
||||
|
||||
The same principles described above for using third-party actions also apply to using third-party workflows. You can help mitigate the risks associated with reusing workflows by following the same good practices outlined above. For more information, see "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)."
|
||||
{% endif %}
|
||||
|
||||
## Potential impact of a compromised runner
|
||||
|
||||
These sections consider some of the steps an attacker can take if they're able to run malicious commands on a {% data variables.product.prodname_actions %} runner.
|
||||
|
||||
@@ -124,6 +124,30 @@ The default permissions can also be configured in the organization settings. If
|
||||
1. Click **Save** to apply the settings.
|
||||
{% endif %}
|
||||
|
||||
{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 %}
|
||||
## Allowing access to components in an internal repository
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** {% data reusables.gated-features.internal-repos %}
|
||||
|
||||
{% endnote %}
|
||||
|
||||
Members of your enterprise can use internal repositories to work on projects without sharing information publicly. For information, see "[About repositories](/repositories/creating-and-managing-repositories/about-repositories#about-internal-repositories)."
|
||||
|
||||
To configure whether workflows in an internal repository can be accessed from outside the repository:
|
||||
|
||||
1. On {% data variables.product.prodname_dotcom %}, navigate to the main page of the internal repository.
|
||||
1. Under your repository name, click {% octicon "gear" aria-label="The gear icon" %} **Settings**.
|
||||
{% data reusables.repositories.settings-sidebar-actions %}
|
||||
1. Under **Access**, choose one of the access settings:
|
||||
|
||||
* **Not accessible** - Workflows in other repositories can't use workflows in this repository.
|
||||
* **Accessible by any repository in the organization** - Workflows in other repositories can use workflows in this repository as long as they are part of the same organization.
|
||||
* **Accessible by any repository in the enterprise** - Workflows in other repositories can use workflows in this repository as long as they are part of the same enterprise.
|
||||
1. Click **Save** to apply the settings.
|
||||
{% endif %}
|
||||
|
||||
{% ifversion fpt or ghes > 2.22 or ghae %}
|
||||
## Configuring the retention period for {% data variables.product.prodname_actions %} artifacts and logs in your repository
|
||||
|
||||
|
||||
@@ -6,6 +6,7 @@ getting_started:
|
||||
- /actions/learn-github-actions/finding-and-customizing-actions
|
||||
- /actions/learn-github-actions/essential-features-of-github-actions
|
||||
- /actions/learn-github-actions/managing-complex-workflows
|
||||
- /actions/learn-github-actions/reusing-workflows
|
||||
- /actions/learn-github-actions/security-hardening-for-github-actions
|
||||
featured_track: true
|
||||
continuous_integration:
|
||||
|
||||
3
data/reusables/actions/reusable-workflow-artifacts.md
Normal file
3
data/reusables/actions/reusable-workflow-artifacts.md
Normal file
@@ -0,0 +1,3 @@
|
||||
{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 %}
|
||||
All actions and workflows called within a run have write access to that run's artifacts.
|
||||
{% endif %}
|
||||
5
data/reusables/actions/reusable-workflows.md
Normal file
5
data/reusables/actions/reusable-workflows.md
Normal file
@@ -0,0 +1,5 @@
|
||||
{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 %}
|
||||
## Reusing workflows
|
||||
|
||||
You can call one workflow from within another workflow. This allows you to reuse workflows, avoiding duplication and making your workflows easier to maintain. For more information, see "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)."
|
||||
{% endif %}
|
||||
7
data/reusables/actions/uses-keyword-example.md
Normal file
7
data/reusables/actions/uses-keyword-example.md
Normal file
@@ -0,0 +1,7 @@
|
||||
```yaml
|
||||
jobs:
|
||||
call-workflow-1:
|
||||
uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
|
||||
call-workflow-2:
|
||||
uses: octo-org/another-repo/.github/workflows/workflow-2.yml@v1
|
||||
```
|
||||
@@ -0,0 +1 @@
|
||||
Workflow templates allow everyone in your organization who has permission to create workflows to do so more quickly and easily. When you create a new workflow, you can choose a template and some or all of the work of writing the workflow will be done for you. You can use workflow templates as a starting place to build your custom workflow or use them as-is. This not only saves time, it promotes consistency and best practice across your organization.
|
||||
Reference in New Issue
Block a user