---
title: "Set Up GitHub Pages CI"
description: "Automate documentation builds and deployment with GitHub Actions."
tags: [Deployment, CI\/CD, GitHub]
---

# Set Up GitHub Pages CI

Great Docs includes a one-command setup for continuous deployment to GitHub Pages.

## Quick Setup

```{.bash filename="Terminal"}
great-docs setup-github-pages
```

This generates a GitHub Actions workflow at `.github/workflows/docs.yml` that:

1. Checks out your repository
2. Installs Python and your package
3. Runs `great-docs build`
4. Deploys the `_site/` output to GitHub Pages

## Enable GitHub Pages in Your Repo

After pushing the workflow:

1. Go to **Settings → Pages** in your GitHub repository
2. Under **Source**, select **GitHub Actions**
3. Push a commit to the configured branch (default: `main`)

The workflow runs automatically on every push to the target branch.

## Customizing the Workflow

The generated workflow uses sensible defaults. Common customizations:

### Change the Trigger Branch

Edit `.github/workflows/docs.yml`:

```yaml
on:
  push:
    branches: [develop]  # Build on develop instead of main
```

### Pin the Python Version

```yaml
- uses: actions/setup-python@v6
  with:
    python-version: "3.12"  # Pin to a specific version
```

### Full Git History for Page Timestamps

Great Docs displays "Created" and "Last updated" timestamps on documentation pages using Git history. The generated workflow already includes `fetch-depth: 0` to enable this:

```yaml
- uses: actions/checkout@v6
  with:
    fetch-depth: 0  # Full history for accurate page timestamps
```

Without full history (the default shallow clone), all pages would show identical timestamps. If you have a very large repository and want faster builds, you can use sparse checkout to fetch full history only for documentation files:

```yaml
- uses: actions/checkout@v6
  with:
    fetch-depth: 0
    sparse-checkout: |
      user_guide
      recipes
      README.md
      ROADMAP.md
```

### Add a Changelog Token

The changelog feature needs API access to fetch releases. In GitHub Actions, `GITHUB_TOKEN` is available automatically:

```yaml
- name: Build docs
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: great-docs build
```

The generated workflow already includes this (no extra setup needed).

## Package Manager Detection

Great Docs automatically detects your project's package manager and generates the appropriate install commands:

| Lock File | Package Manager | Install Command |
|-----------|-----------------|-----------------|
| `uv.lock` | uv | `uv sync` (includes dev dependencies) |
| `poetry.lock` | poetry | `poetry install` (includes dev dependencies) |
| Neither | pip | `pip install -e .` with optional extras |

### uv Projects

If your project uses uv, the workflow installs all dependencies from your lock file:

```yaml
- name: Install package and dependencies
  run: |
    python -m pip install uv
    uv sync
    uv pip install git+https://github.com/posit-dev/great-docs.git
```

### Poetry Projects

For poetry projects:

```yaml
- name: Install package and dependencies
  run: |
    python -m pip install poetry
    poetry install
    poetry run pip install git+https://github.com/posit-dev/great-docs.git
```

### pip Projects with Optional Dependencies

For pip-based projects, Great Docs scans your `pyproject.toml` for optional dependency groups like `dev`, `docs`, `test`, or `notebook` and includes them automatically:

```yaml
- name: Install package and dependencies
  run: |
    python -m pip install --upgrade pip
    python -m pip install -e ".[dev,docs]"
    python -m pip install git+https://github.com/posit-dev/great-docs.git
```

This ensures that dependencies needed for documentation notebooks (like visualization libraries) are installed in CI.

### Override Package Manager Detection

Use the `--package-manager` flag to override auto-detection:

```{.bash filename="Terminal"}
great-docs setup-github-pages --package-manager pip  # Force pip even if uv.lock exists
great-docs setup-github-pages --package-manager uv   # Force uv
```

## Verifying the Deploy

After the first successful run, your docs are live at:

```
https://<username>.github.io/<repo>/
```

Check the **Actions** tab in your repo to see build logs and troubleshoot any issues.
