Alpha Version history
Publish, browse and restore building-Type snapshots from your own GitHub repository
Version history for Types
Alpha can publish snapshots of any building Type to a GitHub repository that your tenant owns. Each snapshot is a real git commit, so:
- You get a full audit trail of who changed what and when, in a place you control.
- You can diff any past version against the current state from inside Alpha.
- You can restore a Type to an older snapshot: including the preview blob it referenced at the time, with one click.
Snapshots are explicit. Nothing leaves Alpha automatically. You publish a version whenever you've reached a state worth pinning.
One-time setup
The GitHub App must be configured server-side by an administrator (env vars
GITHUB_APP_ID,GITHUB_APP_PRIVATE_KEY,GITHUB_APP_SLUG,GITHUB_APP_STATE_SECRET). If the integration card under Settings → Integrations shows "GitHub App is not configured", reach out to ASRR.
Connect your tenant to a repo
- Open Settings → Integrations and scroll to the GitHub section.
- Click Connect to GitHub. You'll be sent to github.com to install the ASRR Alpha GitHub App on the org or user that owns the repo you want to use.
- On the GitHub side, pick Only select repositories and choose the one repository Alpha is allowed to write to.
- After approving the install you're redirected back to Alpha with a green "GitHub connected successfully" banner.
- The card now shows the accessible repos. Set:
- Repository:
owner/name, e.g.acme-bv/alpha-types. - Branch: defaults to
main. - Path prefix: defaults to
alpha-types; Type snapshots land at<prefix>/<typeId>/type.json.
- Repository:
- Click Save.
You only need to do this once per tenant. You can change the repo / branch / path prefix later, or Disconnect to revoke Alpha's write access.
Publishing a version
In the Type editor, open the ⋮ menu next to the Type name and pick Publish version.
- Enter a short commit message describing what changed (defaults to
Update <type name>). - Click Publish. Alpha will:
- Serialize the current state of the Type as pretty-printed JSON.
- Commit it to
<prefix>/<typeId>/type.jsonon the configured branch. - Copy any blobs the Type references (e.g. the preview image) into an immutable sibling Azure container, keyed by the commit SHA.
- Record the commit in Alpha so it appears in the Version history drawer.
Each publish is a single git commit. Browse the repo on github.com to see them.
Browsing history and diffing
From the same ⋮ menu pick Version history. A side drawer opens with:
- A table of past versions (newest first): message, author, when, short SHA.
- Click a row to load the historical JSON and see it side-by-side with the current state of the Type.
- The Open on GitHub → link jumps straight to the commit page on github.com if you want the prettier GitHub diff view.
Restoring an older version
In the Version history drawer, with a version selected:
- Click Restore this version (orange button, top-right of the diff panel).
- Alpha will:
- Fetch the historical JSON for that exact commit.
- Restore any blobs that have since been deleted from Alpha (copied back from the snapshot container).
- Overwrite the Type's fields with the historical values. The Mongo
_idof the Type stays the same; Project references that point at this Type keep working.
Restoring is a write. It creates fresh updated / updatedBy audit fields. If you want to "go back" without losing the current state, publish a version first, then restore. Both versions stay in your repo forever.
What lives where
| Where | Stores |
|---|---|
| Your GitHub repo | Pretty-printed Type JSON at <prefix>/<typeId>/type.json: source of truth for historical content. |
Alpha Mongo (type_versions) | One row per published version: commit SHA, message, author, the blob ids snapshotted at publish time. |
| Azure blob snapshot container | Immutable copies of the blobs each version referenced (<tenantId>/<commitSha>/<blobId>). |
Alpha Mongo (types) | The live current state of the Type: exactly what you're editing right now. |
Limits & known v1 gotchas
- GitHub-only for now. GitLab, Bitbucket and self-hosted Git are on the roadmap but not yet implemented.
- Single repo per tenant. You can't fan a tenant's Types out to multiple repos.
- Single branch per tenant. Publish always targets the configured branch, with no PRs and no per-version branches.
- Coverage blobs aren't snapshotted yet. Product coverage is recomputed deterministically from the Type and the live product catalogue, so it isn't versioned in v1. If you restore a very old Type and the products it references have since been removed, regenerate coverage from the Static models → Recalculate coverage button.
- The historical JSON in git is pretty-printed with sorted map keys, so diffs stay meaningful across refactors. Don't hand-edit those files on github.com; Alpha will overwrite them on the next publish.