Frontend (JavaScript/TypeScript)
Backend (JavaScript/TypeScript)
The is a fully functional set of GitHub Actions workflows and a starter application stack intended to help Agile teams hit the ground running.
Features:
- Pull Request-based pipeline
- Sandboxed development environments
- Gateable production deployments
- Container publishing (ghcr.io) and importing (OpenShift)
- Security, vulnerability, infrastructure, and container scan tools
- Automatic dependency patching available from bcgov/renovate-config
- Enforced code reviews and workflow jobs (pass|fail)
- Helm Package Manager for atomic deployments
- Prometheus Metrics export from Backend/Frontend
- Resource Tuning with Horizontal Pod Autoscaler (TEST/PROD only)
- Affinity and anti-affinity for Scheduling on different worker nodes
- Rolling updates with zero downtime in PROD
- Database Migrations with Flyway
- Pod disruption budgets for high availability
- Self-healing through with probes/checks (startup, readiness, liveness)
- Point the long-lived DEMO route to PRs by using the
demolabel - Sample application stack:
- Database: Crunchy(Postgres, PostGIS), backups, Flyway
- Frontend: TypeScript, Caddy Server
- Backend: TypeScript, Nest.js
- Alternative backend examples - see Alternative Backends
Initial setup is intended to take an hour or less. This depends greatly on intended complexity, features selected/excluded and outside cooperation.
The following are required:
- BC Government IDIR accounts for anyone submitting requests
- GitHub accounts for all participating team members
- Membership in the BCGov GitHub organization
- Provide GitHub IDs to BCGov's Just Ask
- OpenShift project namespaces:
Create a new repository using this repository as a template.
- Verify bcgov/quickstart-openshift is selected under Repository template
Variables and secrets are consumed by workflows. Environments provide their own values, overriding default sets.
Secrets are hidden from logs and outputs, while variables are visible. Using secrets exclusively can make troubeshooting more difficult.
Note: Dependabot, which we don't recommend as highly as Renovate, requires its own set of variables.
Click Settings > Secrets and Variables > Actions > Secrets > New repository secret
OC_TOKEN
OpenShift token, different for every project/namespace. This guide assumes your OpenShift platform team has provisioned a pipeline account.
- Consume:
{{ secrets.OC_TOKEN }}
Locate an OpenShift pipeline token:
- Login to your OpenShift cluster, e.g.: Gold or Silver
- Select your DEV namespace
- Click Workloads > Secrets (under Workloads for Administrator view)
- Select
pipeline-token-...or a similarly privileged token - Under Data, copy
token - Paste into the GitHub Secret
OC_TOKEN
OC_NAMESPACE
OpenShift project/namespace. Provided by your OpenShift platform team.
- Consume:
{{ secrets.OC_NAMESPACE }} - Value: format
abc123-dev | test | prod
SONAR_TOKEN(s)
If SonarCloud is being used each application will have its own token. Single-application repositories typically use ${{ secrets.SONAR_TOKEN }}, while monorepos use similar names.
E.g.:
${{ secrets.SONAR_TOKEN_BACKEND }}${{ secrets.SONAR_TOKEN_FRONTEND }}
BC Government employees can request SonarCloud projects by creating an issue with BCDevOps. Please make sure to request a monorepo with component names (e.g. backend, frontend), which may not be explained in their directions.
Click Settings > Secrets and Variables > Actions > Variables > New repository variable
OC_SERVER
OpenShift server address.
- Consume:
{{ vars.OC_SERVER }} - Value:
https://api.gold.devops.gov.bc.ca:6443orhttps://api.silver.devops.gov.bc.ca:6443
MS_TEAMS_WEBHOOK_URI
- Consume:
{{ vars.MS_TEAMS_WEBHOOK_URI }} - Value:
- Refrence: 'https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook?tabs=newteams%2Cdotnet' & 'https://learn.microsoft.com/en-us/outlook/actionable-messages/message-card-reference'
Environments are groups of secrets and variables that can be gatekept. This includes limting access to certain users or requiring manual approval before a requesting workflow can run. Environment values override any default values.
For pull requests and development surrounding lower-level, sandboxed environments it is best not to use an environment at all. Higher level environments, like TEST and PROD, will override those values as necessary.
Click Settings > Environments > New environment
Environments provide a number of features, including:
- Required reviewers
- Wait timer
- Deployment branches
Dependabot and Mend Renovate can both provide dependency updates using pull requests. Dependabot is simpler to configure, while Renovate is much more configurable and lighter on resources.
A config file (renovate.json) is included with this template. It can source config from our renovate repository. Renovate can be self-hosted or run using the GitHub App managed at the organization level. For BC Government the OCIO controls this application, so please opt in with them using a GitHub issue.
To opt-in:
- Visit the Renovate GitHub App
- Click
Configureand set up your repository - Visit BCDevOps Requests
- Select Issues
- Select New Issue
- Select Request for integrating a GitHub App
- Create a meaningful title, e.g.
Request to add X repo to Renovate App - Fill out the description providing a repository name
- Select "Submit new issue"
- Wait for Renovate to start sending pull requests to your repository
Dependabot is no longer recommended as an alternative to Renovate for generating security, vulnerability and dependency pull requests. It can still be used to generate warnings under the GitHub Security tab, which is only viewable by repository administrators.
Squash merging is recommended for simplified history and ease of rollback. Cleaning up merged branches is recommended for your DevOps Specialist's fragile sanity.
Click Settings > General (selected automatically)
Pull Requests:
[uncheck] Allow merge commits[check] Allow squash mergingDefault to pull request title
[uncheck] Allow rebase merging[check] Always suggest updating pull request branches[uncheck] Allow auto-merge[check] Automatically delete head branches
Packages are available from your repository (link on right). All should have visibility set to public for the workflows to run successfully.
E.g. https://github.com/bcgov/quickstart-openshift/packages
This is required to prevent direct pushes and merges to the default branch. These steps must be run after one full pull request pipeline has been run to populate the required status checks.
- Select
Settings(gear, top right) >Rules>Rulesets(under Code and Automation) - Click
New ruleset>New branch ruleset - Setup Ruleset:
- Ruleset Name:
main - Enforcement status:
Active - Bypass list:
- Click
+ Add bypass - Check
[x] Repository admin - Click
Add selected
- Click
- Target branches:
- Click
Add target - Select
Add default branch
- Click
- Branch protections:
[x] Restrict deletions[x] Require linear history[x] Require a pull request before merging- Additional settings:
Require approvals: 1(or more!)[x] Require conversation resolution before merging
- Additional settings:
[x] Require status checks to pass[x] Require branches to be up to date before merging- Required checks: These will be populated after a full pull request pipeline run!
- Click
+Add checks - This is our default set, yours may differ:
Analysis ResultsPR ResultsValidate Results
- Click
[x] Block force pushes[x] Require code scanning results- Click
+ Add tool - This is our default set, yours may differ:
CodeQLTrivy
- Click
- Click
Create
- Ruleset Name:
Don't forget to add your team members!
- Select Settings (gear, top right) *> Collaborators and teams (under
Access) - Click
Add peopleorAdd teams - Use the search box to find people or teams
- Choose a role (read, triage, write, maintain, admin)
- Click Add
Runs on pull request submission.
- Provides safe, sandboxed deployment environments
- Build action pushes to GitHub Container Registry (ghcr.io)
- Build triggers select new builds vs reusing builds
- Deploy only when changes are made
- Deployment includes curl checks and optional penetration tests
- Run tests (e2e, load, integration) when changes are made
- Other checks and updates as required
Runs on pull request submission.
- Enforces conventional commits in PR title
- Adds greetings/directions to PR descriptions
Runs on pull request submission or merge to the default branch.
- Unit tests (should include coverage)
- CodeQL/GitHub security reporting (now handled as GitHub default!)
- Trivy password, vulnerability and security scanning
Runs on pull request close or merge.
- Cleans up OpenShift objects/artifacts
- Merge retags successful build images as
latest
Runs on merge to main branch.
- Code scanning and reporting to GitHub Security overview
- Zero-downtime* TEST deployment
- Penetration tests on TEST deployment (optional)
- Zero-downtime* PROD deployment
- Labels successful deployment images as PROD
* excludes database changes
Runs on scheduled job (cronjob) or workflow dispatch.
- PR environment purge
- Generate SchemaSpy documentation
- Tests (e2e, load, integration) on TEST deployment
There is a long-lived custom route available to be assigned to specific Pull Request deployments. Add the label demo to that pull request or run the DEMO Route workflow.
Typical route: https://<REPO_NAME>-demo.apps.silver.devops.gov.bc.ca
Please note that the label must be manually created using GitHub's web interface.
The starter stack includes a frontend (React, MUI, Vite, Caddy), backend (Nest/Node) and postgres or postgis database. See subfolder for source, including Dockerfiles and OpenShift templates. Alternative backends are available.
Features:
- TypeScript strong-typing for JavaScript
- NestJS Nest/Node backend and frontend
- Flyway database migrations
- Crunchy Postgres/Postgis Database
Postgis is default. Switch to Postgres by removing the image names in crunchy helm chart values
Crunchy is the default choice for HA postgres/postgis DB in BCGov. provided chart is to get up and going fast, it is upto teams to fine tune resource allocation and patroni parameters of crunchy DB to get the best out of database.
- For specifying different resources for different envs, just add values-test.yml and values-prod.yml , then provide them to the DB Deployer in GHA.
- For enabling S3 backups/recovery, please enable in values file, and in the DB Deployer in GHA, then provide necessary secret values which are prefixed with
s3DB Deployer in GHA - To disable crunchy deployment, make the following changes
- make crunchy enabled to false in values.yaml
- make bitnami postgis enabled to true in values.yaml
- make the db-deployer false in gha workflow .deployer-db.yaml
The sample Java, Python and Go backends repository has been archived, but we have lots of other great examples of active projects you can learn from!
The database documentation is created and deployed to GitHub pages. See here.
After a full workflow run and merge can been run, please do the following:
- Select Settings (gear, top right) *> Pages (under
Code and automation) - Click
BranchorAdd teams - Select
gh-pages - Click
Save
- Flyway is used as Database Schema Migration tool
- Prisma is used as ORM layer
- The rationale behind using flyway to have schema first approach and let prisma generate ORM schema from the database, which would avoid pitfalls like , lazy loading, cascading et.. when defining entities in ORM manually.
- Run flyway in the docker compose to apply latest changes to postgres db.
- Run npx prisma db pull from backend folder to sync the prisma schema.
- Run npx prisma generate to generate the prisma client which will have all the entities populated based on fresh prisma schema.
- if using vscode be aware of this issue
This repository is provided by NRIDS Architecture and Forestry Digital Services, courtesy of the Government of British Columbia.
- NRID's Kickstarter Guide (via. Confluence, links may be internal)
Please contribute your ideas! Issues and Pull Requests are appreciated.