GitHub Actions Workflows

Purpose and Scope

This document provides a comprehensive overview of all GitHub Actions workflows configured in the pyjiit repository. It covers the automated CI/CD pipelines that handle documentation builds/deployments and package publishing to PyPI. For detailed information about the PyPI publishing process specifically, see Publishing to PyPI. For documentation-specific deployment details, see Documentation Deployment.

Sources: .github/workflows/documentation.yml1-65 .github/workflows/python-publish.yml1-29

Workflow Inventory

The repository contains two primary GitHub Actions workflows that automate critical infrastructure tasks:

Sources: .github/workflows/documentation.yml1-8 .github/workflows/python-publish.yml1-8

Documentation Build and Deployment Workflow

Workflow Overview

The documentation.yml workflow is responsible for building Sphinx documentation on every code change and deploying it to GitHub Pages when changes are pushed to the main branch. This ensures documentation is always validated on pull requests and automatically updated on the live site.

Sources: .github/workflows/documentation.yml1-65

Trigger Configuration

on:
  push:
    branches:
      - '**'  # All branches
  pull_request:
  workflow_dispatch:  # Manual triggering

The workflow triggers on:

• Push events to any branch ('**' pattern)
• Pull request events (validation only, no deployment)
• Manual dispatch via GitHub UI

Sources: .github/workflows/documentation.yml3-8

Concurrency Control

The workflow implements concurrency management to prevent resource conflicts:

concurrency:
  group: docs-${{ github.ref }}
  cancel-in-progress: true

This configuration creates a unique concurrency group per branch/ref and cancels any in-progress runs when a new push occurs. This prevents multiple simultaneous builds for the same branch, saving CI resources.

Sources: .github/workflows/documentation.yml10-12

Build Job Steps

Documentation Build Workflow Execution Flow

Sources: .github/workflows/documentation.yml22-64

Step-by-Step Breakdown

Sources: .github/workflows/documentation.yml23-63

Conditional Deployment Logic

The deployment step uses a conditional expression to ensure documentation is only published to GitHub Pages from the main branch:

if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}

This means:

• Pull requests: Documentation is built for validation but not deployed
• Feature branches: Documentation is built for validation but not deployed
• Main branch pushes: Documentation is built and deployed
• Manual dispatch: Depends on which branch it's run from

The deployment action (peaceiris/actions-gh-pages@v3) is configured with:

• publish_branch: gh-pages - Target branch for deployment
• github_token: ${{ secrets.GITHUB_TOKEN }} - Authentication using automatic GitHub token
• publish_dir: docs/_build/html - Source directory containing built HTML
• force_orphan: true - Creates orphan commits (no history) to keep gh-pages branch clean

Sources: .github/workflows/documentation.yml56-63

Caching Strategy

The workflow implements a two-tier caching strategy:

Two-Tier Caching Strategy for Documentation Builds

The cache key ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock','**/pyproject.toml') }} ensures:

• Cache invalidation when dependencies change
• Platform-specific caches (Linux, macOS, Windows)
• Consistent builds across different runners

Sources: .github/workflows/documentation.yml26-40

PyPI Publishing Workflow

Workflow Overview

The python-publish.yml workflow handles building and publishing the pyjiit package to the Python Package Index (PyPI). It is designed to execute only when a new release is published or when manually triggered.

Sources: .github/workflows/python-publish.yml1-29

Trigger Configuration

on:
  release:
    types: [ published ]
  workflow_dispatch:

The workflow triggers on:

• Release published events - Automatic publishing when a GitHub release is created
• Manual dispatch - Emergency or ad-hoc publishing via GitHub UI

This trigger strategy ensures that:

• Package versions are tied to GitHub releases
• Publishing is intentional and traceable
• Manual intervention is possible when needed

Sources: .github/workflows/python-publish.yml3-7

Publish Job Steps

PyPI Publishing Workflow Execution Flow

Sources: .github/workflows/python-publish.yml14-28

Publishing Step Details

The --build flag in the publish command combines two operations:

1. poetry build - Creates dist/*.whl and dist/*.tar.gz files
2. poetry publish - Uploads distributions to PyPI

Sources: .github/workflows/python-publish.yml15-28

Authentication and Secrets

The workflow uses GitHub Secrets for secure authentication:

• PYPI_API_KEY: Repository secret containing PyPI API token
  • Configured at: Repository Settings → Secrets and variables → Actions
  • Token scope: Upload permissions for the pyjiit package
  • Referenced in workflow: ${{ secrets.PYPI_API_KEY }}

The Poetry command poetry config pypi-token.pypi sets the authentication token in Poetry's configuration without exposing it in logs.

Sources: .github/workflows/python-publish.yml27

Workflow Comparison and Integration

Integration of Both GitHub Actions Workflows

Sources: .github/workflows/documentation.yml1-65 .github/workflows/python-publish.yml1-29

Workflow Characteristics

Sources: .github/workflows/documentation.yml1-65 .github/workflows/python-publish.yml1-29

Common Actions and Patterns

Shared Actions

Both workflows use common GitHub Actions:

These actions are maintained by GitHub and provide reliable, well-tested functionality for common CI/CD tasks.

Sources: .github/workflows/documentation.yml24-33 .github/workflows/python-publish.yml16-19

Third-Party Actions

This action is specifically designed for GitHub Pages deployment and handles:

• Committing to the target branch
• Handling CNAME files
• Managing orphan commits
• Authentication via GitHub token

Sources: .github/workflows/documentation.yml57-63

Poetry Configuration Pattern

Both workflows follow a consistent Poetry setup pattern:

pip install poetry        # Install Poetry globally
poetry install           # Install project dependencies
poetry <command>         # Execute Poetry commands

This approach:

• Uses Poetry as the single source of truth for dependencies
• Ensures consistent dependency versions via poetry.lock
• Separates dependency groups (--with docs in documentation workflow)

Sources: .github/workflows/documentation.yml42-49 .github/workflows/python-publish.yml21-23

Permissions and Security

Permission Model

Both workflows declare contents: write permission:

permissions:
  contents: write

This permission is required for:

• Documentation workflow: Writing to the gh-pages branch
• Publishing workflow: Technically not required (could use contents: read), but declared for consistency

Sources: .github/workflows/documentation.yml14-15 .github/workflows/python-publish.yml9-10

Secret Management

The GITHUB_TOKEN is automatically provided by GitHub Actions and has permissions limited to the repository. The PYPI_API_KEY must be manually created on PyPI and added to the repository's secrets.

Sources: .github/workflows/documentation.yml61 .github/workflows/python-publish.yml27

Workflow Execution Context

Developer Actions and Corresponding Workflow Executions

This diagram illustrates the typical development lifecycle and how workflows respond to different events. Documentation is validated on all branches but only deployed from main. Package publishing is strictly tied to release events.

Sources: .github/workflows/documentation.yml3-8 .github/workflows/documentation.yml56-63 .github/workflows/python-publish.yml3-7