README
¶
VersionGate
A lightweight, self-hosted, API-first service for managing mobile application releases and evaluating update policies. Given a client's current version, it decides whether the app should continue normally, be notified that an update is available, or be required to update before continuing.
VersionGate does not distribute application binaries — it only manages release metadata and update policies.
Quick start
Requires Docker and Docker Compose, plus a Go toolchain for the CLI (bootstrap/migrations):
git clone https://github.com/manuelzzz/versiongate.git
cd versiongate
docker compose up -d
Then apply the database schema and create your first Project and API Token with the CLI:
go install github.com/manuelzzz/versiongate/cmd/versiongate@latest
export VERSIONGATE_DATABASE_DSN="postgres://versiongate:versiongate@localhost:5432/versiongate?sslmode=disable"
versiongate migrate up
versiongate bootstrap --name "My Project"
See Installation and CLI bootstrap for the full walkthrough.
Documentation
Full docs: https://manuelzzz.github.io/versiongate/ (source under
docs/, built with Astro + Starlight per
specs/decisions/docs-site.md).
- Installation — Docker-based install, and how to uninstall.
- CLI bootstrap — creating the first Project and API Token with the CLI.
- Managing the database schema — applying, rolling back, and inspecting migrations.
- Publishing Releases — publishing a Release from CI/CD.
- Update Check — integrating the update-check endpoint in a mobile client.
- Contribute —
building, testing, and contributing (see also
CONTRIBUTING.md, the canonical version).
Project knowledge
specs/— domain concepts, protocols, and architectural decisions: the source of truth for why VersionGate is shaped the way it is..rules/— development rules and coding guidelines governing how code is written in this repository.AGENTS.md— entry point for how repository knowledge is organized, for humans and AI agents alike.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
server
command
|
|
|
versiongate
command
|
|
|
internal
|
|
|
application
Package application implements VersionGate's Application domain concept: a single distributable mobile app, scoped to exactly one Project, that Releases and Versions are evaluated against (specs/domain/application.md).
|
Package application implements VersionGate's Application domain concept: a single distributable mobile app, scoped to exactly one Project, that Releases and Versions are evaluated against (specs/domain/application.md). |
|
cli
Package cli implements the versiongate operator CLI.
|
Package cli implements the versiongate operator CLI. |
|
postgres
Package postgres wires VersionGate to its PostgreSQL database: connection pooling and schema migrations (specs/decisions/database.md).
|
Package postgres wires VersionGate to its PostgreSQL database: connection pooling and schema migrations (specs/decisions/database.md). |
|
project
Package project implements VersionGate's Project domain concept: the top-level organizational boundary that Applications, Releases, and API Tokens are scoped to (specs/domain/project.md).
|
Package project implements VersionGate's Project domain concept: the top-level organizational boundary that Applications, Releases, and API Tokens are scoped to (specs/domain/project.md). |
|
release
Package release implements VersionGate's Release domain concept: a published version of an Application for its platform (specs/domain/release.md).
|
Package release implements VersionGate's Release domain concept: a published version of an Application for its platform (specs/domain/release.md). |
|
token
Package token implements VersionGate's API Token domain concept: issuing, verifying, and revoking Project-scoped bearer credentials (specs/decisions/authentication.md).
|
Package token implements VersionGate's API Token domain concept: issuing, verifying, and revoking Project-scoped bearer credentials (specs/decisions/authentication.md). |
|
updatepolicy
Package updatepolicy implements the Update Policy Evaluation domain concept: the derived decision of whether a client on a given version should continue, be notified of an available update, or be required to update (specs/domain/update-policy.md).
|
Package updatepolicy implements the Update Policy Evaluation domain concept: the derived decision of whether a client on a given version should continue, be notified of an available update, or be required to update (specs/domain/update-policy.md). |
|
Package migrations embeds VersionGate's SQL schema migrations so they ship inside the compiled binary — no migrations/ directory needs to be present alongside a deployed VersionGate (e.g.
|
Package migrations embeds VersionGate's SQL schema migrations so they ship inside the compiled binary — no migrations/ directory needs to be present alongside a deployed VersionGate (e.g. |
Click to show internal directories.
Click to hide internal directories.