# Share a CircleCI HTML Report Outside the Artifacts Tab

Canonical: https://commareports.com/ci/circleci-html-report
Published: 2026-08-19

> CircleCI will render your HTML artifact — for people with an org login, for 30 days, with nowhere to leave feedback. Publish the report to a stable URL from one step in config.yml instead.

# Share a CircleCI HTML report

Credit where it's due: CircleCI's Artifacts tab actually renders HTML. Add
`store_artifacts`, click the file, see the report. That's more than GitHub
Actions or GitLab.com will do for you.

The problems are all around it:

- **The URL changes every job.** There is no "the coverage report" link — only
  "the coverage report from job 48213", which is useless in a bookmark, a
  runbook, or a Slack message someone reads next Tuesday.
- **30-day retention.** The report from the release you're investigating in
  next quarter's review is gone.
- **Login required.** The reviewer must have CircleCI access to the project.
  For an engineer that's fine. For the PM, the security reviewer, the customer
  or the auditor, it's a non-starter — and it's exactly why reports get
  screenshotted.
- **Nowhere to respond.** The artifact is a dead end. Every question about it
  happens somewhere else, detached from the thing it's about.

## Publish it from the job instead

Store a [scoped token](/docs/api-tokens) (`reports:write` only) as a project
environment variable, create the report once, and `PATCH` it every run:

```yaml
version: 2.1

jobs:
  test:
    docker:
      - image: cimg/python:3.12
    steps:
      - checkout
      - run: pip install -r requirements.txt
      - run:
          name: Run tests with coverage
          command: pytest --cov --cov-report=html
      - store_artifacts:
          path: htmlcov
      - run:
          name: Publish report to Comma
          when: always
          command: |
            curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$COMMA_REPORT_ID" \
              -H "Authorization: Bearer $COMMA_API_TOKEN" \
              -H "Content-Type: application/json" \
              -d "$(jq -n --rawfile html htmlcov/index.html \
                    --arg title "Coverage — $CIRCLE_SHA1" \
                    '{title: $title, html: $html}')"
            echo "Report → https://commareports.com/p/$COMMA_REPORT_ID"
```

`when: always` is the important flag — the red runs are the ones worth
reading, and the default only publishes on green.

Note that `store_artifacts` stays. Keeping the artifact for engineers who are
already in CircleCI costs nothing; the published report is for everyone else.

## What the published copy adds

- **One URL, forever.** Each job appends a revision at the same address, and
  any two revisions can be diffed — "what changed since the last green build"
  becomes a question with an answer.
- **Readers without a CircleCI seat.** Visibility is
  [private, team, domain-gated, or link](/docs/sharing), independent of your CI
  provider's ACL.
- **Comments anchored to the content.** A reviewer highlights the line that
  regressed and pins a thread to it, and that thread survives every subsequent
  run — see [commenting on HTML](/comment-on-html).
- **No retention clock.** Revisions stay.
- **Announcements.** A [webhook](/docs/api) on `revision.created` posts the new
  revision to Slack or Discord.

## Limits

- **HTML body: 5 MB.** Screenshots, videos and archives go in as
  [assets](/docs/api) at 25 MB per file, 250 MB per report.
- **Scripts are stripped on write**, so a JavaScript-application report
  (Allure, Playwright's default reporter) should be published as a static
  digest with the archive attached — see
  [sharing an Allure report](/share-allure-report).
- **Rate limit: 60 requests/minute per token.** One publish per build is
  nowhere near it.

## Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision
history.

**[Create your first report →](https://commareports.com/)**

### Related

- [Publish from CI](/docs/ci) — the general pipeline pattern
- [GitHub Actions HTML reports](/ci/github-actions-html-report)
- [GitLab CI HTML reports](/ci/gitlab-ci-html-report)
- [Jenkins HTML reports](/ci/jenkins-html-report)