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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add a GitHub Pages Deploy Workflow to a Starlight Docs Site (Starlight)
- Add a GitHub Pages Deploy Workflow to an Eleventy Site (Eleventy)
- Deploy Firebase Functions from GitHub Actions (Firebase Functions)