# 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 Rush](https://cloud.getrush.ai/run/add-deploy-workflow/lit/). Opens 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`

```json
{
  "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.

## 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

- [Add GitHub Actions CI to a Lit Web Component Project](https://getrush.ai/run/add-github-actions-ci/lit/)
- [Add Localization to a Lit Web Component with @lit/localize](https://getrush.ai/run/add-i18n/lit/)
- [Add a React Wrapper to a Lit Component](https://getrush.ai/run/add-react-wrapper/lit/)

## The same job on other stacks

- [Add a GitHub Pages Deploy Workflow to an mdBook](https://getrush.ai/run/add-deploy-workflow/mdbook/)
- [Add a Workflow That Deploys MkDocs Documentation on Every Push](https://getrush.ai/run/add-deploy-workflow/mkdocs/)
- [Add a GitHub Pages Deploy Workflow to a Pelican Site](https://getrush.ai/run/add-deploy-workflow/pelican/)

## 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/)
