jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 18:10:59 -05:00
Code Issues Projects Releases Wiki Activity

Consolidated PR for YAML anchors & aliases and workflow templates (#57491)

Browse Source 
Co-authored-by: eric sciple <ericsciple@users.noreply.github.com>
Co-authored-by: Joe Clark <31087804+jc-clark@users.noreply.github.com>
Co-authored-by: Salman Chishti <salmanmkc@GitHub.com>
Co-authored-by: hubwriter <hubwriter@github.com>
Co-authored-by: Thomas Boop <52323235+thboop@users.noreply.github.com>
This commit is contained in:
Salil
2025-09-17 14:04:08 -07:00
committed by GitHub
parent 418969a7a8
commit 0c84db7087
6 changed files with 201 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
content/actions/concepts/workflows-and-actions/index.md
View File

@@ -10,7 +10,7 @@ children:
- /variables
- /contexts
- /expressions
- /reusable-workflows
- /reusing-workflow-configurations
- /custom-actions
- /deployment-environments
- /concurrency

22
content/actions/concepts/workflows-and-actions/reusable-workflows.md → content/actions/concepts/workflows-and-actions/reusing-workflow-configurations.md
View File

@@ -1,6 +1,7 @@
---
title: Reusable workflows
intro: Learn how to avoid duplication when creating a workflow by reusing existing workflows.
title: Reusing workflow configurations
intro: Learn how to avoid duplication when creating a workflow.
shortTitle: Reusing workflow configurations
versions:
fpt: '*'
ghec: '*'
@@ -9,9 +10,10 @@ redirect_from:
- /actions/using-workflows/avoiding-duplication
- /actions/sharing-automations/avoiding-duplication
- /actions/concepts/workflows-and-actions/avoiding-duplication
- /actions/concepts/workflows-and-actions/reusable-workflows
---
## About reusable workflows
## Reusable workflows
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.
@@ -33,7 +35,7 @@ If you reuse a workflow from a different repository, any actions in the called w
You can view the reused workflows referenced in your {% data variables.product.prodname_actions %} workflows as dependencies in the dependency graph of the repository containing your workflows. For more information, see “[About the dependency graph](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph).”
## Reusable workflows versus composite actions
### Reusable workflows versus composite actions
Reusable workflows and composite actions both help you avoid duplicating workflow content. Whereas reusable workflows allow you to reuse an entire workflow, with multiple jobs and steps, composite actions combine multiple steps that you can then run within a job step, just like any other action.
@@ -57,7 +59,7 @@ Let's compare some aspects of each solution:
| Can connect a maximum of four levels of workflows | Can be nested to have up to 10 composite actions in one workflow |
| Can use secrets | Cannot use secrets |
## Reusable workflows and workflow templates
## 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 workflow template and some or all of the work of writing the workflow will be done for them. Within a workflow template, you can also reference reusable workflows to make it easy for people to benefit from reusing centrally managed workflow code.
@@ -71,6 +73,16 @@ If you use a commit SHA when referencing the reusable workflow, you can ensure t
For more information, see [AUTOTITLE](/actions/using-workflows/creating-starter-workflows-for-your-organization).
{% ifversion fpt or ghec %}
## YAML anchors and aliases
You can use YAML anchors and aliases to reduce repetition in your workflows. An anchor (marked with `&`) identifies a piece of content that you want to reuse, while an alias (marked with `*`) repeats that content in another location. Think of an anchor as creating a named template and an alias as using that template. This is particularly useful when you have jobs or steps that share common configurations.
For reference information and examples, see [AUTOTITLE](/actions/reference/workflows-and-actions/reusing-workflow-configurations#yaml-anchors-and-aliases).
{% endif %}
## Next steps
To start reusing your workflows, see [AUTOTITLE](/actions/how-tos/sharing-automations/reuse-workflows).

78
content/actions/how-tos/reuse-automations/create-workflow-templates.md
View File

@@ -17,88 +17,20 @@ type: tutorial
topics:
- Workflows
- CI
permissions: Write access to the organization's public `.github` repository. Templates can be used by organization members who have permission to create workflows.
---
{% data reusables.actions.enterprise-github-hosted-runners %}
> [!NOTE]
> * Because workflow templates require a public `.github` repository, they are not available for {% data variables.product.prodname_emus %}.
> * To avoid duplication among workflow templates you can call reusable workflows from within a workflow. This can help make your workflows easier to maintain. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows).
## Creating workflow templates
This procedure demonstrates how to create a workflow template and metadata file. The metadata file describes how the workflow templates will be presented to users when they are creating a new workflow.
1. If it doesn't already exist, create a new _public_ repository named `.github` in your organization.
1. If it doesn't already exist, create a new repository named `.github` in your organization.
1. Create a directory named `workflow-templates`.
1. Create your new workflow file inside the `workflow-templates` directory.
If you need to refer to a repository's default branch, you can use the `$default-branch` placeholder. When a workflow is created the placeholder will be automatically replaced with the name of the repository's default branch.
{% ifversion ghes %}
> [!NOTE]
> The following values in the `runs-on` key are also treated as placeholders:
>
> * "ubuntu-latest" is replaced with "[ self-hosted ]"
> * "windows-latest" is replaced with "[ self-hosted, windows ]"
> * "macos-latest" is replaced with "[ self-hosted, macOS ]"
{% endif %}
For example, this file named `octo-organization-ci.yml` demonstrates a basic workflow.
```yaml copy
name: Octo Organization CI
on:
push:
branches: [ $default-branch ]
pull_request:
branches: [ $default-branch ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: {% data reusables.actions.action-checkout %}
- name: Run a one-line script
run: echo Hello from Octo Organization
```
1. Create a metadata file inside the `workflow-templates` directory. The metadata file must have the same name as the workflow file, but instead of the `.yml` extension, it must be appended with `.properties.json`. For example, this file named `octo-organization-ci.properties.json` contains the metadata for a workflow file named `octo-organization-ci.yml`:
```json copy
{
"name": "Octo Organization Workflow",
"description": "Octo Organization CI workflow template.",
"iconName": "example-icon",
"categories": [
"Go"
],
"filePatterns": [
"package.json$",
"^Dockerfile",
".*\\.md$"
]
}
```
* `name` - **Required.** The name of the workflow. This is displayed in the list of available workflows.
* `description` - **Required.** The description of the workflow. This is displayed in the list of available workflows.
* `iconName` - **Optional.** Specifies an icon for the workflow that is displayed in the list of workflows. `iconName` can one of the following types:
* An SVG file that is stored in the `workflow-templates` directory. To reference a file, the value must be the file name without the file extension. For example, an SVG file named `example-icon.svg` is referenced as `example-icon`.
* An icon from {% data variables.product.prodname_dotcom %}'s set of [Octicons](https://primer.style/octicons/). To reference an octicon, the value must be `octicon <icon name>`. For example, `octicon smiley`.
* `categories` - **Optional.** Defines the categories that the workflow is shown under. You can use category names from the following lists:
* General category names from the [starter-workflows](https://github.com/actions/starter-workflows/blob/main/README.md#categories) repository.
* Linguist languages from the list in the [linguist](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml) repository.
* Supported tech stacks from the list in the [starter-workflows](https://github.com/github-starter-workflows/repo-analysis-partner/blob/main/tech_stacks.yml) repository.
* `filePatterns` - **Optional.** Allows the workflow to be used if the user's repository has a file in its root directory that matches a defined regular expression.
To add another workflow template, add your files to the same `workflow-templates` directory.
1. Create a metadata file inside the `workflow-templates` directory.
1. To add another workflow template, add your files to the same `workflow-templates` directory.
## Next steps
To continue learning about {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/learn-github-actions/using-starter-workflows).
* For reference information about workflow templates, see [AUTOTITLE](/actions/reference/workflows-and-actions/reusing-workflow-configurations#workflow-templates).

2
content/actions/reference/workflows-and-actions/index.md
View File

@@ -15,7 +15,7 @@ children:
- /contexts
- /deployments-and-environments
- /dependency-caching
- /reusable-workflows
- /reusing-workflow-configurations
- /metadata-syntax
- /workflow-cancellation
- /dockerfile-support

185
content/actions/reference/workflows-and-actions/reusable-workflows.md → content/actions/reference/workflows-and-actions/reusing-workflow-configurations.md
View File

@@ -1,16 +1,21 @@
---
title: Reusable workflows reference
shortTitle: Reusable workflows
intro: Learn how to avoid duplication when creating a workflow by reusing existing workflows.
title: Reusing workflow configurations
shortTitle: Reusing workflow configurations
intro: Find information about avoiding duplication when creating a workflow by reusing existing workflows{% ifversion fpt or ghec %} and using YAML anchors and aliases{% endif %}.
versions:
fpt: '*'
ghec: '*'
ghes: '*'
redirect_from:
- /actions/reference/reusable-workflows-reference
- /actions/reference/workflows-and-actions/reusable-workflows
---
## Access to reusable workflows
## Reusable workflows
Reference information for reusable workflows.
### Access to reusable workflows
A reusable workflow can be used by another workflow if any of the following is true:
@@ -39,7 +44,7 @@ For {% ifversion ghes or ghec %}internal or {% endif %}private repositories, the
{% data reusables.actions.actions-redirects-workflows %}
## Limitations
### Limitations of reusable worklows
* You can connect up to four levels of workflows. For more information, see [Nesting reusable workflows](/actions/how-tos/sharing-automations/reuse-workflows#nesting-reusable-workflows).
* You can call a maximum of 20 unique reusable workflows from a single workflow file. This limit includes any trees of nested reusable workflows that may be called starting from your top-level caller workflow file.
@@ -51,7 +56,7 @@ For {% ifversion ghes or ghec %}internal or {% endif %}private repositories, the
* To reuse variables in multiple workflows, set them at the organization, repository, or environment levels and reference them using the `vars` context. For more information see [AUTOTITLE](/actions/learn-github-actions/variables) and [AUTOTITLE](/actions/learn-github-actions/contexts#vars-context).
* Reusable workflows are called directly within a job, and not from within a job step. You cannot, therefore, use `GITHUB_ENV` to pass values to job steps in the caller workflow.
## Supported keywords for jobs that call a reusable workflow
### 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:
@@ -74,19 +79,19 @@ When you call a reusable workflow, you can only use the following keywords in th
> * The `GITHUB_TOKEN` permissions passed from the caller workflow can be only downgraded (not elevated) by the called workflow.
> * If you use `jobs.<job_id>.concurrency.cancel-in-progress: true`, don't use the same value for `jobs.<job_id>.concurrency.group` in the called and caller workflows as this will cause the workflow that's already running to be cancelled. A called workflow uses the name of its caller workflow in {% raw %}${{ github.workflow }}{% endraw %}, so using this context as the value of `jobs.<job_id>.concurrency.group` in both caller and called workflows will cause the caller workflow to be cancelled when the called workflow runs.
## How reusable workflows use runners
### How reusable workflows use runners
### {% data variables.product.github %}-hosted runners
#### {% data variables.product.github %}-hosted runners
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 [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners).
### Self-hosted runners
#### Self-hosted runners
Called workflows that are owned by the same user or organization{% ifversion ghes or ghec %} or enterprise{% endif %} as the caller workflow can access self-hosted runners from the 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 enterprise{% endif %}, provided that the runner has been made available to the caller repository
## Access and permissions for nested workflows
### Access and permissions for nested workflows
A workflow that contains nested reusable workflows will fail if any of the nested workflows is inaccessible to the initial caller workflow. For more information, see [Access to reusable workflows](#access-to-reusable-workflows).
@@ -94,10 +99,166 @@ A workflow that contains nested reusable workflows will fail if any of the neste
For information on how to use the API to determine which workflow files were involved in a particular workflow run, see [AUTOTITLE](/actions/how-tos/sharing-automations/reuse-workflows#monitoring-which-workflows-are-being-used).
## Behavior of reusable workflows when re-running jobs
### Behavior of reusable workflows when re-running jobs
{% data reusables.actions.partial-reruns-with-reusable %}
## `github` context
### `github` context
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 [AUTOTITLE](/actions/learn-github-actions/contexts#github-context).
## Workflow templates
Reference information to use when creating workflow templates for your organization.
### Workflow template availability
You can use templates in repositories that match or have more restricted visibility than the template repository.
* Workflow templates in a public `.github` repository are available to all repository types.
* Workflow templates in an internal `.github` repository are only available to internal and private repositories.
* Workflow templates in a private `.github` repository are only available to private repositories.
{% ifversion ghec %}
Because public workflow templates require a public `.github` repository, they are not available for {% data variables.product.prodname_emus %}.
{% endif %}
### Granting access for private/internal repositories
If you're using a private or internal `.github` repository, you need to grant Read access to users or teams who should be able to use the templates.
### The `$default-branch` placeholder
If you need to refer to a repository's default branch, you can use the `$default-branch` placeholder in your workflow template. When a workflow is created the placeholder will be automatically replaced with the name of the repository's default branch.
{% ifversion ghes %}
### Placeholder values in the `runs-on` key
The following values in the `runs-on` key are also treated as placeholders:
* `ubuntu-latest` is replaced with `[ self-hosted ]`
* `windows-latest` is replaced with `[ self-hosted, windows ]`
* `macos-latest"` is replaced with `[ self-hosted, macOS ]`
{% endif %}
### Example workflow template file
This file named `octo-organization-ci.yml` demonstrates a basic workflow.
```yaml copy
name: Octo Organization CI
on:
push:
branches: [ $default-branch ]
pull_request:
branches: [ $default-branch ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: {% data reusables.actions.action-checkout %}
- name: Run a one-line script
run: echo Hello from Octo Organization
```
### Metadata file requirements
The metadata file must have the same name as the workflow file, but instead of the `.yml` extension, it must be appended with `.properties.json`. For example, this file named `octo-organization-ci.properties.json` contains the metadata for a workflow file named `octo-organization-ci.yml`:
```json copy
{
"name": "Octo Organization Workflow",
"description": "Octo Organization CI workflow template.",
"iconName": "example-icon",
"categories": [
"Go"
],
"filePatterns": [
"package.json$",
"^Dockerfile",
".*\\.md$"
]
}
```
* `name` - **Required.** The name of the workflow. This is displayed in the list of available workflows.
* `description` - **Required.** The description of the workflow. This is displayed in the list of available workflows.
* `iconName` - _Optional._ Specifies an icon for the workflow that is displayed in the list of workflows. `iconName` can one of the following types:
* An SVG file that is stored in the `workflow-templates` directory. To reference a file, the value must be the file name without the file extension. For example, an SVG file named `example-icon.svg` is referenced as `example-icon`.
* An icon from {% data variables.product.prodname_dotcom %}'s set of [Octicons](https://primer.style/octicons/). To reference an octicon, the value must be `octicon <icon name>`. For example, `octicon smiley`.
* `categories` - **Optional.** Defines the categories that the workflow is shown under. You can use category names from the following lists:
* General category names from the [starter-workflows](https://github.com/actions/starter-workflows/blob/main/README.md#categories) repository.
* Linguist languages from the list in the [linguist](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml) repository.
* Supported tech stacks from the list in the [starter-workflows](https://github.com/github-starter-workflows/repo-analysis-partner/blob/main/tech_stacks.yml) repository.
* `filePatterns` - **Optional.** Allows the workflow to be used if the user's repository has a file in its root directory that matches a defined regular expression.
{% ifversion fpt or ghec %}
## YAML anchors and aliases
You can use YAML anchors and aliases to reduce repetition in your workflows. An anchor (marked with `&`) identifies a piece of content that you want to reuse, while an alias (marked with `*`) repeats that content in another location.
For detailed information about anchors and aliases, see [Node Anchors and Aliases in the YAML specification](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases).
Here's an example that uses YAML anchors and aliases with environment variables:
```yaml
jobs:
job1:
env: &env_vars # Define the anchor on first use
NODE_ENV: production
DATABASE_URL: {% raw %}${{ secrets.DATABASE_URL }}{% endraw %}
steps:
- run: echo "Using production settings"
job2:
env: *env_vars # Reuse the environment variables
steps:
- run: echo "Same environment variables here"
```
This is equivalent to writing the following YAML without anchors and aliases:
```yaml
jobs:
job1:
env:
NODE_ENV: production
DATABASE_URL: {% raw %}${{ secrets.DATABASE_URL }}{% endraw %}
steps:
- run: echo "Using production settings"
job2:
env:
NODE_ENV: production
DATABASE_URL: {% raw %}${{ secrets.DATABASE_URL }}{% endraw %}
steps:
- run: echo "Same environment variables here"
```
You can also use anchors for more complex configurations, such as reusing an entire job configuration:
```yaml
jobs:
test: &base_job # Define the anchor on first use
runs-on: ubuntu-latest
timeout-minutes: 30
env:
NODE_VERSION: '18'
steps:
- uses: {% data reusables.actions.action-checkout %}
- name: Set up Node.js
uses: {% data reusables.actions.action-setup-node %}
with:
node-version: {% raw %}${{ env.NODE_VERSION }}{% endraw %}
- run: npm test
alt-test: *base_job # Reuse the entire job configuration
```
{% endif %}

4
content/actions/tutorials/migrate-to-github-actions/manual-migrations/migrate-from-circleci.md
View File

@@ -51,7 +51,11 @@ Both CircleCI and {% data variables.product.prodname_actions %} configure `jobs`
Both CircleCI and {% data variables.product.prodname_actions %} provide a mechanism to reuse and share tasks in a workflow. CircleCI uses a concept called orbs, written in YAML, to provide tasks that people can reuse in a workflow. {% data variables.product.prodname_actions %} has powerful and flexible reusable components called actions, which you build with either JavaScript files or Docker images. You can create actions by writing custom code that interacts with your repository in any way you'd like, including integrating with {% data variables.product.github %}'s APIs and any publicly available third-party API. For example, an action can publish npm modules, send SMS alerts when urgent issues are created, or deploy production-ready code. For more information, see [AUTOTITLE](/actions/creating-actions).
{% ifversion fpt or ghec %}
CircleCI can reuse pieces of workflows with YAML anchors and aliases. {% data variables.product.prodname_actions %} supports YAML anchors and aliases for reusability, and also provides matrices for running jobs with different configurations. For more information about matrices, see [AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs).
{% else %}
CircleCI can reuse pieces of workflows with YAML anchors and aliases. {% data variables.product.prodname_actions %} supports the most common need for reusability using matrices. For more information about matrices, see [AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs).
{% endif %}
## Using Docker images