Understanding GitHub Actions Core Concepts

1. Understanding Workflows

Property	Description	Example
name	Name of the workflow	`Deploy to Production`
on	Triggers for the workflow	`push`, `pull_request`
jobs	Collection of jobs to run	`build`, `test`

Example: Basic Workflow Configuration

name: CI
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello World"

Note: Workflows are defined in .github/workflows/ directory with YAML files.

2. Understanding Jobs

Property	Description	Values
jobs.<job_id>	Unique identifier for the job	`string`
jobs.<job_id>.name	Human-readable name for the job	`string`
jobs.<job_id>.runs-on	Runner environment to execute the job	`ubuntu-latest`, `macOS-latest`, `Windows-latest`
jobs.<job_id>.steps	Ordered list of steps to run in the job	`array`

Example: Basic Job Definition

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

Note: Jobs run in parallel by default unless dependencies are defined using needs.

3. Understanding Steps

Property	Description	Values
uses	Specifies the action to run	`actions/checkout@v4`
with	Input parameters for the action	`{ "token": "${{ secrets.GITHUB_TOKEN }}", "repository": "owner/repo" }`
env	Environment variables for the step	`ENV_VAR: value`
name	Display name of the step	`Run tests`
id	Unique identifier for the step	`test-step`
if	Conditional execution based on expression	`success()`

Example: Using a built-in action

steps:
  - name: Checkout code
    uses: actions/checkout@v4

Example: Using a custom action with inputs

steps:
  - name: Set up Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'

Note: Steps run in sequence within a job, and each step runs in its own isolated environment.

4. Understanding Actions

Property	Description	Example
name	Name of the action	`"Checkout Repository"`
uses	Reference to the action (local or from a repo)	`"actions/checkout@v4"`
with	Inputs to pass to the action	`{ "ref": "main" }`
runs	Defines how to run a JavaScript action	`"node main.js"`

Example: Using a GitHub Action

name: Build and Deploy
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

Note: Actions can be reused across workflows and repositories using the uses keyword.

Action Types

Reusable Actions - Shared across workflows and repos
Local Actions - Defined in the same repo
JavaScript Actions - Custom logic written in JavaScript
Docker Actions - Run in a Docker container

5. Understanding Runners

Runner Type	Description	Features	Limitations
GitHub-hosted runners	Managed by GitHub, pre-configured with tools and software	Linux, macOS, Windows Up to 6 hours runtime 10 concurrent jobs	No custom infrastructure May have outdated tools
Self-hosted runners	Runners you manage and configure on your own infrastructure	Full control over environment Custom tools and dependencies Can run on any OS or architecture	Security considerations Requires maintenance and setup

Example: Self-hosted runner registration

# Register a self-hosted runner
./config.sh --url https://github.com/owner/repo --token TOKEN

# Run the runner
./run.sh

Note: GitHub-hosted runners are ideal for quick setup and testing, while self-hosted runners provide flexibility for complex or sensitive workflows.

6. Understanding Events

Event	Description	Triggered By	Notes
push	Triggers on git push to a branch or tag	Git push operation	Can be filtered by branch or tag patterns
pull_request	Triggers on pull request creation, update, or merge	Pull request activity	Supports actions on opened, synchronize, closed, etc.
schedule	Triggers based on a cron schedule	Cron expression	Useful for periodic tasks like cleanup or reporting
workflow_dispatch	Allows manual triggering of a workflow	User action in UI or API call	Useful for testing or on-demand execution
issue_comment	Triggers on comments added to issues or pull requests	Comment creation	Can filter by comment content or user

Example: Push Event Configuration

on:
  push:
    branches: [ main ]
    tags: [ 'v*' ]

Example: Scheduled Workflow

on:
  schedule:
    - cron: '0 0 * * *' # Runs daily at midnight UTC

Note: Events can be filtered using branches, tags, and paths to reduce unnecessary workflow runs.

7. Understanding Contexts

Contexts are objects that contain information about the GitHub Actions runtime environment, including event data, workflow details, and repository information. They are accessible within workflows using the ${{ }} syntax.

Context	Description	Usage Example
github	Provides information about the workflow run and the event that triggered it.	`${{ github.event_name }}`
env	Contains environment variables set in the workflow or job.	`${{ env.GITHUB_TOKEN }}`
job	Provides information about the current job.	`${{ job.status }}`
runner	Provides information about the runner executing the job.	`${{ runner.os }}`
secrets	Provides access to secrets configured in the repository or organization.	`${{ secrets.API_KEY }}`

Example: Using GitHub Context in a Workflow

name: Example Workflow
on:
  push:
    branches:
      - main

jobs:
  example-job:
    runs-on: ubuntu-latest
    steps:
      - name: Echo Event Name
        run: echo "Event name is ${{ github.event_name }}"

Note: Contexts are read-only and cannot be modified during workflow execution.

Key Points About Contexts

Contexts are accessed using the ${{ }} syntax.
Each context provides specific runtime information relevant to the workflow environment.
Contexts can be used in if conditions, environment variables, and step commands.

8. Understanding YAML Syntax

Concept	Description	Example
Indentation	YAML uses indentation to define structure. Spaces (not tabs) are used for indentation.	`name: My Workflow on: push: branches: - main`
Keys and Values	Keys and values are separated by a colon and space.	`name: My Workflow`
Lists	Lists are created using a dash and space.	`branches: - main - develop`
Scalars	Simple values like strings, numbers, booleans.	`enabled: true`
Multiline Strings	Use `\|` for preserving line breaks, `>` for folding.	`description: \| This is a multiline description`

Example: Basic Workflow Structure

name: CI
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

Note: YAML is case-sensitive and requires consistent indentation. Misaligned indentation can cause parsing errors in GitHub Actions workflows.

9. Understanding Workflow Execution Model

The GitHub Actions workflow execution model determines how jobs and steps are orchestrated across runners. Each workflow runs in a separate, isolated environment provided by a runner.

Component	Description	Details
Workflow	A configured set of events that trigger jobs.	Defined in `.github/workflows/` directory with YAML files.
Job	A set of steps that run on the same runner.	Each job has a unique ID and can depend on other jobs.
Step	A task executed within a job.	Can run commands or actions; each step runs in its own process.
Runner	The environment where jobs execute.	Can be hosted on GitHub (Linux, macOS, Windows) or self-hosted.

Example: Basic Workflow Execution Flow

name: Example Workflow
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
      - name: Run Tests
        run: npm test

Execution Lifecycle

Trigger: Event like push or schedule initiates workflow.
Runner Allocation: GitHub assigns a runner based on runs-on.
Job Execution: Steps run sequentially in a job on the same runner.
Parallelism: Multiple jobs can run in parallel if defined.

Note: Each job runs in a fresh environment, meaning file system changes in one job do not persist to another unless explicitly shared via artifacts or other mechanisms.

10. Understanding Billing and Quotas

Resource	Free Tier Limit	Paid Tier Limit	Notes
Compute Time	`3,000 minutes/month`	`Unlimited`	Includes all GitHub-hosted runners
Storage	`500 MB`	`Unlimited`	For workflow run artifacts and caches
Artifacts	`1 GB`	`Unlimited`	Storage for workflow artifacts
Caching	`5 GB`	`Unlimited`	For GitHub Actions cache
Concurrent Jobs	`20`	`Unlimited`	Simultaneous workflow runs

Note: Free tier includes 3,000 minutes/month of compute time for GitHub-hosted runners. Usage beyond this limit will incur charges.

Example: Billing Alert

name: Billing Alert
on:
  schedule:
    - cron: '0 0 * * *'
jobs:
  check-billing:
    runs-on: ubuntu-latest
    steps:
      - name: Check usage
        run: |
          echo "Current usage: ${{ github.run_id }}"

Key Billing Points

GitHub-hosted runners are the primary cost driver
Free tier includes 3,000 minutes/month compute time
Usage beyond free limits is billed at $0.004 per minute for compute time
Storage and caching are free up to limits