DEV Community

Cover image for GitHub Actions: How It Works Under the Hood (Mental Model)
Micheal Angelo
Micheal Angelo

Posted on

GitHub Actions: How It Works Under the Hood (Mental Model)

#github #devops #automation #learning

GitHub Actions — How It Works Under the Hood

These notes explain GitHub Actions end-to-end — from the moment you push code to how shell commands run inside a temporary virtual machine and modify your repository.

This is not just a tutorial.

This is a mental model of how GitHub Actions actually works.

1️⃣ What GitHub Actions Really Is

At its core:

GitHub Actions = event-driven automation using temporary virtual machines that run shell commands on your repository

There is:

  • No magic
  • No background daemon in your repo
  • No always-on server

Everything runs only when an event occurs.

2️⃣ The Trigger: What Starts a Workflow

A workflow starts because of an event.

Example:

on:
  push:
Enter fullscreen mode Exit fullscreen mode

Meaning:

“When someone pushes code to this repository, run this workflow.”

Other common events:

  • pull_request
  • schedule (cron)
  • workflow_dispatch (manual trigger)
  • release

If no event fires — nothing runs.

3️⃣ The Big Picture Timeline (One Push)

When you run:

git push
Enter fullscreen mode Exit fullscreen mode

What actually happens:

  1. GitHub receives your push
  2. GitHub scans .github/workflows/*.yml
  3. Finds workflows listening to push
  4. Starts a fresh virtual machine (VM)
  5. Clones your repository into that VM
  6. Runs the defined steps
  7. Pushes changes back (if allowed)
  8. Destroys the VM

➡️ Each run is isolated, temporary, and stateless.

4️⃣ The Runner (Virtual Machine)

This line defines the environment:

runs-on: ubuntu-latest
Enter fullscreen mode Exit fullscreen mode

What this means:

  • GitHub spins up a brand-new Ubuntu Linux VM
  • Includes:
    • Bash
    • Git
    • Core Unix utilities (sed, date, grep, etc.)
  • Nothing from previous runs exists
  • The VM lives only for the job duration

Think of it as:

“A clean Linux laptop created just for this workflow.”

5️⃣ Jobs and Steps (Execution Order)

Basic structure:

jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - step 1
      - step 2
      - step 3
Enter fullscreen mode Exit fullscreen mode

Rules:

  • Jobs run in parallel by default
  • Steps run top to bottom
  • All steps share the same VM and filesystem

6️⃣ Checkout Step — How Your Code Enters the VM 

- uses: actions/checkout@v4
Enter fullscreen mode Exit fullscreen mode

Behind the scenes:

git clone https://github.com/yourname/yourrepo.git
cd yourrepo
Enter fullscreen mode Exit fullscreen mode

Without this step:

  • The VM has no source code
  • README.md doesn’t exist
  • Shell commands fail

7️⃣ persist-credentials Explained 

with:
  persist-credentials: true
Enter fullscreen mode Exit fullscreen mode

This tells Git:

“Keep GitHub’s temporary auth token so this VM can push back.”

Without it:

  • git push fails
  • Workflow can only read, not write

8️⃣ Where Shell Commands Run

Shell commands run:

  • Inside the Ubuntu VM
  • At the repository root

Example:

sed -i "..." README.md
Enter fullscreen mode Exit fullscreen mode

Means:

“Modify the README.md file inside the VM’s cloned repo.”

If the file is in a subfolder:

docs/README.md
Enter fullscreen mode Exit fullscreen mode

Linux paths are case-sensitive.

9️⃣ The Shell Step (Real Example) 

- name: Update date
  run: |
    DATE=$(date +"%Y-%m-%d")
    sed -i "s/_Last updated:.*_/_Last updated: ${DATE}_/" README.md
Enter fullscreen mode Exit fullscreen mode

What happens:

  • date runs on Ubuntu
  • Output stored in DATE
  • sed replaces the matching line in README

This is pure Unix, not GitHub magic.

🔟 Git Commands in Actions 

git add README.md
git commit -m "chore: auto update last updated date"
git push
Enter fullscreen mode Exit fullscreen mode

These are:

  • Normal Git commands
  • Running inside the VM
  • Acting on the cloned repo

Only difference:

  • Authentication is automatic

1️⃣1️⃣ Authentication (Why No Password)

GitHub injects a temporary token:

GITHUB_TOKEN
Enter fullscreen mode Exit fullscreen mode

Properties:

  • Valid only for this workflow run
  • Scoped to this repo
  • Expires after job completion

Allows:

  • git push
  • API calls

No human credentials involved.

1️⃣2️⃣ Workflow Permissions (Critical)

By default:

  • Actions can read
  • They cannot write

You must enable:

Settings → Actions → General → Read and write permissions
Enter fullscreen mode Exit fullscreen mode

Otherwise:

  • git push fails
  • Workflow appears to succeed but does nothing

1️⃣3️⃣ Why an Extra Commit Appears

Timeline:

  • You push commit A
  • Workflow runs
  • Workflow modifies files
  • Workflow creates commit B

History becomes:

A → B
Enter fullscreen mode Exit fullscreen mode

This is expected.

1️⃣4️⃣ Why This Does NOT Loop Forever

GitHub prevents infinite loops.

A workflow does not re-trigger itself unless:

  • The workflow file changes
  • Or explicitly configured

So:

  • Workflow-generated commits are ignored
  • No recursion

1️⃣5️⃣ Folder Roles 

.github/
└── workflows/
    └── update-date.yml
Enter fullscreen mode Exit fullscreen mode
  • .github/ → GitHub-specific config
  • workflows/ → automation definitions
  • .yml → declarative instructions

Actual scripts live inside:

run: |
Enter fullscreen mode Exit fullscreen mode

1️⃣6️⃣ Mental Model (Remember This)

GitHub Actions = temporary Linux VM + your repo + shell commands + event trigger

If you understand:

  • Linux shell
  • Git basics
  • File paths

You understand GitHub Actions.

1️⃣7️⃣ Why This Matters (Career Insight)

You’ve learned:

  • CI/CD fundamentals
  • Event-driven automation
  • Token-based authentication
  • Infrastructure abstraction

This is how:

  • Tests
  • Builds
  • Deployments
  • Linting
  • Docs generation

work in real systems.

Final Takeaway

Nothing runs “magically inside GitHub”.

Everything:

  • Runs on a real VM
  • Executes real shell commands
  • Uses real Git
  • Then disappears

Top comments (0)