Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hotosm/tasking-manager/llms.txt

Use this file to discover all available pages before exploring further.

HOT Tasking Manager uses CircleCI to manage both continuous integration (automated testing on every pull request and branch push) and continuous deployment (automated builds and infrastructure updates triggered by pushes to specific git branches). The project follows a trunk-based development model with develop as the primary integration branch.

​
Branch-to-Environment Mapping

Deployments are triggered by pushing to named deployment branches. Each branch is associated with a specific environment and CircleCI context containing that environment’s secrets.
EnvironmentBranch
Productiondeployment/hot-tasking-manager
Production (frontend only)deployment/hot-tasking-manager-frontend
Stagingdevelop
TeachOSMdeployment/teachosm-tasking-manager
Indonesiadeployment/id-tasking-manager
Version tags are created from master/main after pull requests are reviewed and approved. The deployment branches are rebased from develop rather than merged, keeping a clean linear history.

​
Deploy to Production

1

Ensure develop is up to date

Pull the latest changes from the develop branch before rebasing:
git checkout develop
git fetch
git pull origin develop
2

Rebase and push the production branch

Rebase deployment/hot-tasking-manager onto develop and push to trigger the full deployment pipeline:
git checkout deployment/hot-tasking-manager
git pull origin deployment/hot-tasking-manager
git rebase develop
git push origin deployment/hot-tasking-manager
CircleCI detects the push, runs tests, builds the backend container, and deploys it to the production Auto Scaling Group via CodeDeploy.

​
Frontend-Only Deployment

If only frontend code changed, push deployment/hot-tasking-manager-frontend instead. This builds and syncs only the React assets to S3 — it is significantly faster and less disruptive than a full backend deployment because it does not replace EC2 instances: 
git checkout deployment/hot-tasking-manager-frontend
git rebase develop
git push origin deployment/hot-tasking-manager-frontend

​
CircleCI Contexts and Environment Variables

Each deployment environment has its own CircleCI context stored under Organisation Settings → Contexts. These contexts currently hold environment variables for frontend builds only. Backend environment variables are managed through the CloudFormation stack — see the Deployment guide for details. The following variables are configured per-environment context:
VariableDescription
OPSGENIE_APIOpsGenie API key for deployment alerts
TM_APP_API_URLBackend API URL for this environment
TM_APP_API_VERSIONAPI version string (e.g. v2)
TM_APP_BASE_URLFrontend base URL for this environment
TM_CONSUMER_KEYOSM OAuth consumer key (legacy)
TM_CONSUMER_SECRETOSM OAuth consumer secret (legacy)
TM_ENABLE_SERVICEWORKERWhether to register the service worker (0 or 1)
TM_MAPBOX_TOKENMapbox access token for map tile rendering
TM_MATOMO_ENDPOINTMatomo analytics tracker URL
TM_MATOMO_IDMatomo site ID
TM_ORG_CODEShort organisation code (e.g. HOT)
TM_ORG_NAMEFull organisation name
TM_ORG_PRIVACY_POLICY_URLURL of the privacy policy page
TM_ORG_URLOrganisation homepage URL
TM_SERVICE_DESKURL of the organisation’s service desk

​
Automated Tests

CircleCI runs backend and frontend tests on every pull request and every branch push. A dedicated CircleCI context named tasking-manager-testing provides the test database configuration:
VariableDescription
POSTGRES_DBDefault database name (e.g. tm). The test setup script creates test_<POSTGRES_DB> automatically.
POSTGRES_ENDPOINTHostname of the test PostgreSQL server
POSTGRES_USERPostgreSQL username for the test database
TM_ORG_CODERequired for tests that exercise template rendering (e.g. test_variable_replacing in TestTemplateService)
TM_ORG_NAMERequired for the same template rendering tests
The POSTGRES_DB variable must point to an existing default database (e.g. tm). The test runner creates a temporary database named test_tm during setup and drops it afterwards. Do not set POSTGRES_DB to the name of a database you cannot afford to lose.

​
Refreshing the CircleCI Cache

CircleCI caches the frontend node_modules directory between builds to speed up CI runs. If a build is behaving unexpectedly due to a stale cache (for example, after a major dependency upgrade), force a cache refresh by incrementing the CACHEVERSION environment variable in the CircleCI project settings. Set the value to v{n} where {n} is an integer incremented by 1 each time you wish to invalidate the cache (e.g. v1, v2, v3). All subsequent builds will perform a fresh yarn install.

​
Branch Naming Conventions

The project follows a consistent branch naming scheme:
PrefixPurpose
feature/New features under development
bugfix/Non-urgent bug fixes
hotfix/Urgent production fixes
deployment/Environment-specific deployment branches (never commit directly to these)
Development branches are opened as pull requests against develop. After review and CI passing, they are merged into develop. Deployment branches are only ever updated by rebasing from develop — direct commits to deployment branches are not permitted.

Build docs developers (and LLMs) love

Get started for freeTalk to us