Skip to content

Latest commit

 

History

History
117 lines (89 loc) · 5.85 KB

creating-workflow-templates-for-your-organization.md

File metadata and controls

117 lines (89 loc) · 5.85 KB
title shortTitle intro redirect_from versions type topics
Creating workflow templates for your organization
Create workflow templates
Learn how you can create workflow templates to help people in your team add new workflows more easily.
/actions/configuring-and-managing-workflows/sharing-workflow-templates-within-your-organization
/actions/learn-github-actions/creating-workflow-templates
/actions/learn-github-actions/creating-starter-workflows-for-your-organization
/actions/using-workflows/creating-starter-workflows-for-your-organization
fpt ghes ghec
*
*
*
tutorial
Workflows
CI

{% data reusables.actions.enterprise-github-hosted-runners %}

Overview

{% data reusables.actions.workflow-organization-templates %}

{% data reusables.actions.workflow-templates-categories %}

Note

Because workflow templates require a public .github repository, they are not available for {% data variables.product.prodname_emus %}.

Creating a workflow template

Workflow templates can be created by users with write access to the organization's public .github repository. These can then be used by organization members who have permission to create workflows.

{% ifversion fpt %} Workflow templates created by users can only be used to create workflows in public repositories. Organizations using {% data variables.product.prodname_ghe_cloud %} can also use workflow templates to create workflows in private repositories. For more information, see the {% data variables.product.prodname_ghe_cloud %} documentation. {% endif %}

Note

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.

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.

  2. Create a directory named workflow-templates.

  3. 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.

    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

  4. 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:

    {
    "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. 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:

    • 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 {% data variables.product.prodname_actions %}, see AUTOTITLE.