# Staged Publishing for HTML Reports: Edit a Shared Report Without Readers Seeing the Draft

Canonical: https://commareports.com/staged-publishing-html-report
Published: 2026-10-26

> Keep one share link for a report while you keep editing it. Readers see the last approved revision; reviewers see the latest draft. The new version goes live only when someone approves it.

# Staged publishing: edit a shared report without readers seeing the draft

Sending the link is the easy part. The hard part is the next morning, when
the numbers need fixing and the link is already in front of the CFO, the
client, or forty people in `#metrics`.

Most tools give you two bad choices. You can edit the live page, and everyone
watching sees your half-finished changes. Or you can publish a second copy,
and now there are two links, and some people are reading the old one.

Comma has a third option. **The link keeps showing the last approved version
while you work on the next one.** When a reviewer approves the new draft,
readers move to it on the same URL.

## How it works

1. **Publish the report.** Paste HTML or Markdown, upload a folder, or have
   an agent call `create_report`.
2. **Get one approval.** Share the link with a reviewer as a commenter. They
   click **Approve** next to the report. See
   [how sign-off works](/approve-html-report).
3. **Turn on staged publishing.** In the share dialog, click **Publish only
   approved revisions**. The toggle then reads _Viewers see the last
   approved revision_.
4. **Send the link to everyone.**
5. **Keep editing.** Every save makes a new revision. Readers stay on the
   approved one. Your reviewer sees the draft, comments on it, and approves
   it when it's right.
6. **Readers move to the new version on their next page load.** Same URL,
   no announcement needed.

## Who sees what

| Person opening the link                                        | Sees                   |
| -------------------------------------------------------------- | ---------------------- |
| You (the owner)                                                | Latest draft           |
| Signed-in reviewer on a comment or edit link                   | Latest draft           |
| View-only reader                                               | Last approved revision |
| Anonymous visitor on a public link                             | Last approved revision |
| Visitor who entered the share password                         | Last approved revision |
| Readers of an [embed](/embed-html-report) on your docs or wiki | Last approved revision |

Reviewers need to see the draft, because reviewing it is their job. Everyone
else gets the version someone has already signed off on.

## The rules, exactly

- **Nothing is held back until the first approval.** With no approved
  revision, readers see the latest version. The share dialog says this
  rather than letting you assume otherwise. Approve first, then send the link.
- **Approvals move readers forward, never back.** The approved pointer only
  advances. An approval on an older revision can't rewind it, and retracting
  an approval doesn't un-ship content readers already saw.
- **The URL never changes.** Links in email, Slack, Notion, Confluence and
  [embeds](/embed-html-report) keep working through every version.
- **Old revisions are kept.** Revision history is unlimited on every plan,
  so you can always see exactly what readers were shown and when.

## When it's worth turning on

- **Client deliverables.** The client sees the version you agreed on, not
  the one you're fixing at 11pm.
- **Weekly and monthly reports to leadership.** The analyst refreshes the
  numbers, the lead approves, and only then does the update reach the list.
- **Reports an agent regenerates on a schedule.** A
  [routine](/features/routines) can rebuild the report every morning. With staged
  publishing on, nobody outside the review loop sees today's output until a
  person approves it. That makes overnight automation safe to point at
  stakeholders.
- **Public status pages and changelogs** where a typo stays up for hours
  once people read it.
- **Release gates.** QA approves the test or coverage report for the build
  that ships, and the link the release notes point at shows that run.

## What it is not

Staged publishing decides **what readers are shown**, not **what they're
allowed to read**. The draft is still part of a report they can open, so a
determined person with API access could still read it. The point is to keep
stakeholders from seeing unfinished numbers, not to keep secrets from an
adversary.

If a person must not see the content at all, use the access controls
instead: [private visibility or a share password](/password-protect-html-report),
or [company-domain sharing](/share-html-report-internally).

## Turning it on from an agent or the API

Agents use the MCP tool `set_report_sharing`:

```
set_report_sharing(report_id: "6f1c…", show_approved_only: true)
→ { show_approved_only: true, approved_revision_id: "a91e…", … }
```

Over REST, the same field goes to the share endpoint with a token that has
the `sharing` scope:

```bash
curl -X PUT https://commareports.com/api/v1/reports/REPORT_ID/share \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "show_approved_only": true }'
```

`approved_revision_id` is `null` until the first approval, which is how an
agent can tell readers are still seeing the latest version. To approve, a
reviewer (or an agent acting as one) calls `set_report_signoff`, or POSTs to
`/api/v1/reports/:id/signoffs`. See the [API docs](/docs/api) and the
[sharing docs](/docs/sharing).

A simple pattern for an agent that regenerates a report every day: update
the report, call `request_review` so your agent reviewers leave anchored
comments on the new draft, and leave staged publishing on. Readers only move
once a person reads the draft and approves it.

## Try it

Publish a report, ask a teammate to approve it, turn on **Publish only approved revisions**, then change a number.
Open the link in a private window: it still shows the old number until the
new revision is approved.

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

### Related

- [Get sign-off on an HTML report](/approve-html-report)
- [Leave anchored comments on an HTML report](/comment-on-html)
- [Embed an HTML report on another site](/embed-html-report)
- [Password-protect an HTML report](/password-protect-html-report)
- [Share an HTML report only with your company](/share-html-report-internally)
- [Scheduled HTML reports](/features/routines)