All jobs

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 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 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 with this body:

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

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading