How do you publish organization workflow templates safely?

Create a .github repository, add a workflow-templates directory, write each template with secure defaults, add a matching properties file, and protect the repository with required review and code owners. Because templates are copied, every default you bake in becomes the starting point for many repositories.

Step 1: create the home

GitHub's documentation says to create a repository named .github in your organization if it does not exist, then create a directory named workflow-templates inside it. Each template is a YAML workflow file in that directory.

Step 2: write the template with safe defaults

You can use the $default-branch placeholder, which GitHub replaces with the repository default branch when a workflow is created. Beyond that, treat the file as your organization's opinion about how CI should look. A solid baseline includes:

• a top level permissions block with contents read
• actions pinned to reviewed commit SHAs
• a timeout on each job
• a comment block explaining what to change
• a scan or test step your teams already agreed on

Here is a minimal example:

name: Org CI
on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v6
      - run: echo "replace with build and test"

In your own copy, replace the version tag with a pinned SHA that you have reviewed.

Step 3: add the properties file

The metadata file must share the workflow's name, with the extension .properties.json. GitHub lists name and description as required. You can also set an icon, categories and file patterns. File patterns suggest the template when a repository has a matching file in its root, such as a package manifest.

Step 4: protect the repository

This is the step teams skip. Anyone who can push to the .github repository can change the starting point for new workflows across the organization. Apply the same rules you use for production code:

1. Require a pull request for changes to the default branch.
2. Add CODEOWNERS for the workflow-templates directory.
3. Limit write access to a small group.
4. Require review from someone who knows CI security.

See protecting workflow files with CODEOWNERS.

Step 5: tell people what changed

Copied templates do not update existing repositories. When you improve a template, announce the change and list what teams should update. Version notes in the commit message or a changelog file help.

Step 6: test before you publish

Create a test repository and generate a workflow from the template. Read the generated file. Run it. The public starter workflows project documents a preview label that hides a template from the usual list until it is ready, which is a useful idea to copy in your own process even if you manage it differently.

Try it yourself

Click through it at your own pace, or open it full screen. Consider what checks you would want every new repository to inherit from your template.

Quick check

Sources

• Creating workflow templates for your organization, GitHub Docs
• Secure use reference, GitHub Docs
• actions/starter-workflows README

Last reviewed: 19 October 2026.