From e255333ae95803a5239b7d2afff4eb254e0142c5 Mon Sep 17 00:00:00 2001 From: Salman Chishti Date: Thu, 18 Dec 2025 21:36:27 +0000 Subject: [PATCH] Add examples and metadata guidance to "Creating workflow templates" doc (#58161) Co-authored-by: Joe Clark <31087804+jc-clark@users.noreply.github.com> --- .../create-workflow-templates.md | 42 ++++++++++++++++++- .../reusing-workflow-configurations.md | 28 +------------ .../workflow-templates-metadata-example.md | 15 +++++++ .../workflow-templates-metadata-keys.md | 11 +++++ 4 files changed, 69 insertions(+), 27 deletions(-) create mode 100644 data/reusables/actions/workflow-templates-metadata-example.md create mode 100644 data/reusables/actions/workflow-templates-metadata-keys.md diff --git a/content/actions/how-tos/reuse-automations/create-workflow-templates.md b/content/actions/how-tos/reuse-automations/create-workflow-templates.md index 64ddb49e10..0081818272 100644 --- a/content/actions/how-tos/reuse-automations/create-workflow-templates.md +++ b/content/actions/how-tos/reuse-automations/create-workflow-templates.md @@ -28,7 +28,47 @@ This procedure demonstrates how to create a workflow template and metadata file. 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. -1. Create a metadata 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`: + + {% data reusables.actions.workflow-templates-metadata-example %} + + {% data reusables.actions.workflow-templates-metadata-keys %} + 1. To add another workflow template, add your files to the same `workflow-templates` directory. ## Next steps diff --git a/content/actions/reference/workflows-and-actions/reusing-workflow-configurations.md b/content/actions/reference/workflows-and-actions/reusing-workflow-configurations.md index 61c083c387..bf9d93492f 100644 --- a/content/actions/reference/workflows-and-actions/reusing-workflow-configurations.md +++ b/content/actions/reference/workflows-and-actions/reusing-workflow-configurations.md @@ -170,33 +170,9 @@ jobs: 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$" - ] - } - ``` +{% data reusables.actions.workflow-templates-metadata-example %} -* `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 `. 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. +{% data reusables.actions.workflow-templates-metadata-keys %} {% ifversion fpt or ghec %} diff --git a/data/reusables/actions/workflow-templates-metadata-example.md b/data/reusables/actions/workflow-templates-metadata-example.md new file mode 100644 index 0000000000..0f2a52a771 --- /dev/null +++ b/data/reusables/actions/workflow-templates-metadata-example.md @@ -0,0 +1,15 @@ +```json copy +{ + "name": "Octo Organization Workflow", + "description": "Octo Organization CI workflow template.", + "iconName": "example-icon", + "categories": [ + "Go" + ], + "filePatterns": [ + "package.json$", + "^Dockerfile", + ".*\\.md$" + ] +} +``` diff --git a/data/reusables/actions/workflow-templates-metadata-keys.md b/data/reusables/actions/workflow-templates-metadata-keys.md new file mode 100644 index 0000000000..c691f2d5d5 --- /dev/null +++ b/data/reusables/actions/workflow-templates-metadata-keys.md @@ -0,0 +1,11 @@ +* `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 be 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 `. 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.