DOCSEARCHbyAlgolia
Submit Docs

GitHub Actions Starter Workflows

repository·main·Indexed 11 days ago

https://github.com/actions/starter-workflows

A collection of template YAML files and metadata used to bootstrap common automation, CI/CD, and deployment workflows within the GitHub Actions UI. Includes documentation on directory organization, configuring properties.json metadata, supported categories, and the use of workflow variables like $default-branch.

Tokens
963
Snippets
1
Records
7
Agent score
46%

What's inside Starter Workflows

  1. Structure of a Starter Workflow template

    main

    Each starter workflow requires two files to function correctly in the GitHub UI:

    1. A YAML workflow file with a .yml extension (e.g., ci/django.yml).
    2. A corresponding metadata file located in a properties subdirectory of the workflow's folder, using the .properties.json extension (e.g., ci/properties/django.properties.json).

    Directory Organization:

    • ci/: Continuous Integration solutions.
    • deployments/: Deployment solutions.
    • automation/: Automation solutions.
    • code-scanning/: Code Scanning solutions.
    • pages/: GitHub Pages solutions.
    • icons/: SVG icons used for the templates.

  2. Use Starter Workflows in GitHub Actions

    main
    Starter Workflows are pre-configured YAML files designed to help users quickly set up GitHub Actions workflows. To use them, navigate to the Actions tab in a GitHub repository and select a template from the available options to begin creating a new workflow.

  3. Preview or publish starter workflow templates

    main

    Template authors can control the visibility of workflows using the labels array in properties.json:

    To hide a template (Preview mode): Add "preview" to the labels array. The template will be hidden from the general public but can be viewed by adding the preview=true query parameter to the workflow creation URL: https://github.com/<owner>/<repo_name>/actions/new?preview=true

    To publish a template (Public mode): Remove the labels array (or specifically the preview label) from the properties.json file.

  5. Use workflow variables in templates

    main

    You can use the following variables within your starter workflow YAML files. GitHub will substitute these values when the workflow is instantiated:

    • $default-branch: Substitutes the repository's default branch (e.g., main or master).
    • $protected-branches: Substitutes the list of protected branches in the repository.
    • $cron-daily: Substitutes a valid, random time within a 24-hour period.

  6. Supported categories for Starter Workflows

    main

    When defining the categories array in properties.json, use the following valid category names:

    • continuous-integration
    • deployment
    • testing
    • code-quality
    • code-review
    • dependency-management
    • monitoring
    • Automation
    • utilities
    • Pages
    • Hugo

  7. Configure workflow metadata in properties.json

    main

    The .properties.json file defines how a workflow appears in the GitHub onboarding UI. Use the following keys to configure the template:

    • name: A unique name for the template shown during onboarding.
    • description: A description of what the workflow does.
    • iconName: The name of the SVG icon in the icons/ folder (e.g., django maps to icons/django.svg). Alternatively, use an Octicon by prefixing with octicon (e.g., octicon person).
    • creator: The name of the template author.
    • categories: An array of categories used to group the template. Templates should include at least one category from the supported list and should ideally include language and tech stack identifiers to improve discoverability.
    • labels: An array of labels. Adding the preview label hides the template from the public UI.
    {
    "name": "Node.js",
    "description": "Build and test a Node.js project with npm.",
    "iconName": "nodejs",
    "categories": ["Continuous integration", "JavaScript", "npm", "React", "Angular", "Vue"],
    "labels": ["preview"]
}