You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Consolidated PR for YAML anchors & aliases and workflow templates (#57491)
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>
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.
17
19
@@ -33,7 +35,7 @@ If you reuse a workflow from a different repository, any actions in the called w
33
35
34
36
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).”
35
37
36
-
## Reusable workflows versus composite actions
38
+
###Reusable workflows versus composite actions
37
39
38
40
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.
39
41
@@ -57,7 +59,7 @@ Let's compare some aspects of each solution:
57
59
| Can connect a maximum of four levels of workflows | Can be nested to have up to 10 composite actions in one workflow |
58
60
| Can use secrets | Cannot use secrets |
59
61
60
-
## Reusable workflows and workflow templates
62
+
## Workflow templates
61
63
62
64
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.
63
65
@@ -71,6 +73,16 @@ If you use a commit SHA when referencing the reusable workflow, you can ensure t
71
73
72
74
For more information, see [AUTOTITLE](/actions/using-workflows/creating-starter-workflows-for-your-organization).
73
75
76
+
{% ifversion fpt or ghec %}
77
+
78
+
## YAML anchors and aliases
79
+
80
+
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.
81
+
82
+
For reference information and examples, see [AUTOTITLE](/actions/reference/workflows-and-actions/reusing-workflow-configurations#yaml-anchors-and-aliases).
83
+
84
+
{% endif %}
85
+
74
86
## Next steps
75
87
76
88
To start reusing your workflows, see [AUTOTITLE](/actions/how-tos/sharing-automations/reuse-workflows).
Copy file name to clipboardExpand all lines: content/actions/how-tos/reuse-automations/create-workflow-templates.md
+5-73Lines changed: 5 additions & 73 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,88 +17,20 @@ type: tutorial
17
17
topics:
18
18
- Workflows
19
19
- CI
20
-
permissions: Write access to the organization's public `.github` repository. Templates can be used by organization members who have permission to create workflows.
21
20
---
22
21
23
22
{% data reusables.actions.enterprise-github-hosted-runners %}
24
23
25
-
> [!NOTE]
26
-
> * Because workflow templates require a public `.github` repository, they are not available for {% data variables.product.prodname_emus %}.
27
-
> * 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).
24
+
## Creating workflow templates
28
25
29
26
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.
30
27
31
-
1. If it doesn't already exist, create a new _public_repository named `.github` in your organization.
28
+
1. If it doesn't already exist, create a new repository named `.github` in your organization.
32
29
1. Create a directory named `workflow-templates`.
33
30
1. Create your new workflow file inside the `workflow-templates` directory.
34
-
35
-
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.
36
-
37
-
{% ifversion ghes %}
38
-
39
-
> [!NOTE]
40
-
> The following values in the `runs-on` key are also treated as placeholders:
41
-
>
42
-
> * "ubuntu-latest" is replaced with "[ self-hosted ]"
43
-
> * "windows-latest" is replaced with "[ self-hosted, windows ]"
44
-
> * "macos-latest" is replaced with "[ self-hosted, macOS ]"
45
-
46
-
{% endif %}
47
-
48
-
For example, this file named `octo-organization-ci.yml` demonstrates a basic workflow.
49
-
50
-
```yaml copy
51
-
name: Octo Organization CI
52
-
53
-
on:
54
-
push:
55
-
branches: [ $default-branch ]
56
-
pull_request:
57
-
branches: [ $default-branch ]
58
-
59
-
jobs:
60
-
build:
61
-
runs-on: ubuntu-latest
62
-
63
-
steps:
64
-
- uses: {% data reusables.actions.action-checkout %}
65
-
66
-
- name: Run a one-line script
67
-
run: echo Hello from Octo Organization
68
-
```
69
-
70
-
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`:
71
-
72
-
```json copy
73
-
{
74
-
"name": "Octo Organization Workflow",
75
-
"description": "Octo Organization CI workflow template.",
76
-
"iconName": "example-icon",
77
-
"categories": [
78
-
"Go"
79
-
],
80
-
"filePatterns": [
81
-
"package.json$",
82
-
"^Dockerfile",
83
-
".*\\.md$"
84
-
]
85
-
}
86
-
```
87
-
88
-
* `name` - **Required.** The name of the workflow. This is displayed in the list of available workflows.
89
-
* `description` - **Required.** The description of the workflow. This is displayed in the list of available workflows.
90
-
* `iconName` - **Optional.** Specifies an icon for the workflow that is displayed in the list of workflows. `iconName` can one of the following types:
91
-
* 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`.
92
-
* 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`.
93
-
* `categories` - **Optional.** Defines the categories that the workflow is shown under. You can use category names from the following lists:
94
-
* General category names from the [starter-workflows](https://github.com/actions/starter-workflows/blob/main/README.md#categories) repository.
95
-
* Linguist languages from the list in the [linguist](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml) repository.
96
-
* 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.
97
-
98
-
* `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.
99
-
100
-
To add another workflow template, add your files to the same `workflow-templates` directory.
31
+
1. Create a metadata file inside the `workflow-templates` directory.
32
+
1. To add another workflow template, add your files to the same `workflow-templates` directory.
101
33
102
34
## Next steps
103
35
104
-
To continue learning about {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/learn-github-actions/using-starter-workflows).
36
+
* For reference information about workflow templates, see [AUTOTITLE](/actions/reference/workflows-and-actions/reusing-workflow-configurations#workflow-templates).
0 commit comments