GitHub Actions Workflows

GitHub Actions Workflows#

This page documents QuantEcon’s GitHub Actions workflow configurations.

Documentation Preview Workflow#

The QuantEcon.manual repository includes an automated CI workflow that provides documentation previews for Pull Requests.

How It Works#

When you create or update a Pull Request, the ci.yml workflow automatically:

  1. Builds the documentation using Jupyter Book with the same environment as production

  2. Deploys a preview to https://manual.quantecon.org/pr-{number}/

  3. Comments on the PR with a direct link to the preview

  4. Updates the preview when you push new commits to the PR

  5. Cleans up the preview directory when the PR is closed or merged

The cleanup process includes:

  • Automatic Detection: Distinguishes between merged and closed PRs

  • Robust Removal: Safely removes preview directories with retry logic

  • Verification: Confirms successful cleanup completion

  • Error Handling: Gracefully handles cases where directories are already removed

Benefits#

  • Visual Feedback: See exactly how your changes will look before merging

  • Review Process: Reviewers can easily access the rendered documentation

  • Quality Assurance: Catch formatting issues and broken links early

  • No Manual Setup: Everything is automated - just create a PR

Preview URLs#

Previews are accessible at:

  • Primary: https://manual.quantecon.org/pr-{number}/

  • Fallback: https://quantecon.github.io/QuantEcon.manual/pr-{number}/

Where {number} is your PR number (e.g., pr-45 for Pull Request #45).

Workflow Configuration#

The CI workflow is defined in .github/workflows/ci.yml and includes:

  • Environment Setup: Uses the same conda environment as production (environment.yml)

  • Build Process: Runs jb build manual --path-output ./

  • Safe Deployment: Uses subdirectory deployment to avoid conflicts with the main site

  • Smart Comments: Creates new preview comments for each build with commit SHA

  • Robust Cleanup: Removes preview directories when PRs are closed with:

    • Automatic detection of merged vs. closed PRs

    • Retry logic for push operations

    • Verification of successful cleanup

    • Graceful handling of edge cases

Note

The preview workflow is completely safe and won’t interfere with the main documentation site. It uses subdirectory deployment and preserves all existing content and configuration.

When the main branch publishes to gh-pages, the publish.yml workflow is configured with keep_files: true to preserve existing PR preview directories, so active previews remain accessible even after main branch deployments.

The cleanup mechanism has been enhanced to ensure previews are reliably removed when PRs are closed or merged, preventing accumulation of old preview directories.

GPU-Enabled Workflows#

For lecture repositories that require GPU computation, QuantEcon uses specialized workflows.

Our GPU based workflows are now built using RunsOn

Build Images#

There are two types of workflows:

  1. Using our own custom ami that is preloaded with CUDA, CUDANN, and LaTeX

  2. Using the ami provided by Runs On that includes Docker support. This is used by collab.yml workflows or any containerized workflow.

The benefit of using our own custom AMI is that we can choose CUDA, CUDANN versions and ensure we are able to use the latest versions to support lectures on JAX and GPU computing.

It is best to install only system wide software such as GPU frameworks, tool-kits and drivers.

When setting up a custom AMI we should install the NVIDIA support:

  1. nvidia CUDA framework

  2. nvidia drivers

  3. nvidia CUDANN

using the latest versions and then LaTeX

sudo apt-get -qq update
sudo apt-get install -y     \
texlive-latex-recommended \
texlive-latex-extra       \
texlive-fonts-recommended \
texlive-fonts-extra       \
texlive-xetex             \
latexmk                   \
xindy                     \
dvipng                    \
cm-super

Leave anaconda and local installs to the GitHub actions workflow.

While this incurs a small setup cost in terms of execution time, it provides flexibility in upgrading the python / anaconda software stack.

In addition to anaconda you should install gpu enabled python software in the GitHub Action as a setup step

  - name: Install JAX, Numpyro, PyTorch
    shell: bash -l {0}
    run: |
        pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu128
        pip install pyro-ppl
        pip install --upgrade "jax[cuda12-local]"
        pip install numpyro  
        python scripts/test-jax-install.py

Warning

PyTorch typically lags JAX in terms of compatibility with nvidia drivers. It is best to install the nightly versions to ensure the best compatibility.

You can check the latest on the PyTorch site with the installation table

Contents