Workflow File Naming & Organization

~9 min · organization, naming, convention

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Boring filenames pay rent for years

The Actions UI sorts workflows alphabetically by filename inside the .github/workflows directory. name: shows in the UI; the filename shows in URLs and grep. The two should match.

Convention worth following

ci.yml — quality checks: lint, type-check, test.
release.yml — runs on tag push, builds and publishes artifacts.
deploy-staging.yml, deploy-prod.yml — environment deploys, separate files for separate gates.
nightly.yml — scheduled jobs.
dependabot-auto-merge.yml — small admin automations.
codeql.yml — security scanning.
docs.yml — docs build / deploy.

What not to do

Don't dump everything into main.yml. Search and re-runs become awful.
Don't name files after dates (v2-2026-04-ci.yml) — versioning is git's job.
Don't use spaces or special chars; stick to lowercase + hyphens.
Don't have multiple workflows with the same name: — the UI gets confusing fast.

Code

A typical real-world .github/workflows directory·bash

ls .github/workflows/
# ci.yml
# release.yml
# deploy-staging.yml
# deploy-prod.yml
# nightly.yml
# codeql.yml
# dependabot-auto-merge.yml

# Each file declares one purpose. The set, read top-to-bottom, is
# the entire CI/CD story for the repo.

External links

GitHub — Workflow file location

Exercise

List the workflow files in any repo you maintain. For each, judge whether the filename describes its purpose. Rename any that don't (a single PR is enough). Don't rename URLs you reference externally without redirecting consumers.