Skip to main content

GitHub Actions Python: Quick Start Guide

GitHub Actions is GitHub's native continuous integration and continuous deployment (CI/CD) platform that runs workflows automatically when you push code, open a pull request, or trigger them manually. A GitHub Actions workflow for Python is a YAML file that defines jobs, steps, and the actions to execute—all stored in your repository under .github/workflows/.

In this guide, you'll create your first workflow in under five minutes, covering the anatomy of a workflow file, how to check out code, set up Python, install dependencies, and run your first automated checks. By the end, every push to your repository will automatically run tests and linting.

Understanding GitHub Actions Workflows​

A workflow is a series of jobs that run in response to an event (a push, pull request, schedule, or manual trigger). Each job contains steps, and each step runs a shell command or calls a pre-built action. GitHub Actions provides thousands of community actions that handle common tasks like setting up Python, installing dependencies, and uploading test results.

GitHub Actions is free for public repositories and includes 2,000 free runner minutes per month for private repositories. A workflow runs on a runner—a virtual machine (Ubuntu, macOS, or Windows) where your code executes.

Creating Your First Workflow File​

Create a new directory .github/workflows/ in your repository root, then add a file named python-ci.yml:

name: Python CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    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 tests
      run: python -m pytest
    - name: Run linting
      run: python -m flake8 src/

This workflow triggers on pushes and pull requests to main or develop. It checks out your code, sets up Python 3.11, installs dependencies from requirements.txt, and runs pytest and flake8. When you push this file and commit it to your repository, GitHub automatically detects it and runs the workflow.

Triggering Workflows and Viewing Results​

After committing .github/workflows/python-ci.yml, navigate to your repository on GitHub. Click the Actions tab to see your workflow. A new run appears each time you push or open a pull request. Click the run to see detailed logs for each step, including pass/fail status, output, and any errors.

Failed workflow runs appear as red X badges on commits and pull requests. This immediate feedback helps catch bugs before merging. Successful runs show green checkmarks.

Key Components Explained​

on: Defines the event that triggers the workflow. Common triggers are push, pull_request, schedule (cron jobs), and workflow_dispatch (manual runs from the UI).

jobs: A workflow contains one or more jobs that run in parallel (unless you configure dependencies). Each job runs on a specified runner (operating system and image).

runs-on: Specifies the runner environment. Use ubuntu-latest for Linux, macos-latest for macOS, or windows-latest for Windows.

steps: An ordered sequence of tasks within a job. Steps can run shell commands (run:) or call actions (uses:). Actions are reusable units of work maintained by GitHub or the community.

Common Actions for Python Projects​

actions/checkout@v4: Clones your repository into the runner so your code is available to subsequent steps.

actions/setup-python@v5: Downloads and installs a specified Python version on the runner. You can test multiple versions by changing the python-version input.

actions/upload-artifact@v4: Uploads files (test reports, logs, coverage data) as workflow artifacts for download or later use.

actions/cache@v4: Caches directories (like ~/.cache/pip/) between workflow runs to avoid reinstalling dependencies.

Best Practices for Your First Workflow​

Keep your initial workflow simple and focused on detecting failures. Install only what you need (pytest and a linter). Avoid complex shell scripts in the workflow file; move multi-line logic to a script file in your repository.

Use consistent step names that describe what they do (not Step 3). Always pin action versions (e.g., @v4, not @latest) to prevent unexpected breakage when maintainers update actions.

Test your workflow locally using act (a tool that runs GitHub Actions workflows on your machine) before relying on it for critical checks. This reduces iteration time and saves runner minutes.

Key Takeaways​

  • A GitHub Actions workflow is a YAML file in .github/workflows/ that automates tasks in response to repository events.
  • Each workflow contains jobs, each job contains steps, and each step runs a command or calls an action.
  • Use actions/checkout@v4 to access your code and actions/setup-python@v5 to install Python.
  • Workflows run on virtual machines (runners) provided by GitHub; free tiers include 2,000 minutes per month for private repos.
  • Commit your workflow file to trigger automatic runs on push and pull request events.

Frequently Asked Questions​

What is the difference between a workflow and an action?​

An action is a reusable unit of code (like a function) that performs a specific task, provided by GitHub or the community. A workflow is a YAML file that orchestrates actions and shell commands in response to events. Workflows call actions; actions are building blocks.

Can I run the same workflow on multiple operating systems?​

Yes, use a matrix strategy. Replace runs-on: ubuntu-latest with a matrix that includes macos-latest and windows-latest. GitHub will run your workflow on each OS automatically.

How do I debug a failing workflow?​

Check the workflow run logs in the Actions tab on GitHub. Each step prints output and errors. For local testing, install act from https://github.com/nektos/act and run act -l to list workflows, then act push to simulate a push event.

Do I need to commit requirements.txt for the workflow to work?​

Yes, if your workflow installs dependencies with pip install -r requirements.txt, that file must exist in your repository. Alternatively, hard-code dependency names in the workflow's install step (not recommended for large projects).

How often can I run workflows?​

Workflows can run on every push, every pull request, on a schedule (cron), or manually via the UI. For public repos, there is no execution limit. For private repos, you get 2,000 free runner minutes per month; additional minutes are billed per second.

Further Reading​