GitHub Actions

Table of Contents

Understanding GitHub Actions in a Linux Context

GitHub Actions is GitHub’s built-in automation platform for CI/CD and workflow automation. In a Linux-focused workflow, you primarily run jobs on Linux runners, build and test Linux-targeted software, and use Linux tooling inside your pipelines.

This chapter focuses on how to use GitHub Actions effectively when your targets, tools, or deployment environments are Linux.

Core Concepts: Workflows, Jobs, and Runners

At a high level:

Workflow: A YAML file stored in .github/workflows/. Defines automation triggered by events (push, pull request, schedule, etc.).
Job: A set of steps that run together on a single runner (e.g., ubuntu-latest).
Runner: A machine that executes jobs. Commonly:

GitHub-hosted Linux runner (e.g., ubuntu-latest)
Self-hosted Linux runner you manage

Key Linux-related idea: a job runs in a fresh Linux environment each time (unless you cache things), so you must install dependencies inside the workflow or use prebuilt actions.

Minimal Linux-based workflow:

name: CI
on:
  push:
    branches: [ "main" ]
jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install build dependencies
        run: sudo apt-get update && sudo apt-get install -y build-essential
      - name: Build
        run: make
      - name: Run tests
        run: make test

Linux Runners: GitHub-Hosted vs Self-Hosted

GitHub-Hosted Linux Runners

These are preconfigured virtual machines maintained by GitHub.

Common labels:

ubuntu-latest (points to a recent LTS, e.g., Ubuntu 22.04)
ubuntu-22.04, ubuntu-20.04, etc.

Characteristics:

Root access via sudo
Common tools preinstalled (Git, Python, Node, Docker CLI, etc.)
Fresh environment per job → reliable, but you must install anything custom every run or use caching.

Linux-specific considerations:

Package management via apt
Systemd services are generally not something you manage directly; workflows are expected to be non-interactive and short-lived.
Docker is available; useful for building Linux images or running Linux containers.

Self-Hosted Linux Runners

Useful when:

You need special hardware (e.g., GPU).
You depend on tools or network access not available on GitHub-hosted runners.
You want more control over performance and environment.

High-level steps to set up:

Provision a Linux machine (physical or VM).
Install basic requirements: Git, system tools.
In GitHub repository or organization: Settings → Actions → Runners → add runner.
Follow GitHub’s script to:

Download the runner binary for Linux.
Configure it (connects to GitHub).
Install as a systemd service (optional but typical).

Then in your workflow:

jobs:
  build-on-self-hosted:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - run: make

You can use custom labels for better control:

runs-on: [ self-hosted, linux, gpu ]

Linux operational concerns:

Keep the OS updated and secure.
Manage runner as a systemd service (start, stop, logs).
Ensure sufficient disk space, especially if building containers or large artifacts.

Workflow Files: Linux-Oriented Structure

Workflows are YAML files under .github/workflows/. Example layout:

.github/
  workflows/
    ci.yml
    release.yml
    nightly.yml

A typical Linux-centric CI workflow:

name: Linux CI
on:
  pull_request:
  push:
    branches: [ "main" ]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      - name: Run unit tests
        run: pytest

Linux angle:

Shell commands under run are executed by a shell (by default bash on Linux runners).
You can use typical Linux tooling (grep, sed, awk, find, etc.) in run steps.

Common Events for DevOps Workflows

Some common triggers:

push, pull_request: CI, basic checks.
workflow_dispatch: manual runs (often for deployments).
schedule: cron-like schedules (nightly builds, periodic checks).
release: on release creation/publishing.

Example scheduled Linux build:

on:
  schedule:
    - cron: "0 2 * * *"   # Every day at 02:00 UTC
jobs:
  nightly-linux-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/nightly-build.sh

The cron syntax is Linux-style crontab.

Steps and Actions: Using Linux Shell and Tools

Steps

Each step is either:

An external action (uses:), or
A shell command (run:).

Linux-specific behaviors:

Multiple lines in run: behave like a shell script:

- name: Build with logging
  run: |
    set -e
    mkdir -p build
    cd build
    cmake ..
    make -j"$(nproc)"

You can use environment variables ($HOME, $GITHUB_WORKSPACE, custom vars).
nproc is useful on Linux to detect CPU cores for parallel builds.

Using Official Actions with Linux

Common ones:

actions/checkout: clone your repository into the Linux runner.
actions/setup-node, actions/setup-python, actions/setup-go, actions/setup-java: set up language runtimes on Linux.
actions/cache: cache compiled dependencies, package downloads, etc.

Example: caching pip dependencies on Linux:

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
    restore-keys: |
      ${{ runner.os }}-pip-
- name: Install dependencies
  run: pip install -r requirements.txt

Note: runner.os will be Linux on Linux runners.

Working with Containers in GitHub Actions on Linux

Containers are very natural in a Linux CI environment.

Using a Container for a Job

Instead of installing packages repeatedly, run the job in a prebuilt Linux container image:

jobs:
  build-in-container:
    runs-on: ubuntu-latest
    container:
      image: python:3.11-slim
    steps:
      - uses: actions/checkout@v4
      - name: Install build tools
        run: |
          apt-get update
          apt-get install -y build-essential
      - name: Run tests
        run: pytest

Linux considerations:

The container itself is a Linux environment.
Package manager inside container may differ (e.g., apk on Alpine, dnf on Fedora).
File system operations are scoped to the container, but the workspace is mounted.

Building and Pushing Docker Images

Common for deploying Linux-based services.

Example:

jobs:
  build-and-push-image:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      id-token: write  # for registry authentication with OIDC (optionally)
    steps:
      - uses: actions/checkout@v4
      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: myuser/myapp:latest

This builds a Linux container image (default base) on an Ubuntu runner.

Using Matrix Builds for Multiple Linux Versions

Matrix builds let you test across multiple OS versions or tool versions.

Example: test on multiple Ubuntu versions and Python versions:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        os: [ ubuntu-20.04, ubuntu-22.04 ]
        python-version: [ "3.9", "3.11" ]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - run: pip install -r requirements.txt
      - run: pytest

You can also matrix different Linux distributions by using different container images instead of different runs-on labels.

Environment Variables and Secrets on Linux Runners

Environment Variables

You can set environment variables at different levels:

Workflow-wide: env at top level.
Job-specific: env in job.
Step-specific: env in a step.
Dynamically: echo "VAR=value" >> $GITHUB_ENV in a run step.

Example:

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      BUILD_TYPE: release
    steps:
      - uses: actions/checkout@v4
      - name: Print build type
        run: echo "Build type is $BUILD_TYPE"

On Linux runners, environment variables are accessed in the usual shell way: $VAR.

Secrets

Secrets (tokens, passwords, etc.) are stored in GitHub and injected into workflows:

- name: Deploy
  env:
    SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
  run: |
    mkdir -p ~/.ssh
    echo "$SSH_KEY" > ~/.ssh/id_ed25519
    chmod 600 ~/.ssh/id_ed25519
    ssh -o StrictHostKeyChecking=no user@server.example.com "deploy.sh"

Linux-specific part: handling file permissions with chmod, using SSH tools, etc.

Artifacts and Caching on Linux

Artifacts

Artifacts are files collected from a job (e.g., compiled binaries, logs).

Example:

- name: Build binary
  run: |
    make
    ls -l build/
- name: Upload binary
  uses: actions/upload-artifact@v4
  with:
    name: linux-binary
    path: build/myapp

Later workflow or job can download them using actions/download-artifact.

Caching

actions/cache is especially valuable on Linux for:

Package manager caches (~/.cache/pip, ~/.npm, ~/.cargo).
Build caches (~/.ccache, ~/.m2 for Maven).

General pattern:

- uses: actions/cache@v4
  with:
    path: ~/.cache/mytool
    key: ${{ runner.os }}-mytool-${{ hashFiles('**/lockfile') }}
    restore-keys: |
      ${{ runner.os }}-mytool-

On Linux, caches are regular directories on ext4/XFS/etc. on the runner; GitHub handles upload/download.

Linux-Focused CI Examples

C/C++ Project on Linux

name: C Build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install deps
        run: sudo apt-get update && sudo apt-get install -y build-essential cmake
      - name: Configure
        run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
      - name: Build
        run: cmake --build build -- -j"$(nproc)"
      - name: Run tests
        run: ctest --test-dir build

Python Project with Linters and Tests on Linux

name: Python CI
on:
  push:
  pull_request:
jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('requirements*.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-
      - name: Install dependencies
        run: pip install -r requirements.txt -r requirements-dev.txt
      - name: Lint
        run: flake8 src tests
      - name: Test
        run: pytest

Deploying from GitHub Actions to Linux Servers

GitHub Actions often serves as the bridge between code and Linux servers (on-prem or cloud VMs).

Common Linux deployment methods:

SSH-based deploy:

Copy artifacts via scp or rsync.
Run remote commands with ssh (e.g., restart systemd service).

Example:

   - name: Copy files
     run: |
       rsync -avz ./build/ user@server:/opt/myapp/
   - name: Restart service
     run: |
       ssh user@server "sudo systemctl restart myapp.service"

Container-based deploy:

Build and push Docker images in Actions.
On the Linux host, pull new images and restart containers (manually or via tools like Docker Swarm, Kubernetes, or systemd units that run containers).

Package-based deploy:

Build .deb or .rpm packages on Linux runner.
Publish to an internal repo, then upgrade on servers using apt or dnf.

These deployments usually happen in workflows triggered by tags/releases or manual workflow_dispatch events.

Security and Best Practices for Linux-Based Workflows

Least privilege:

Use minimal permissions: in workflows (e.g., contents: read only for CI).
Avoid giving unnecessary write permissions.

Protect secrets:

Store credentials as GitHub Secrets.
Never echo secrets directly in run steps.
Use environment variables, and restrict logging.

Pin action versions:

Instead of @v4 with floating major, consider pinning to specific SHAs for sensitive workflows.

Limit sudo usage on hosted runners:

Install only what you need.
Don’t run build steps with sudo unless necessary.

Harden self-hosted Linux runners:

Keep OS patched.
Restrict network access.
Run each job in containers if possible.
Clean workspace between jobs to avoid cross-job contamination.

Debugging GitHub Actions on Linux

When workflows misbehave:

Use ACTIONS_STEP_DEBUG and ACTIONS_RUNNER_DEBUG secrets for verbose logs (enable in repo settings).
Add set -x in shell steps to echo commands:

  - name: Debug script
    run: |
      set -euxo pipefail
      ./script.sh

Use ls, pwd, env to inspect the Linux environment:

  - run: |
      pwd
      ls -R
      env | sort

Check differences between local Linux environment and runner environment (versions of tools, missing packages, etc.).

By combining GitHub Actions with Linux runners, containers, and typical Linux tooling, you can build comprehensive CI/CD pipelines that compile, test, package, and deploy software reliably to Linux environments.

Comments

Please login to add a comment.

Don't have an account? Register now!

GitHub Actions

Understanding GitHub Actions in a Linux Context

Core Concepts: Workflows, Jobs, and Runners

Linux Runners: GitHub-Hosted vs Self-Hosted

GitHub-Hosted Linux Runners

Self-Hosted Linux Runners

Workflow Files: Linux-Oriented Structure

Common Events for DevOps Workflows

Steps and Actions: Using Linux Shell and Tools

Steps

Using Official Actions with Linux

Working with Containers in GitHub Actions on Linux

Using a Container for a Job

Building and Pushing Docker Images

Using Matrix Builds for Multiple Linux Versions

Environment Variables and Secrets on Linux Runners

Environment Variables

Secrets

Artifacts and Caching on Linux

Artifacts

Caching

Linux-Focused CI Examples

C/C++ Project on Linux

Python Project with Linters and Tests on Linux

Deploying from GitHub Actions to Linux Servers

Security and Best Practices for Linux-Based Workflows

Debugging GitHub Actions on Linux

Comments

Where to Move