GitHub project setup (board, labels, issues)

Your remote is already configured (example: Jjustmee23/omnihub-schoolV2). This doc explains how to finish the GitHub-side project: Project board, labels, and starter issues.

1. Install GitHub CLI (gh)

• Windows: GitHub CLI releases or winget install GitHub.cli
• macOS: brew install gh

Authenticate:

gh auth login

Verify:

gh auth status

2. GitHub Projects — extra token-scope (eenmalig)

gh project … (board aanmaken, koppelen, issues toevoegen) vraagt project en read:project op je token. Standaard-login heeft dat vaak nog niet.

Voer eenmalig uit en voltooi de browser/device flow:

gh auth refresh -s project,read:project -h github.com

Daarna kun je het volledige board automatisch zetten vanuit de repo-root (uitgevoerd voor project #4 — OmniTrack roadmap, zie GitHub Projects):

PowerShell

.\scripts\github\create-roadmap-project.ps1

cmd / Bash

node scripts/github/create-roadmap-project.mjs

Dat script: zoekt of "OmniTrack roadmap" al bestaat → zo niet, maakt het project aan → koppelt deze repo → voegt alle open issues toe. Titel aanpassen: set PROJECT_TITLE=Mijn board (Windows) of PROJECT_TITLE="…" node … (Unix).

Handmatig (zonder script)

gh project create --owner Jjustmee23 --title "OmniTrack roadmap"
gh project link <nummer> --owner Jjustmee23 -R Jjustmee23/omnihub-schoolV2
gh project item-add <nummer> --owner Jjustmee23 --url https://github.com/Jjustmee23/omnihub-schoolV2/issues/1

Vervang <nummer> door het projectnummer uit gh project list --owner Jjustmee23.

Suggested columns (Table layout):

Column	Purpose
Backlog	Triaged ideas, not scheduled
Ready	Spec’d, ready for implementation
In progress	Active development
In review	Open PR linked to the issue
Done	Merged / released / accepted

Optional Status field values can mirror your release train (e.g. “Next deploy”, “Blocked”).

Automatisering: taken op het board en naar “Done”

Je hoeft daarvoor niet per se iets in de repo-code te zetten. GitHub Projects heeft ingebouwde workflows:

1. Open je project (bijv. OmniTrack roadmap #4) → menu ⋯ (of Project) → Workflows (of “Project workflows”, afhankelijk van de UI).
2. Schakel workflows in zoals: als een issue wordt gesloten → zet status op Done (en eventueel: nieuwe issues uit gekoppelde repo’s automatisch op dit board).
3. Sla op en zet de workflow aan.

Taken op het board zetten:

• Bestaand issue uit de repo: + Add item → issue zoeken, of vanaf de issue-pagina Projects toevoegen.
• Alleen op het board (geen issue in de repo): + → Draft (concepttaak); later kun je die vaak omzetten naar een echt issue als je wilt.

Afgerond / Completed: ofwel automatisch (issue sluiten triggert “Done” als je die workflow aan hebt), ofwel handmatig de kaart naar de kolom Done slepen.

Meer detail: Using the built-in automations.

Mooi overzicht: roadmap, features en bugs niet door elkaar

Gebruik één GitHub-project met meerdere views (filters per label/type). De volledige stap-voor-stap checklist (velden, 12+ views, Roadmap, default view) staat hieronder in §2c.

2c. Volledige checklist — één project, meerdere views (OmniTrack roadmap #4)

Doel: project #4 als enige backlog; roadmap / features / bugs / areas gescheiden door views, niet door alles in één ongefilterde lijst.

2c.1 Velden + repo-koppeling (CLI, reproduceerbaar)

Vanaf repo-root (met gh ingelogd + project-scope, zie §2):

gh project link 4 --owner Jjustmee23 -R Jjustmee23/omnihub-schoolV2
gh project field-create 4 --owner Jjustmee23 --name "Target date" --data-type DATE
gh project field-create 4 --owner Jjustmee23 --name "Delivery phase" --data-type SINGLE_SELECT --single-select-options "Backlog,Ready,In progress,In review,Done,Blocked"

(Vervang 4 / owner / repo door jouw projectnummer en pad — of gebruik het script hieronder dat ze automatisch zoekt.)

• Delivery phase — volledige workflow zoals in het plan (Backlog → Blocked).
• Target date — nodig voor de layout Roadmap (tijdlijn op de kaart).

Alle standaard-views in één keer (aanbevolen): vanaf repo-root:

gh auth refresh -s project,read:project -h github.com
node scripts/github/setup-project-views.mjs

PowerShell: .\scripts\github\setup-project-views.ps1
Zelfde filters/layouts als de tabel in §2c.4; dubbele view-namen worden overgeslagen. Zie scripts/github/setup-project-views.mjs voor env (PROJECT_ORG + PROJECT_OWNER_TYPE=org voor org-projecten).

Controle velden:

gh project field-list 4 --owner Jjustmee23 --format json

2c.1b Volledige CLI-keten (project + labels + views + optioneel roadmap-issues)

gh auth refresh -s project,read:project -h github.com
node scripts/github/sync-labels.mjs
node scripts/github/create-roadmap-project.mjs
node scripts/github/setup-project-views.mjs
# optioneel alle roadmap-issues uit manifest:
# node scripts/github/populate-omnitrack-roadmap.mjs

2c.2 Status (GitHub) vs Delivery phase (custom)

GitHub voegt een ingebouwd veld Status toe met vaak Todo / In Progress / Done; ingebouwde workflows (issue gesloten → Done) werken daar typisch op.

• Voor Board-views die exact het plan volgen (Backlog … Blocked): kies Group by → Delivery phase (niet het ingebouwde Status-veld, tenzij je die opties in de GitHub-UI handmatig hebt uitgebreid).
• Houd in het team één afspraak: óf workflows + Status als waarheid, óf Delivery phase bijwerken naast Status. Minimaal: nieuwe items op Delivery phase = Backlog zetten.

2c.3 Workflows in de browser (controleren, niet in git)

1. Open OmniTrack roadmap #4 → ⋯ / Project → Workflows.
2. Zet aan: when an issue is closed → set item Status to Done (of NL-equivalent), zodat afgeronde issues niet op “Todo” blijven hangen.
3. Optioneel: auto-add nieuwe issues/PR’s uit de gekoppelde repo naar dit project.

Zie ook Using the built-in automations.

2c.4 Views aanmaken (primair: CLI via gh api)

Standaard-views (All work, Features, Bugs, Roadmap, …) kun je automatisch aanmaken:

node scripts/github/setup-project-views.mjs

Het script roept de GitHub REST API aan (gh api … POST …/projectsV2/{n}/views) met dezelfde filters als onderstaande tabel. Handmatig in de browser hoeft alleen nog als je het script niet draait, of voor fine-tuning.

Let op (GitHub-documentatie): views op een user-owned project kunnen met sommige fine-grained PAT’s voor gh 403 geven. Oplossingen: org-owned project (PROJECT_OWNER_TYPE=org + PROJECT_ORG=…) of een classic PAT met project-scope voor gh auth login.

Zelfde view-definities (naam, filter, layout) — handmatig aanmaken kan zo:

1. + New view (of View → New view).
2. Name invullen.
3. Onder Filter de query plakken (labels met : tussen quotes: label:"type:feature").
4. Layout kiezen: Table, Board, of Roadmap.
5. Group by: voor boards meestal Delivery phase; voor tabellen vaak ook Delivery phase of Status — wat je team kiest (zie §2c.2).
6. Sort instellen (kolom Updated / Created).
7. Save / view-naam bevestigen.

#	View-naam	Filter (plakken)	Layout	Group by (aanbevolen)	Sort (aanbevolen)
1	All work	(leeg)	Table	Delivery phase	Updated desc
2	Roadmap (epics)	label:roadmap	Board	Delivery phase	Updated desc
3	Roadmap batch	label:omnitrack-roadmap-batch	Table	Delivery phase	Updated desc
4	Features	label:"type:feature"	Board	Delivery phase	Updated desc
5	Bugs	label:"type:bug"	Board	Delivery phase	Created asc
6	Docs & ops	label:"type:docs"	Table	Delivery phase	Updated desc
7	Dependencies	label:dependencies	Table	Delivery phase	Updated desc
8	P1 nu	label:"priority:P1" is:issue is:open	Board	Delivery phase	Updated asc
9	Telematics	label:"area:telematics"	Table	Delivery phase	Updated desc
10	Deploy / CI	label:"area:deploy"	Table	Delivery phase	Updated desc
11	Frontend	label:"area:frontend"	Table	Delivery phase	Updated desc
12	i18n	label:"area:i18n"	Table	Delivery phase	Updated desc

Optionele view 13 — Roadmap timeline: layout Roadmap; filter label:roadmap is:issue is:open; in de view-instellingen date field = Target date (aangemaakt in §2c.1). Het script setup-project-views.mjs maakt een basis-roadmap-view met filter aan; stel Target date als tijdlijnveld nog in de browser in als GitHub dat vereist. Zonder ingevulde Target date op items blijft de tijdlijn leeg.

Meer over filters en layouts: Filtering projects en Changing layout and grouping.

2c.5 Default view en tab-volgorde

• Kies één default view (ster-icoon / “Set as default view”): aanbevolen All work (1) of Features (4).
• Sleep view-tabs zodat All work, Features, Bugs, Roadmap (epics) vooraan staan.

2c.6 Onderhoud (labels)

Repo-labels staan in scripts/github/labels.json. PR-path labels komen uit .github/labeler.yml. Nieuwe issues: minstens type:* of roadmap + priority:* waar van toepassing, anders verdwijnen ze uit type-gefilterde views.

B. Meerdere projecten — echt gescheiden boards (meer onderhoud):

• Maak bv. een tweede project “OmniTrack — bugs” of “Sprint” en koppel dezelfde repo (gh project link …).
• Voeg alleen relevante issues toe (handmatig of via automations / workflows).
• Nadeel: een issue kan op meerdere boards staan; je moet afspreken waar je “de waarheid” beheert.

C. Issues-tab in de repo — snelle lijsten zonder project:

• Gebruik de zoekbalk: is:issue is:open label:type:feature en bookmark de URL.
• Zelfde voor label:roadmap, label:type:bug, enz.

D. Milestones / iterations — voor release- of sprint-overzicht naast labels.

3. Sync labels

Labels are used by automation (e.g. Dependabot, PR labeler). From the repo root:

PowerShell (Windows):

./scripts/github/sync-labels.ps1

Bash:

./scripts/github/sync-labels.sh

Scripts use gh label create with --force to update colours if they already exist. Internally they run node on sync-labels.mjs / create-initial-issues.mjs (no jq required).

4. Create starter issues (optional)

After labels exist:

PowerShell:

./scripts/github/create-initial-issues.ps1

Bash:

./scripts/github/create-initial-issues.sh

Each script checks gh and creates a small set of roadmap / hygiene issues (no secrets). Edit the scripts if you want different titles.

4b. Volledige roadmap-issues op het GitHub Project

Na labels sync en project-koppeling:

1. Zorg dat scopes voor Projects gezet zijn (gh auth refresh -s project,read:project -h github.com).
2. Sync labels (nieuwe labels roadmap en omnitrack-roadmap-batch):

node scripts/github/sync-labels.mjs

3. Maak of hergebruik het project en koppel de repo (zoals in §2):

node scripts/github/create-roadmap-project.mjs

4. Maak alle roadmap-issues uit scripts/github/roadmap/manifest.json en voeg ze toe aan het project OmniTrack roadmap:

PowerShell

./scripts/github/populate-omnitrack-roadmap.ps1

Bash

./scripts/github/populate-omnitrack-roadmap.sh

Het script is idemponent: als er al issues met label omnitrack-roadmap-batch bestaan, stopt het (geen dubbele batch). Opnieuw draaien met een nieuwe batch: oude issues sluiten of tijdelijk FORCE_ROADMAP_RECREATE=1 (let op duplicaten).

5. Branch protection (recommended)

In GitHub: Settings → Branches → Add branch protection rule for main:

• Require a pull request before merging
• Require status checks to pass (select jobs from CI and production deploy, Docs site build, etc.) — do not require Dependabot auto-merge as a branch check (that workflow only runs for Dependabot PRs; requiring it would block normal PRs).
• Optionally: require linear history, disallow force-push
• Turn on Allow auto-merge under Settings → General → Pull requests so Dependabot PRs can queue a squash merge after checks pass. If you require approvals, add a ruleset/bypass for Dependabot or auto-merge will wait forever unless a human approves.

Exact check names appear after the workflows have run at least once on a PR.

Dependabot — fewer branches and shorter CI queues

• Grouped updates are configured in .github/dependabot.yml: expect at most about three concurrent Dependabot branches (root npm, documentation/ npm, and github-actions), instead of many separate version bumps each with its own branch.
• One-time cleanup on GitHub: close or merge the old open Dependabot PRs from before grouping; their branches disappear when the PR closes. Example: gh pr list --state open --label dependencies (this repo labels Dependabot PRs with dependencies).
• CI: pull requests whose head branch is dependabot/github_actions/… run a light YAML parse in .github/workflows/deploy.yml instead of the full Node/Docker pipeline; npm and documentation dependency PRs still run full CI. PR npm audit (.github/workflows/pr-npm-audit.yml) runs on every PR without requiring GitHub Advanced Security.
• Auto-merge: .github/workflows/dependabot-auto-merge.yml enables squash auto-merge for Dependabot PRs once checks pass, except semver-major grouped npm/docs bumps (merge those manually). Deploy rollback: if deploy/remote-deploy.sh fails after a pull, the deploy workflow runs deploy/rollback-to-revision.sh to reset the checkout to the previous SHA and rebuild containers so the stack can return to the last revision (the Actions job still fails so you see the incident).

6. What already lives in this repo

Item	Location
CI + production deploy	.github/workflows/deploy.yml
Dependabot auto-merge	.github/workflows/dependabot-auto-merge.yml
Docusaurus CI	.github/workflows/docs-ci.yml
PR path labels	.github/workflows/pr-labeler.yml + .github/labeler.yml
PR npm audit (root + documentation)	.github/workflows/pr-npm-audit.yml
Dependabot	.github/dependabot.yml
Issue forms	.github/ISSUE_TEMPLATE/
PR template	.github/pull_request_template.md
Roadmap manifest + populate script	scripts/github/roadmap/manifest.json + scripts/github/populate-omnitrack-roadmap.mjs
GitHub Project multi-views checklist	docs/github/SETUP.md §2c — velden Delivery phase + Target date, 12 views + optionele Roadmap-timeline, workflows
Roadmap project (script)	scripts/github/create-roadmap-project.mjs
Deploy secrets checklist	.github/DEPLOY-SECRETS.md
Contributing	CONTRIBUTING.md

7. New service “boilerplate”

Patterns for new Node services live alongside production code:

• TCP / ingest: services/telematics-gateway/
• Async consumer: services/telemetry-worker/

Copy the folder structure, package.json scripts in the root workspace (esbuild entries), and wire Docker in docker-compose*.yml following those services.

8. PR dependency checks (npm audit)

This repo uses .github/workflows/pr-npm-audit.yml on pull requests: npm ci + npm audit --audit-level=critical for the root workspace and for documentation/ (critical-only so known high/moderate transitive issues do not block every PR until upgraded). That works on any GitHub plan and does not require Dependency review (which needs Dependency graph + GitHub Advanced Security on the repository).

If you later enable Advanced Security and want actions/dependency-review-action, you can add a separate workflow; remove or relax the npm audit job if you prefer dependency-review as the only gate.