Note
- Because workflow templates require a public
.github
repository, they are not available for Enterprise Managed Users. - 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 Reuse workflows.
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.
-
If it doesn't already exist, create a new public repository named
.github
in your organization. -
Create a directory named
workflow-templates
. -
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.For example, this file named
octo-organization-ci.yml
demonstrates a basic workflow.YAML name: Octo Organization CI on: push: branches: [ $default-branch ] pull_request: branches: [ $default-branch ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Run a one-line script run: echo Hello from Octo Organization
name: Octo Organization CI on: push: branches: [ $default-branch ] pull_request: branches: [ $default-branch ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Run a one-line script run: echo Hello from Octo Organization
-
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 namedocto-organization-ci.properties.json
contains the metadata for a workflow file namedocto-organization-ci.yml
:JSON { "name": "Octo Organization Workflow", "description": "Octo Organization CI workflow template.", "iconName": "example-icon", "categories": [ "Go" ], "filePatterns": [ "package.json$", "^Dockerfile", ".*\\.md$" ] }
{ "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 namedexample-icon.svg
is referenced asexample-icon
. - An icon from GitHub's set of Octicons. To reference an octicon, the value must be
octicon <icon name>
. For example,octicon smiley
.
- An SVG file that is stored in the
-
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 repository.
- Linguist languages from the list in the linguist repository.
- Supported tech stacks from the list in the starter-workflows 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.
Next steps
To continue learning about GitHub Actions, see Using workflow templates.