# Add a GitHub Pages Deploy Workflow to a Pelican Site

Yes. An agent adds a workflow that builds your Pelican site with the project's own reusable workflow, checks it on pull requests and publishes it to GitHub Pages.

[Run this on Rush](https://cloud.getrush.ai/run/add-deploy-workflow/pelican/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts with how the site is built and published today. In a site like getpelican/pelican-blog, the Pelican project's own weblog, `pelicanconf.py` sets `PATH = "content"`, `THEME = "themes/notmyidea"` (a theme committed in the repository, not installed from a package), `DEFAULT_PAGINATION = 5`, `STATIC_PATHS` for `images` and `extra`, an `EXTRA_PATH_METADATA` map that moves `extra/robots.txt` and the Apple touch icons to the site root, and a `MARKDOWN` dictionary with the `admonition`, `codehilite`, `extra`, `meta` and `toc` extensions. `publishconf.py` imports it, sets `SITEURL = "https://blog.getpelican.com"` and `DELETE_OUTPUT_DIRECTORY = True`. The content is twenty-one reStructuredText files and one Markdown file under `content/news/` and `content/pages/`. There is no `requirements.txt`, no `.github/` directory and no `.python-version`; the `Makefile` builds with `pelican $(INPUTDIR) -o $(OUTPUTDIR) -s $(PUBLISHCONF)` and its `upload` target pushes `output/` to a server with `rsync` over SSH. Its help text lists a `github` target, and `.PHONY` names one, but no rule for it exists, and `make serve` still calls `python -m SimpleHTTPServer`, which only Python 2 had.

Pelican publishes a reusable workflow for exactly this, `.github/workflows/github_pages.yml` in getpelican/pelican, and its documentation page on publishing shows the caller. The agent writes `.github/workflows/pelican.yml` with `on: push: branches: [main]`, `pull_request` and `workflow_dispatch`, and one job that `uses: getpelican/pelican/.github/workflows/github_pages.yml@<commit>` with `permissions` of `contents: read`, `pages: write` and `id-token: write`. The documentation suggests pinning the `@main` reference to a commit, so the agent pins it to the newest commit that touched the file, `3d3265b74c54338b8e9371c51eba4e8ef8b629c9`, and adds `.github/dependabot.yml` with a `github-actions` entry so the pin moves by pull request. The `with:` block carries `settings: "publishconf.py"`, `requirements: "pelican[markdown]"`, because the one Markdown article and the `MARKDOWN` setting need the `markdown` extra that the default `pelican` requirement leaves out, and `deploy: ${{ github.event_name == 'push' }}`, so a pull request only builds. The `theme` input stays empty: the reusable workflow clones a theme from a URL, and this one is already in the tree, which `pelicanconf.py` points at with a relative path.

Two settings deserve a sentence in the pull request rather than a change. The reusable workflow builds with `--extra-settings SITEURL=... FEED_DOMAIN=...` set to the GitHub Pages URL that `actions/configure-pages` reports, unless the caller passes `siteurl` and `feed_domain`; for a site that will keep its own domain, as `publishconf.py` says this one does, the agent passes both inputs and notes that a `CNAME` file in `content/extra/` with a matching `EXTRA_PATH_METADATA` entry is how Pelican gets that file to the root of the output. It also records that the workflow's `python` input defaults to 3.14 and that `publishconf.py`'s `sys.path.append(".")` is what lets it find `pelicanconf.py` when run from the repository root, which the workflow does.

Before opening the pull request the agent runs the same build the workflow will. It installs `pelican[markdown]` in its sandbox, runs `pelican content -o output -s publishconf.py --extra-settings SITEURL='"http://localhost:8000"'`, checks the output for the `news/` and `pages/` HTML, `feeds/all.atom.xml`, `robots.txt` and `theme/css/main.css`, serves `output/` and opens the index in its own browser to confirm the `notmyidea` theme renders and the five-per-page pagination works. It runs `actionlint` on the new workflow. One thing it cannot do: the GitHub Pages source must be switched to GitHub Actions under the repository's Settings, Pages, by someone with admin rights, and the pull request says so in its first paragraph.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a GitHub Actions workflow that builds this Pelican site and deploys it to GitHub Pages. Read pelicanconf.py, publishconf.py, the Makefile, the content directory and the theme first. Write .github/workflows/pelican.yml that calls the reusable workflow getpelican/pelican/.github/workflows/github_pages.yml pinned to its latest commit, with permissions contents: read, pages: write and id-token: write, settings publishconf.py, requirements matching the content formats and markdown extensions the settings use, deploy only on push to main and a build-only run on pull requests. Leave the theme input empty if the theme is committed in the repository. Add .github/dependabot.yml for github-actions. Install the same requirements in the sandbox, build the site with publishconf.py and a local SITEURL, check the output has the articles, pages, feeds and robots.txt, serve it and open it in the browser, and run actionlint on the workflow. In the pull request say that the Pages source must be set to GitHub Actions by hand, and explain how SITEURL and FEED_DOMAIN are set by the workflow and when to pass siteurl and feed_domain for a custom domain. Change no content.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `.github/workflows/pelican.yml` and `.github/dependabot.yml` and changes nothing else; the `Makefile`, `develop_server.sh` and the rsync target stay as they are, so the existing server deploy keeps working alongside the new one. Its description quotes the `pelican` build output from the sandbox, lists the files it found in `output/`, shows the browser screenshot of the built index from the run's record, and explains the two decisions a reader must make: which commit of the reusable workflow to trust, and whether the site keeps a custom domain.

A reviewer checks three things: that `requirements` matches every content format and plugin the settings use, which is where a build that passes locally and fails in Actions usually comes from; that `deploy` is false for pull requests, so a contributor's branch never publishes; and that the Pages setting has been switched to GitHub Actions before merge, because a first run on a repository still set to deploy from a branch fails at the `configure-pages` step. After merge, the first push to `main` builds, uploads the `output/` tarball as the `github-pages` artifact and deploys it, and the `Deploy to GitHub Pages` run shows the site URL on its summary.

## Run it on every Pelican site without a deploy workflow

A team that keeps several Pelican sites sends this body once per repository from its own server, each `POST /o/{org}/sessions` naming one repository in `resources` and carrying a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own settings: a site with a `requirements.txt` gets `requirements: "-r requirements.txt"`, a site that installs its theme from a package gets nothing in `theme` and the package in `requirements`, and a site that pulls its theme from another repository gets that URL in `theme` and a tag in `theme-checkout`.

The key's `webhook_url` reports each run the key starts with the pull request URL in `result`, so a script that sent four requests collects four pull requests without polling.

## Why run it on Rush?

A deploy workflow is only right if it builds the same site the author builds, and the places it goes wrong are in the settings: a Markdown extension the default requirement lacks, a theme path that only resolves from the repository root, a `SITEURL` that the workflow overrides. The agent reads `pelicanconf.py` and `publishconf.py`, runs the real `pelican` build in its own sandbox with the same inputs the workflow passes, opens the output in a browser and keeps every command in the run's record, so the pull request arrives with the evidence that the build works rather than a template copied from the documentation.

It also reads what is already there. A `Makefile` with a dead `github` target, a Python 2 server command and an rsync deploy tells the agent this site has been published by hand for years, so the pull request adds the new path without removing the old one and says which parts of the `Makefile` the workflow replaces. Several sites, each with its own settings, get several pull requests, each fitted to its repository.

## Frequently asked questions

### Why call Pelican's reusable workflow instead of writing the steps out?

Because the Pelican project maintains it: it sets up Python, installs the requirements, runs `pelican` with the Pages URL as `SITEURL` and `FEED_DOMAIN`, fixes file permissions, uploads the artifact and deploys it. The caller is a dozen lines, and Dependabot moves the pinned commit when the project publishes a change. The pull request also lists the steps the workflow runs, so a reader who prefers their own file can copy them.

### Do I have to commit the output directory?

No. The workflow runs `pelican` on the runner and uploads `output/`, so the repository holds the source only. `output` is already in this site's `.gitignore`, and the pull request leaves it there.

### What if my site uses a custom domain?

Pass `siteurl` and `feed_domain` in the `with:` block, because without them the workflow sets both to the `<user>.github.io/<repo>` address that `configure-pages` reports. Add a `CNAME` file under `content/extra/` with an `EXTRA_PATH_METADATA` entry that puts it at the output root, the same mechanism this site already uses for `robots.txt`.

### Does the agent change the Pages setting for me?

No. Switching the Pages source to GitHub Actions happens under the repository's Settings, Pages, and needs an admin on github.com. The pull request says so first, and the first workflow run fails at `actions/configure-pages` until it is done.

### Will pull requests publish the site?

No. The caller passes `deploy: ${{ github.event_name == 'push' }}`, so a pull request runs the build job only and shows whether the site still generates; only a push to `main` runs the deploy job.

## More Pelican jobs

- [Add Giscus Comments to a Pelican Blog](https://getrush.ai/run/add-giscus-comments/pelican/)
- [Show Last-Updated Dates on a Pelican Blog](https://getrush.ai/run/add-last-updated-dates/pelican/)
- [Add Link Checking to a Pelican Blog](https://getrush.ai/run/add-link-checking/pelican/)

## The same job on other stacks

- [Add a GitHub Pages Deploy Workflow to a Starlight Docs Site](https://getrush.ai/run/add-deploy-workflow/starlight/)
- [Add a GitHub Pages Deploy Workflow to an Eleventy Site](https://getrush.ai/run/add-deploy-workflow/eleventy/)
- [Deploy Firebase Functions from GitHub Actions](https://getrush.ai/run/add-deploy-workflow/firebase-functions/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
