version.cam

Source README.md · versioncam 0.5.3 from npm

version.cam renders what versioncam publish sends and keeps each clip at a living address, clips.version.cam/<owner>/<repo>/<clip>. It plays the newest version from your default branch that passed, so a page that embeds it never needs editing. Projects are managed on app.version.cam.

Connect a repository

Sign in at app.version.cam with GitHub, and install the Versioncam GitHub App on the repositories you choose. Then publish from GitHub Actions with the versioncam Action, which signs in with GitHub’s own token, so there is no secret to store. A repository’s project appears the first time it publishes, or when the App is installed on it.

The App is how version.cam learns from GitHub, each time someone signs in, who may do what: whoever may read a repository sees its project, and whoever administers the repository changes the project’s settings. The App also reports each publish on GitHub: a check on its commit, and on a pull request a comment naming the clips that look different and the ones that failed.

Plans

Priced per project, never per seat, and planned until the first bill confirms them. Free, for public repositories: three projects, ten clips a project, thirty days of history, clips to sixty seconds, a gigabyte, the pull request check and the badge. Pro, $35 a project a month or $350 a year: private repositories too, unlimited history, a hundred clips a project, and the team told by email, Slack or a GitHub issue when a clip breaks. Max, $145 a month for ten projects with everything Pro has. The recorder and the Action are free whatever the plan. While the beta is private nothing is sold: Free works for anyone who signs in, and the first ten accounts that write to hello@version.cam have Pro free until it ends.

When a clip breaks

A clip breaks when its check fails on the default branch: a control it uses was renamed or removed, a page moved, a step waited for something that never came, or the app would not start. A change in how the app looks never breaks a clip. It makes a new version.

Your pages keep playing the last version that passed, and say nothing about the break. A project that wants its viewers told, open source docs perhaps, turns on “Tell viewers when a clip is broken” in its settings.

On every plan, CI says so, and so does the dashboard: a pull request’s check fails and the Action comments on it, the App’s check on the commit says the clip is broken, and the summary of the job that publishes says what your pages play meanwhile.

On Pro and Max, version.cam also tells your team, by email, in Slack or with a GitHub issue, as the project’s settings choose. It reminds them two days after a clip broke and then every week, until the clip passes again or someone acknowledges it on the dashboard (“I know, keep the old one”). An acknowledged clip gets one more reminder a month later if it is still broken. When the clip passes again, the team is told it is fixed.

Who can see the clips

Visibility	Who can see the clips
public	Anyone, and search engines.
unlisted	Anyone with the address, kept out of search. The address is made of names, so unlisted means not listed, not secret.
private	Whoever GitHub lets read the repository, signed in at app.version.cam.

A private repository’s clips start private, and a public repository’s start public. A private clip plays only for the people who may see it, so never on a public page: to show a private repository’s clips in public docs or on a landing page, make them public or unlisted in the project’s settings.

From the command line

versioncam cloud does what the dashboard does, from a terminal, and so from an agent working in one:

npx versioncam cloud login              # a code you approve in a browser, once a week
npx versioncam cloud status             # this repository's clips: current or broken, and what plays
npx versioncam cloud failure checkout   # where a broken clip stopped, and the page as it was

Signing in. cloud login prints an address and a code. Open the address on any device, sign in with GitHub, check that the page shows the same code, and approve it. Nothing calls back to the machine that runs the command, so it works over SSH and in a sandbox. The command line then holds a token that lasts seven days, in ~/.config/versioncam/credentials.json, or under $XDG_CONFIG_HOME when that is set: a file only you may read, which no command prints. cloud logout revokes it. VERSIONCAM_API, set in the shell, points the commands at another version.cam, and each one’s sign-in is kept apart. Unlike publish, they never take it, or XDG_CONFIG_HOME, from a .env file, so a repository you clone cannot send your sign-in to a server of its choosing, or have the token written inside it.

Reading needs nothing more. status lists the clips: current or broken, since when, who acknowledged a broken one, and the version your pages play meanwhile; then the plan, and where to manage the project. failure <clip> says which step stopped a broken clip and why, and saves the page as it was then to .versioncam/failures/<clip>.png. embed <clip> prints the snippets that embed it, and plan says which plan, why and until when, and where to upgrade and pay. Each takes --json. They act on the repository they run in, from its origin remote on GitHub, or on the one that --project owner/repo names. ack <clip> is the dashboard’s “I know, keep the old one”.

A setting changes only once you approve it in the browser, one change at a time. cloud set visibility public prints the change in a sentence, an address and a code, and waits up to ten minutes. The page shows exactly that change, so an agent running the commands for you cannot change a project without you seeing what it asked for. The settings are visibility, retention, viewers (“Tell viewers when a clip is broken”) and alerts, by email, in Slack or with a GitHub issue.

Three things stay a click on app.version.cam: paying (cloud plan prints the page), deleting a project, and making a project token for CI outside GitHub.

The authoring skill runs these commands too: /versioncam status, /versioncam fix [clip] and /versioncam embed <clip>.

Other CI

A repository on GitHub publishes from GitHub Actions, whatever builds it otherwise. GitHub’s token says which repository, commit and branch a run is of, and version.cam takes them from it. A project token, VERSIONCAM_TOKEN, would have to say all that itself, with nothing to check it against, so it speaks only for a project with no GitHub repository.

So when your CI runs elsewhere, run just the clips in GitHub Actions: a workflow beside the CI you have, with the versioncam Action checking the clips on pull requests and publishing them from your default branch. The Action’s README has one to copy.

A repository outside GitHub publishes with a project token, given to versioncam publish as VERSIONCAM_TOKEN and made on the project’s page at app.version.cam. Its project is set up by hand: write to hello@version.cam.