Skip to content

Latest commit

 

History

History
88 lines (61 loc) · 5.59 KB

release-workflow.md

File metadata and controls

88 lines (61 loc) · 5.59 KB

Release workflow

Read this document before creating a pull request or changing release and deployment configuration.

Pull requests

Read defaultBase from nx.json and use it as the pull request base. Use another base only when the task names one.

Releases and deployments

Release tags and deployment workflows can affect production. Change or run them only when the user explicitly requests that work.

The workflow files under .github/workflows/ define the active branch triggers, build configurations, and deployment branches. Inspect those files before release work. Do not rely on a copied branch map in documentation.

CI builds the applications that changed since the latest successful run of the same workflow on the branch. If CI cannot find that run, it uses the commit before the push, then HEAD~1. .github/scripts/get-affected-base.sh selects this base commit.

Tags create production releases:

  • A v<version> tag, for example v2611.1, releases all applications.
  • An <app>/v<version> tag, for example workplace/v2611.1, releases only that application. <app> is the folder name under apps/. CI tests the application and all libraries. If <app> is not an application, CI fails, so a misspelled name cannot release all applications.

The tagged commit must be on develop or on a hotfix/* branch. Push the commit to that branch before you push the tag. Otherwise, CI fails and does not deploy. tools/get-affected.js selects the applications from the tag. .github/scripts/check-release-source.sh checks the branches. It does not check review.

The Release tags repository ruleset lets only the admin and maintain roles create, move, or delete v*, */v*, and mobile/*/v* tags.

GitHub does not start workflows for tags when one push contains more than three tags. To release more than three applications, use one v<version> tag, or push the tags in separate pushes.

Deploys of one application to one build branch run one at a time. Before each production deploy, .github/scripts/check-release-order.sh checks that the tagged commit contains the source commit of the current build. Thus a tag on an older commit fails, and does not replace a newer build. Start a hotfix/* branch from the commit of the current production build. Merge the hotfix into develop before the next release from develop.

Mobile tags build Android and iOS artifacts. They do not deploy web applications:

  • A mobile/v<version> tag builds all mobile applications.
  • A mobile/<app>/v<version> tag builds one mobile application.

Web release tags do not build mobile applications. See Mobile builds.

CI writes the build/<project>/<environment> branches. Do not edit those branches directly.

The workflow generates application-specific changelogs once before the build jobs start. Each changelog includes commits that change the application, its transitive Nx dependencies, or files under shared/. Each commit stays in the release that contains it, also when the release tag is on a commit for a different application. An <app>/v<version> tag is a release only in the changelog of that application. In other application changelogs, its commits go to the next release of that application. The root CHANGELOG.md uses only v<version> tags. git-cliff reads the full history one time for all applications, because that read takes almost all of the generation time. Builds include CHANGELOG.md when generation and artifact transfer succeed. Changelog generation, upload, download, or copy failures do not block tests, builds, or deployment.

cliff.toml disables remote metadata lookups for both application and release changelogs. Their template uses only local commits and tags, so generation does not need GitHub API access. Run the generation regression tests with bun test tools/changelog-generation.test.js; they require git-cliff and jq on PATH (or GIT_CLIFF_BIN pointing to the generator binary).

Templates demo site

The frontend-templates Vercel project serves templates.demo.place.tech. Vercel deploys only the templates-demo branch. The Vercel team can create a limited number of deployments each day, and Vercel counts canceled deployments too. Thus, other branches must not create Vercel deployments:

  • The root vercel.json turns off Vercel deployments for all branches except templates-demo.
  • .github/scripts/publish-subdir.sh adds a vercel.json that turns off Vercel deployments to each build branch commit. Vercel reads vercel.json from the pushed commit, and build branches do not contain the root file.

The Templates Demo workflow moves templates-demo to develop once per day (17:00 UTC), if develop changed. To update the site now, run the workflow manually. Do not push to templates-demo directly.

Sentry source maps

Production builds of the apps that use Sentry make hidden source maps: the scripts do not link to them. Staging builds keep their linked source maps. The build writes a debug ID into each script and its source map.

After each build in the BUILD workflow, CI runs .github/scripts/register-sentry-debug-ids.mjs. The script adds code that registers each script's debug ID for the Sentry SDK, and updates the service worker hashes. CI then uploads the source maps to the placeos-dev project in the place-technology Sentry organisation. The upload needs the SENTRY_AUTH_TOKEN repository secret. Without the secret, CI does not change the build and skips the upload. An upload failure does not block the deployment.

The BUILD and PR Flow workflows delete the source maps from production builds before deployment.