What Is a Workflow File? The Document That Defines a Pipeline
A workflow file is the document, usually YAML, that defines a pipeline: when it runs, what jobs it has, and what steps each job performs.
A workflow file is where pipeline-as-code becomes concrete. It is the actual file you write to tell the CI system what to do. The structure is consistent across platforms: a trigger section, a set of jobs, and steps within each job. Learning to read a workflow file is learning to read a pipeline.
Anatomy of a workflow file
- Triggers: the events that start the workflow.
- Jobs: independent units of work, often parallel.
- Steps: ordered commands or actions inside each job.
- Config: runner selection, variables, permissions.
How it is discovered
The platform scans a known location for workflow files. GitHub Actions reads every .yml under .github/workflows/. Each file is a separate workflow with its own triggers, so one repo can have many.
A quick example
A file starts with on: (the trigger), then jobs:, and under each job a runs-on: plus a list of steps:. That handful of keys describes an entire pipeline in a few dozen readable lines.
One repo, many workflow files
Splitting concerns across files keeps each readable: a CI file for tests, a release file for publishing, a nightly file for scheduled runs. Each triggers independently, so they do not interfere.
Workflow file vs pipeline run
The workflow file is the static definition; a run is one execution of it. Editing the file changes future runs. The file is the recipe; the run is the meal.
Key takeaways
- A workflow file is the YAML document that defines a pipeline.
- It has triggers, jobs, and steps, discovered from a known location.
- One repo can hold many workflow files, each triggering independently.