All jobs

Add a Deploy Workflow for a Lit Component's Docs Site

Yes. An agent adds a workflow that builds your Lit starter's Eleventy docs and publishes them to GitHub Pages, stops committing the output and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how the docs site is produced before it writes the workflow, because the starter already has a full pipeline and the job is to run it somewhere other than a laptop. In a project started from lit/lit-element-starter-ts, the docs script in package.json chains docs:clean, which removes docs/, build, which is tsc, analyze, which runs cem analyze --litelement over src/ to write custom-elements.json, docs:build, which bundles my-element.js with Rollup into docs/my-element.bundled.js, docs:assets, which copies Prism's prism-okaidia.css, and docs:gen, which runs Eleventy with .eleventy.cjs. That file sets docs-src as input and docs as output, loads the syntax-highlight plugin and passes docs.css, .nojekyll, the webcomponentsjs polyfills and Lit's polyfill-support.js through; docs-src/_data/api.11tydata.js reads custom-elements.json so the API page lists the element's properties and events; and docs-src/_includes/relative-path.cjs makes every link relative, which is what lets the site work under a repository subpath. The README says the generated docs/ is intended to be checked in and served from the main branch /docs folder, and docs-src/_README.md repeats that the built files must be pushed to appear. docs/ is committed with api/, examples/, install/, docs.css, prism-okaidia.css and .nojekyll; .gitignore ignores custom-elements.json, the compiled my-element.js and test/ but not docs/. There is no .github/workflows/ directory.

The workflow uses GitHub's own Pages actions, so no token or deploy branch is needed. .github/workflows/docs.yml runs on a push to main that touches src/, docs-src/, .eleventy.cjs, package.json, package-lock.json or the workflow itself, and on workflow_dispatch. It declares permissions of contents: read, pages: write and id-token: write, a concurrency group named pages that does not cancel a deploy in progress, and two jobs. build checks out with actions/checkout, sets up Node on the current LTS line with actions/setup-node and its npm cache, runs npm ci and npm run docs, then actions/configure-pages and actions/upload-pages-artifact with path: docs. deploy needs build, runs in the github-pages environment and calls actions/deploy-pages, whose output is the site URL. The versions are the current releases when read, actions/checkout v7.0.1, actions/setup-node v7.1.0, actions/configure-pages v6.0.0, actions/upload-pages-artifact v5.0.0 and actions/deploy-pages v5.0.1, each pinned by commit SHA with the version in a comment.

With the site built in CI, the committed copy is a liability: every npm run docs rewrites it and every pull request that touches src/ carries a generated diff. The agent removes docs/ from the repository in its own commit, adds /docs/ to .gitignore under the existing generated-file entries, and rewrites the Static Site section of the README and docs-src/_README.md to say the site is published by the workflow and that the Pages source must be set to GitHub Actions under the repository's Pages settings, a step only a repository admin can do and which the sandbox cannot. The docs:serve script, wds --root-dir=docs, still works locally after a build, and the pull request says so.

Before opening the pull request the agent runs the same steps in its sandbox: npm ci, npm run docs, then npm run docs:serve and a visit in its own browser to /docs/index.html, /docs/api/ and /docs/examples/name-property/ to see that the API page lists name, count and the count-changed event from the manifest and that the bundled element renders in the example. It checks that .nojekyll is in the output, since GitHub Pages would otherwise skip files whose names begin with an underscore, and that every link in the generated HTML is relative, which is what the deployed subpath depends on. The output of each command goes into the pull request.

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 and deploys this Lit project's Eleventy docs site to GitHub Pages. Read package.json, .eleventy.cjs, everything under docs-src/, the committed docs/ directory, .gitignore and the README first. Write .github/workflows/docs.yml with a build job that runs npm ci and npm run docs and uploads docs/ with actions/upload-pages-artifact, and a deploy job that uses actions/deploy-pages in the github-pages environment, with pages and id-token permissions and a pages concurrency group; trigger it on pushes to the default branch that touch the sources, the docs sources or the build files, and on workflow_dispatch; pin each action by commit SHA with its version in a comment. Remove the committed docs/ directory in its own commit and add it to .gitignore. Update the README and docs-src/_README.md to describe the workflow and the Pages source setting an admin must change. Run npm ci and npm run docs in the sandbox, serve the output, open the index, API and example pages in the browser, and confirm .nojekyll is present and links are relative. Open a pull request with the commands and their output.",
  "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 has two commits: one that adds .github/workflows/docs.yml, the .gitignore line and the README changes, and one that removes the committed docs/ directory, so a reviewer can read the workflow without the deletion noise. Its description quotes the npm run docs output step by step, names the three pages opened in the browser and what they showed, and lists the pinned action versions. package.json, .eleventy.cjs and everything under docs-src/ are unchanged, because the workflow runs the project's existing scripts rather than new ones.

A reviewer checks the Node version pinned in the workflow, whether the paths filter should include anything else that feeds the site, and whether to keep a docs/ copy around until the first deploy succeeds, in which case the second commit can be dropped from the merge. The one step after merging is theirs: switching the Pages source to GitHub Actions, after which the first push to main, or a manual dispatch, publishes the site at the URL the deploy job prints.

Run it on every Lit project with a hand-built docs site

A team with several component packages started from the same template 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 package.json and .eleventy.cjs: a project that renamed the output directory gets that path in the upload step, and a project that already has a workflow directory gets the new file beside the others with the same pinning style.

The key's webhook_url reports each run the key starts with the pull request URL in result, so a script that sent the requests collects the 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 docs pipeline that chains six scripts fails in CI for reasons that never show on a laptop with a warm node_modules: a manifest that is not regenerated, an asset copied from a path that moved, a link that only works at the site root. The agent runs the whole chain in its own clean sandbox, serves the result, opens the pages in a browser and keeps every command and its output in the run's record, so the pull request shows the site the workflow will publish rather than a workflow that has never run.

The change uses what the repository already has: its own docs script, its relative links, its .nojekyll passthrough, and GitHub's Pages actions instead of a deploy token or a second branch. Removing the committed output is its own commit so it can be reviewed, or held back, on its own. Five component repositories get five pull requests, each pinned and filtered for its own files.

Frequently asked questions

Do I need a deploy token or a gh-pages branch?

No. actions/deploy-pages publishes the uploaded artifact through the workflow's own identity, which is why the job asks for pages: write and id-token: write. The only setting to change is the Pages source, from a branch folder to GitHub Actions, which an admin does once.

Why delete the committed docs directory?

Because once the workflow builds the site, the committed copy is regenerated by every npm run docs and turns every source change into a noisy diff. The deletion is a separate commit so you can merge the workflow first and remove the directory after the first successful deploy.

Will the site still work under my repository's subpath?

Yes. The starter's Eleventy templates build every link with the relative-path helper, so the pages do not assume they are served from the root, and the agent checks the generated HTML for absolute links before opening the pull request.

Does the workflow run tests?

No, only the docs chain. Tests are a separate concern and, in this starter, a separate workflow; keeping them apart means a failing test does not block a docs fix and a docs build does not slow a test run. The build script runs inside npm run docs in any case, so a type error still fails the deploy.

How do I preview the site locally?

Run npm run docs then npm run docs:serve, which serves the generated docs/ directory with the dev server. That still works after the directory is removed from the repository, since the build recreates it; it is just no longer committed.

More Lit jobs

The same job on other stacks

Keep reading