Tollgate

Tollgate is a monorepo managed with pnpm workspaces and turbo. It contains reusable packages under packages/ and deployable services under services/.

Requirements

• Node.js >=22.0.0
• pnpm >=10.0.0
• Bun >=1.1.0

Workspace Commands

• pnpm install
• pnpm dev
• pnpm lint
• pnpm test
• pnpm build

Release Policy

Tollgate uses a single-version release model for the entire repository.

• The root package.json version is the authoritative release version for the monorepo.
• packages/* and services/* must stay aligned with the root version unless an explicit future policy says otherwise.
• Releases follow Semantic Versioning 2.0.0.
• MAJOR is reserved for backward-incompatible public API or contract changes.
• MINOR is reserved for backward-compatible features.
• PATCH is reserved for backward-compatible fixes and internal corrections with user-visible impact.
• All unreleased work must be documented only in CHANGELOG.md under ## [Unreleased] until the release is cut.
• Git tags use the vX.Y.Z format.

Changelog Policy

The root CHANGELOG.md is the only changelog for the repository and must follow Keep a Changelog 1.1.0.

• Use only Added, Changed, Deprecated, Removed, Fixed, and Security.
• Every entry must explain the technical reason for the change.
• Mention dependency versions when they affect compatibility or behavior.
• Include code examples when a public API or contract changes.
• Reference the related Jira issue as TOLL-XX when applicable.
• Do not add vague entries such as fix bug, small changes, or misc improvements.

Release Workflow

1. Update CHANGELOG.md under ## [Unreleased] with categorized entries.
2. Run pnpm version patch, pnpm version minor, or pnpm version major.
3. Review the generated release section and the synchronized workspace package versions.
4. Push the release commit and tag with git push --follow-tags.

CI/CD

GitLab CI runs lint, package/service tests, build, npm package publishing from main, and an automatic production deploy to Fly.io.

• Merge requests run validation jobs (lint, test:*, build).
• main runs validation, publishes @tollgate-dc/core and @tollgate-dc/sdk to npm when the current version is not already published, and then deploys to Fly.io.
• main runs validation and then deploys with flyctl deploy --remote-only, letting Fly/Depot build the app directly from the repository.
• Production does not depend on a Docker image published to the GitLab Container Registry.

Required GitLab CI/CD variables:

• NPM_TOKEN
• FLY_API_TOKEN_VALUE
• FLY_APP_NAME

FLY_API_TOKEN_VALUE should contain only the token payload after the FlyV1 prefix. The pipeline reconstructs FLY_API_TOKEN at runtime so the GitLab variable can remain masked even though Fly's final token format contains a space.

NPM_TOKEN must be allowed to publish public packages under the @tollgate-dc scope on npm. The pipeline publishes @tollgate-dc/core first and then @tollgate-dc/sdk, rewriting the SDK manifest only in CI/publish temp space so npm sees an exact @tollgate-dc/core semver instead of workspace:*.

Runtime secrets for the API are not stored in .gitlab-ci.yml; configure them in Fly with fly secrets set, including at least:

• JWT_SECRET
• REDIS_URL
• TOLLGATE_SIWE_DOMAIN
• TOLLGATE_WALLET_ADDRESS
• POLYGON_RPC_URL when private RPC access is required

Fly injects those values into the running machine as runtime environment variables. The API reads them from process.env; they are not baked into the Docker image during build.

The root version lifecycle scripts automate these release tasks:

• preversion validates that CHANGELOG.md contains releasable Unreleased entries and that workspace package versions still match the current root version.
• version moves categorized Unreleased entries into ## [x.y.z] - YYYY-MM-DD, resets the Unreleased template, and synchronizes all workspace package versions to the new root version.
• postversion prints the expected vX.Y.Z tag name and the push command for the maintainer.

For local package validation before shipping, run:

• bun run build
• bun run publish:npm:dry-run