actions/starter-workflows: the template library behind GitHub's Actions tab

What problem the starter workflow library solves

A new GitHub Actions workflow starts from an empty file, and an empty file is a bad teacher. The starter-workflows repository exists to remove that blank page: its README says these files are "presented whenever you start to create a new GitHub Actions workflow," surfaced through the Actions tab in the repository where you want the workflow. The audience is anyone who has a repository and has not yet written CI for it, plus anyone who wants to see how GitHub's own engineers structure a workflow before writing their own.

The repository is organized by intent rather than by language. The README lists ci for Continuous Integration workflows, deployments for Deployment workflows, automation for automating workflows, code-scanning for Code Scanning, and pages for Pages workflows, with icons holding the SVG artwork used in the picker. That split is the useful part. If you are looking for a release pipeline, you read deployments. If you are looking for a scheduled job, you read automation. The directory name is the first filter, and it costs nothing to browse.

How a template becomes a button in the Actions tab

Every workflow is a YAML file with a .yml extension, and it must be paired with a .properties.json file that carries the metadata shown in the GitHub.com interface. The README gives the example pairing ci/django.yml with ci/properties/django.properties.json. The YAML is the workflow itself. The JSON is what the picker renders: name, description, iconName, creator and categories.

Two details in that metadata contract are worth understanding before you read the templates. First, name is unique within the repository, so it doubles as an identifier rather than a free-form label. Second, categories drive prominence: the README says templates matching the user's language and tech stacks "will feature more prominently" in the list. Categories are drawn from a fixed set (continuous-integration, deployment, testing, code-quality, code-review, dependency-management, monitoring, Automation, utilities, Pages, Hugo) plus entries from GitHub's linguist languages file and a separate tech-stack list. A template that omits the right category is not broken, it is just harder to find.

The YAML side has substitution variables that the README documents. $default-branch resolves to the repository's branch, for example main or master. $protected-branches resolves to the repository's protected branches. $cron-daily resolves to a valid but random time within the day. That last one explains why scheduled templates do not all fire at the same minute.

Using a starter workflow without touching the repository

You do not install this project. There is no package, no CLI and no build step. The README's instruction is to click the Actions tab in the repository where you want to create a workflow, which opens the picker populated by these templates. If you want the raw file instead, read it in the repository and paste it into .github/workflows/ in your own project. The directory layout tells you where to look: ci/django.yml for a Django CI workflow, for instance.

The metadata format is the one thing worth copying if you maintain your own template set. The README's example for a Node.js template looks like this:

{
    "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"]
}

That labels array is the staging mechanism. The README states that adding a labels array with the label preview hides the template from users unless the URL carries the query parameter preview=true, and gives the example https://github.com/<owner>/<repo_name>/actions/new?preview=true. Removing the labels array publishes the template to the public list. If you ever build an internal template catalog, that preview flag is the pattern to steal: one field flips visibility, and the URL parameter is the only way in.

The contribution freeze, and what it means for you

The README is blunt: "right now we are not taking contributions." It redirects questions and support requests to the Community Discussions area, points high-priority bugs at Community Discussions or the support contact form, and directs security issues to the repository's security.md. It commits to security updates and fixes for major breaking changes, and says bugs may still be raised. That is a narrower commitment than a normal open source project, and it should shape how you treat the repository.

Practically, this means the templates are a sample, not a maintained library you can patch. If a template pins an action version you dislike, or uses a runner label that does not match your setup, you fork the YAML into your own repository and edit it there. There is no upstream path for your improvement. The README also notes that the GitHub public roadmap is where feature updates are tracked, which is a signal that the project's direction is managed elsewhere.

The licence field is reported as NOASSERTION, and the repository has no published GitHub releases. Anyone who needs a clear licence identifier or a version to pin should read the LICENSE file at the repository root rather than assume a standard open source grant. That is a limitation of the metadata, not necessarily of the licence itself, but it is the kind of thing that blocks adoption inside a company with a licence review process.

Where a hand-written workflow beats a starter template

A starter template is optimized for the first commit, not the hundredth. It cannot know your matrix, your caching keys, your deployment environments or your secrets. The substitution variables cover branch names and a daily cron time, and that is the whole surface. Anything conditional on your infrastructure is left to you.

There is also a discoverability trap. Because categories determine prominence, a template can be correct and still invisible if its metadata does not include your language or stack. The README points at external lists for languages and tech stacks, which means the category vocabulary is not fully contained in this repository. If you are searching the picker for something and it does not appear, the metadata is the first place to look, not the YAML.

A third case: if your organization has an internal template catalog with its own review process, importing a public template creates a second source of truth. You will be maintaining a copy of a file that upstream will not accept patches for. At that point, writing the workflow directly against your own conventions is cleaner than adapting someone else's.

Alternatives and how they differ

The closest alternative is the GitHub Actions Marketplace, which distributes individual actions rather than whole workflows. The difference in approach is the unit of reuse. A starter workflow gives you a complete .github/workflows file with jobs, steps and triggers already arranged; a Marketplace action gives you one step to insert into a workflow you have already designed. If you want a working pipeline in one click, the starter workflow is the right unit. If you want to compose your own pipeline from vetted pieces, the Marketplace is.

A second alternative is writing the YAML yourself from the GitHub Actions documentation. That is more work up front and gives you exactly the file you want, with no metadata layer and no template conventions to unlearn. The starter workflows are most valuable as a reading exercise in that scenario: they show the shape GitHub's own authors reach for, and you can then write your own with that shape in mind. Neither alternative is a drop-in replacement for the other, because they solve different problems.

What to verify before you commit a template

Read the YAML, not just the name. A template called "Node.js" tells you the ecosystem, not the steps, the triggers or the runner. Confirm which events it listens on and whether that matches how your team ships.

Check the substitution variables in context. $default-branch and $protected-branches resolve differently in a repository with a non-standard default branch or no protected branches at all. $cron-daily gives a random time within the day, which is fine for a nightly job and wrong if you need a specific window.

Confirm the licence situation yourself by reading the LICENSE file, since the metadata reports NOASSERTION. If your organization requires a named licence before code enters the repository, resolve that first.

Finally, treat the last push date as the maintenance signal it is. The repository's last push was on 2026-08-03, and the README states that security updates and fixes for major breaking changes will continue while contributions are closed. That is the level of upkeep to expect: not a feature roadmap, but not an abandoned tree either.

Editorial conclusion

Adopt this as a reference, not as a dependency: read the ci, deployments and automation folders to see how GitHub itself writes workflow YAML, and copy patterns rather than cloning the repository into your own tree. Do not plan on sending a pull request, because the README states the project is not taking contributions, and do not expect a tagged release or a changelog, since the repository has no GitHub releases and no changelog file. Before relying on any template, verify two things in your own repository: that the $default-branch and $protected-branches substitutions resolve the way you expect, and that the pinned action versions inside the template are ones you are willing to run.

Frequently asked questions

Official sources

1. actions/starter-workflows on GitHub
2. Issues
3. Project website
4. README