Using CirCI
Hosted sites
Host a built Storybook, test report or docs next to the screenshots, behind sign-in, with addresses per commit and per branch.
CirCI can host the built Storybook, Playwright or Vitest report, coverage report or docs of a commit, so a reviewer opens the real thing next to the screenshots. Sites are served from their own domain and always need sign-in.
Turn it on for a project
Section titled “Turn it on for a project”Owners and admins switch hosting on per project: Project settings › General › Hosted sites › Host static sites, then Save changes. The checkbox only appears when the instance has a sites domain; without one, the Sites page says "Static site hosting isn't set up on this server" and, to an instance admin, which variable to set (STATIC_SITES_HOST, a separate domain). See Project settings.
Upload a site from CI
Section titled “Upload a site from CI”Use the project's CI token (shown once when you create the project; see CI examples for wiring it into CI) with the CLI:
circi storybook upload ./storybook-staticcirci site upload ./playwright-report --name playwrightcirci site upload ./coverage --kind coverage| Option | Meaning |
|---|---|
<dir> |
The built site: a folder with its index.html |
--name |
Which of the project's sites this is. Default site, or storybook for circi storybook upload |
--kind |
storybook, vitest-report, playwright-report, coverage, docs, generic or auto (the default) |
--spa |
Serve unknown paths with the entry page, for single-page apps |
--api-url |
The CirCI address, instead of CIRCI_API_URL |
Each upload belongs to a commit. A CI re-run of a commit replaces that commit's files and keeps its address. See CLI.
Addresses
Section titled “Addresses”Every upload gets two addresses on the sites domain:
| Kind | Address | Serves |
|---|---|---|
| Commit | the first 12 hex characters of the commit's SHA, a dash, the site name | That commit's site, exactly |
| Branch | the first 12 hex characters of a hash of the branch name, a dash, the site name | The newest upload on that branch |
For commit a1b2c3d4e5f6789… and a site named storybook on acme-sites.com, the commit address is a1b2c3d4e5f6-storybook.acme-sites.com.
A branch address moves only when the uploaded commit is the branch's current tip (its latest commit), and never for a pull request from a fork. When a project's pull requests have hosted sites, the summary comment on the pull request lists them under Hosted sites for this commit, each linked to its commit address.
The Sites page
Section titled “The Sites page”With hosting on and at least one site uploaded, Sites appears in the sidebar under the open project (and in project settings for owners and admins). For each site it shows:
- Custom domain, covered below.
- Branches: each branch's current address, the commit it points to and when it was updated.
- Uploads: recent uploads by commit, with branch, size and age. The commit links to its address.
Until the first upload, the page says "No sites yet" and shows the upload command with a copy button. The dashboard only links out: the sites themselves open on the sites domain.
Sign-in and access
Section titled “Sign-in and access”Opening a site sends you to the dashboard, which lets you in if you belong to the project's workspace. Signing out, or leaving the workspace, ends access within a minute. A session you end under Sessions in Account settings cuts off hosted sites too. How the sign-in handoff and the site's cookie work is in Site domains.
An address that doesn't exist, isn't yours or has never been used gets the same answer, so nobody can probe for addresses. An address whose site was removed by retention answers Site expired (HTTP 410) to people who may open it, and the same "not found" answer to everyone else.
Custom domain for the default branch
Section titled “Custom domain for the default branch”A site can have one custom domain, such as storybook.acme.com, that always serves the project's default branch: the newest upload that moved that branch's address. Commit and branch addresses stay as they are. Owners and admins set it; everyone else sees it.
-
Save the domain. In Custom domain, type it and choose Save domain.
-
Add the DNS record. Use a CNAME with the domain as its name, pointing to the target the page shows (
custom.followed by the sites domain). -
Choose Check DNS. The badge changes from Not verified to Verified, the domain is served and its certificate is issued once DNS points at the server. If the check fails, a warning says why.
Change edits the domain and Remove stops the site from opening on it (after a confirmation). A domain another site holds, the dashboard's host, or anything that shares cookie scope with it's refused: with the dashboard on ci.acme.io, storybook.acme.io is refused, but storybook.acme.com is fine. A domain that can't be a CNAME, such as an apex, can use A or AAAA records instead; the dashboard only shows the CNAME.
How long sites are kept
Section titled “How long sites are kept”Hosted site versions expire with their project's retention (Keep builds for, 30 days by default), except a version a live branch link still serves. See Retention and garbage collection and Workspace settings.