Read this document before creating a pull request or changing release and deployment configuration.
Read defaultBase from nx.json and use it as the pull request base. Use another base only when the task names one.
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 examplev2611.1, releases all applications. - An
<app>/v<version>tag, for exampleworkplace/v2611.1, releases only that application.<app>is the folder name underapps/. 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).
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.jsonturns off Vercel deployments for all branches excepttemplates-demo. .github/scripts/publish-subdir.shadds avercel.jsonthat turns off Vercel deployments to each build branch commit. Vercel readsvercel.jsonfrom 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.
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.