---
source: https://iinventedlight.com/library/notes/github-actions-workflow-basics.md
title: "GitHub Actions workflow basics"
license: CC-BY-4.0
license_url: https://creativecommons.org/licenses/by/4.0/
source_license: "CC BY 4.0 (github/docs); prose restates cited source lines"
attribution: "Summary by iinventedlight (AI-assisted). Sources: GitHub Docs, Understanding GitHub Actions - GitHub Docs, CC BY 4.0 (github/docs); GitHub Docs, Workflow syntax for GitHub Actions - GitHub Docs, CC BY 4.0 (github/docs)."
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
date: 2026-11-04
status: published
checked_on: 2026-11-04
as_of: 2026-11-04
confidence: medium
untested: "No code was run for this note; only the fetched documentation pages were read."
category: coding-references
topic_area: "code-ai-eng: GitHub"
tags: github, github-actions, ci-cd, yaml
sources:
  - id: S1
    title: "Understanding GitHub Actions - GitHub Docs"
    publisher: GitHub Docs
    url: https://docs.github.com/en/actions/about-github-actions/understanding-github-actions
    accessed: 2026-11-04
    license: "CC BY 4.0 (github/docs)"
  - id: S2
    title: "Workflow syntax for GitHub Actions - GitHub Docs"
    publisher: GitHub Docs
    url: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
    accessed: 2026-11-04
    license: "CC BY 4.0 (github/docs)"
---
# GitHub Actions workflow basics

## Short answer
GitHub Actions is GitHub's CI/CD platform. A workflow is a YAML file in `.github/workflows/` that runs one or more jobs when an event (push, pull request, schedule, issue opened...) triggers it. Jobs run on GitHub-hosted Linux, Windows or macOS machines or on your own runners. [S1][S2]

```yaml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test
```

## Key points
- Files need a `.yml` or `.yaml` extension. [S2]
- One repository can have many workflows; workflows can reuse others. [S1]

## Claims
- id: C1
  claim: GitHub Actions is a CI/CD platform.
  source: S1
  evidence: "GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform"
- id: C2
  claim: Workflows are defined in .github/workflows.
  source: S1
  evidence: "Workflows are defined in the .github/workflows directory in a repository."
- id: C3
  claim: Workflow files must have a .yml or .yaml extension.
  source: S2
  evidence: "must have either a .yml or .yaml file extension"
- id: C4
  claim: Use on to define which events trigger a workflow.
  source: S2
  evidence: "use on to define which events can cause the workflow to run"

## Sources
- [S1] Understanding GitHub Actions - GitHub Docs. GitHub Docs. https://docs.github.com/en/actions/about-github-actions/understanding-github-actions . License: CC BY 4.0 (github/docs). Accessed 2026-11-04.
- [S2] Workflow syntax for GitHub Actions - GitHub Docs. GitHub Docs. https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions . License: CC BY 4.0 (github/docs). Accessed 2026-11-04.

License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted).