# Add GitHub Actions CI to a Lit Web Component Project

Yes. An agent adds a GitHub Actions workflow to your Lit project that installs the Playwright browsers and runs lint, the tsc build and web-test-runner on each push.

[Run this on Rush](https://cloud.getrush.ai/run/add-github-actions-ci/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 project builds and tests before it writes a workflow, because a Lit starter has more moving parts than a `npm test` line suggests. In a project like lit/lit-element-starter-ts, `package.json` depends on `lit` 3.2 and `typescript` 5.9, there is no `engines` field, no `package-lock.json` and no `.github/` directory. `build` is plain `tsc`, which `tsconfig.json` points at `src/**/*.ts` with `rootDir` `src` and `outDir` set to the repository root, so `my-element.js` and `test/my-element_test.js` land beside `package.json` and are listed in `.gitignore`. `lint` runs `lit-analyzer` and then ESLint 8 over `src/**/*.ts`. `test` runs `wtr` twice, once as `test:dev` and once as `test:prod` with `MODE=prod`, and `web-test-runner.config.js` reads `./test/**/*_test.js`, the compiled output, through `@web/test-runner-playwright` launchers for Chromium, Firefox and WebKit, honouring a `BROWSERS` environment variable to run a subset. The one test file, `src/test/my-element_test.ts`, holds five tests on `my-element`.

Two facts shape the workflow. Tests run against compiled files, so `npm run build` must come before `npm test` or the runner finds nothing under `test/`. And `@web/test-runner-playwright` needs real browsers, which a fresh runner does not have, so the job runs `npx playwright install --with-deps` after installing dependencies, which pulls the three browsers and the system libraries they need on Ubuntu. Because the repository has no lockfile, `npm ci` would fail and `actions/setup-node`'s npm cache has nothing to key on; the agent runs `npm install`, commits the `package-lock.json` it produces, and uses `npm ci` with `cache: npm` from then on. If you would rather not commit a lockfile, it says so in the pull request and keeps `npm install`.

The workflow it writes, `.github/workflows/ci.yml`, triggers on `push` to `main` and on `pull_request`, sets `permissions: contents: read`, a `concurrency` group keyed on the ref with `cancel-in-progress`, and a `timeout-minutes` so a hung browser cannot hold a runner. One `test` job on `ubuntu-latest` checks out the code, sets up Node 22 with the npm cache, installs, installs the browsers, then runs `npm run lint`, `npm run build` and `npm test` as separate steps so a failure names the stage. A second `docs` job runs `npm run docs`, which chains `tsc`, `cem analyze`, the Rollup bundle and Eleventy over `docs-src/`, because that pipeline is the part of a starter that silently rots; it uploads nothing and only has to exit zero. A `prettier --check` step over the same glob as the `format` script, with the same `--ignore-path ./.eslintignore`, is included only if the tree is already clean, which the agent checks first.

Before opening the pull request the agent runs every step itself in its sandbox: lint, build, the five tests in all three browsers in both modes, and the docs build, and fixes what the workflow turns up rather than leaving a red first run. It adds `actionlint` over the new file to catch an expression or a runner label typo, and a status badge line to `README.md` under the existing Testing section.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add GitHub Actions CI to this Lit TypeScript project. Read package.json, tsconfig.json, web-test-runner.config.js, rollup.config.js, .eslintrc.json, .eslintignore, .prettierrc.json, .gitignore and src/test/my-element_test.ts first, and check whether a lockfile exists. Write .github/workflows/ci.yml that runs on push to main and on pull requests, with contents: read permissions, a concurrency group that cancels superseded runs and a timeout. In a test job on ubuntu-latest: check out, set up Node 22 with npm caching, install dependencies, run npx playwright install --with-deps, then npm run lint, npm run build and npm test as separate steps, in that order because the tests run against compiled output. Add a docs job that runs npm run docs. If there is no package-lock.json, run npm install, commit the lockfile and use npm ci; otherwise use npm ci as is. Run every step locally in the sandbox before opening the pull request, run actionlint on the workflow, add a badge to README.md, and describe in the pull request which steps run, which browsers are installed and why build precedes test.",
  "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

What comes back is a pull request that adds `.github/workflows/ci.yml`, a `package-lock.json` when the repository had none, and a badge line in `README.md`. The description lists the jobs and their steps, names the Node version and the three browsers installed, explains why `npm run build` runs before `npm test`, and states which command produced the lockfile so a reviewer knows it was not hand-edited.

The run's record keeps the output of each command the agent ran in its sandbox: the `lit-analyzer` and ESLint pass, the `tsc` build, the web-test-runner results per browser and per mode, the Eleventy docs build and the `actionlint` check. A reviewer can read those before the first Actions run on GitHub exists.

Before merging, a reviewer confirms the workflow's first run on the pull request is green, decides whether the `docs` job should stay as a required check, and whether to pin `BROWSERS=chromium` on pull requests to shorten the job and keep the full matrix for `main`.

## Run it on every new repository

A team that creates component repositories from the Lit starter can run this once per repository from its own server: one `POST /o/{org}/sessions` per new repository, each with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started instead of opening a second pull request.

To keep the workflow current after that, an automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "check that .github/workflows/ci.yml still runs every script this pull request adds to package.json, and update it on this branch if not" reads the diff and pushes to the pull request's branch. The trigger puts the pull request after the prompt; only pushes by an owner, member or collaborator fire it, never a fork's.

## Why run it on Rush?

A CI workflow for a browser test suite is the kind of file that is wrong on the first run for reasons you only see on a clean machine: no lockfile for `npm ci`, no browsers for Playwright, tests that read compiled files that were never built. The agent writes it on exactly that kind of machine, a fresh sandbox with nothing installed, runs every step there, and fixes the order and the install commands before the workflow ever runs on GitHub.

The sandbox keeps every command and its output, so the pull request can state that the five tests pass in Chromium, Firefox and WebKit in both Lit modes, and that the docs pipeline builds, with the log to show for it rather than a promise that the first green run will come.

## Frequently asked questions

### Why does the workflow need npx playwright install?

The starter's `web-test-runner.config.js` launches Chromium, Firefox and WebKit through `@web/test-runner-playwright`, which depends on the `playwright` package but does not download browsers on `npm install`. A GitHub runner starts without them, so the job installs them, with `--with-deps` so the Linux libraries they need are present too.

### Do I have to commit a package-lock.json?

Only if you want `npm ci` and the setup-node cache. The starter ships without one, and `npm ci` refuses to run in that case. The agent commits the lockfile that `npm install` produces and says so in the pull request; if you prefer to stay lockfile-free, it keeps `npm install` and drops the cache.

### Why does the build step run before the tests?

`tsconfig.json` compiles `src/` to the repository root, and the test runner is configured to read `./test/**/*_test.js`, the compiled copy of `src/test/my-element_test.ts`. Without a build the runner finds no test files and reports nothing, which looks like a pass.

### Can I run only Chromium on pull requests?

Yes. The config reads a `BROWSERS` environment variable, so a step can set `BROWSERS=chromium` for pull requests and leave the full set for pushes to `main`. The agent leaves the full set in both places by default and mentions this switch in the pull request.

### Does it change any file outside .github?

It adds a badge line to `README.md` and, when the repository had no lockfile, a `package-lock.json`. It does not touch `tsconfig.json`, the lint configuration or the test files, and it leaves the `format` script alone.

## More Lit jobs

- [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/)
- [Add an npm Release Workflow to a Lit Component](https://getrush.ai/run/add-release-workflow/lit/)

## The same job on other stacks

- [Add GitHub Actions CI to a Medusa Monorepo](https://getrush.ai/run/add-github-actions-ci/medusa/)
- [Set Up GitHub Actions CI for a Next.js App](https://getrush.ai/run/add-github-actions-ci/nextjs/)
- [Add GitHub Actions CI to a Phoenix App](https://getrush.ai/run/add-github-actions-ci/phoenix/)

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