Once your repo crosses around 15 workflows, it falls apart. CI logic, PR triggers, deploy flows, cron jobs, label events, all jammed into one folder like a digital landfill. GitHub doesn’t let you put workflows (not actions) anywhere else. You can’t separate them. So the mess grows, and your engineering velocity starts bleeding.
Here’s how I fix it with a structure that actually works at scale.
One Entry File: ci.yaml
This is your entrypoint. It doesn’t do anything except orchestrate. No logic. No steps. No envs (unless shared). Just pure routing. It uses workflow_call to dispatch the actual work.
This file should read like a flowchart. It decides what runs, in what order, and how concurrency is handled. Nothing else. All actual running jobs are handled elsewhere.
Naming: Simple, Predictable, Scannable
Every job lives in its own file. Each file follows the same naming pattern:
on-[trigger]-[type]-[what]
Like this:
on-issue-label-check-reproduction
on-pr-label-deploy-app-preview
on-workflow-call-lint
on-issue-label-notify
The trigger is the source event like issue or PR.
The type is what action occurred like label or open.
The what is what the workflow actually does.
If it’s a scheduled job, it drops the "on-" and starts with "cron".
cron-daily-summary
cron-clean-old-sessions
If a workflow doesn’t fit the formula, or has too many shenanigans, sure, name it however you want. Just keep everything that can be structured VISIBLY clear with the formula. When you open the workflows folder, it should read like a timeline, not a guessing game.
Keep Workflows Dumb
Every workflow file should be as thin as possible. Even if you trigger something directly like workflow_dispatch, the logic should live elsewhere.
Use actions or scripts. Keep workflows dumb. Let them route to the real work, not be the work.
Actions are reusable, versioned, testable, and logged. They run bash. They call scripts. They don’t rot in the YAML jungle.
ROI
You’ll burn a couple hours setting this up at first. But it'll pay in spades later on, since you won't have to go through a maze every time you need to add a new job, debug a flow, or onboard a new hire. Also, AI will help you 10x your productivity if you stick to patterns, and you'll be able to reason about your CI much easier. Patterns matter more than context here. The more predictable your system, the more useful the LLM becomes.