waynestate / rollcall
WELD's fleet scanner: every app answers present with its PHP image, Laravel and auth-package versions and its PROCTOR result, checked against CREED's policy.
Requires
- php: ^8.3
- composer/semver: ^3.4
- nyholm/psr7: ^1.8
- promphp/prometheus_client_php: ^2.14
- psr/clock: ^1.0
- psr/http-client: ^1.0
- psr/http-factory: ^1.0
- psr/http-message: ^2.0
- symfony/console: ^7.1
- symfony/http-client: ^7.4
Requires (Dev)
- inertiajs/inertia-laravel: ^3.0
- laravel/pint: ^1.32
- league/commonmark: ^2.10
- opis/json-schema: ^2.6
- orchestra/testbench: ^10.0 || ^11.0
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^11.5
- symfony/mailer: ^7.4
- waynestate/advisor: ^0.3
- waynestate/pinstripe: ^0.3
Suggests
- inertiajs/inertia-laravel: Only for the dashboard as one of an Inertia app's own Vue pages (ROLLCALL_DASHBOARD_INERTIA); the Blade and raw-PHP pages need nothing extra
- laravel/framework: For the Laravel adapter: the dashboard page and the scheduled scan
- symfony/mailer: Only to mail the opt-in owner digests (rollcall digest --send); printing them needs nothing extra
- waynestate/advisor: ADVISOR's MCP server loads the Rollcall module (src/Advisor/RollcallModule.php) with its three read-only tools
- waynestate/playbook: WSU's shared values (CAS, Entra, gateway); private, git.wayne.edu
- waynestate/wayne-ui: WayneUI styles the dashboard page (Laravel or raw PHP). Install it, or link its stylesheet with ROLLCALL_WAYNEUI_CSS
Provides
None
Conflicts
None
Replaces
None
README
Rollcall
Checks: composer ci (the same command runs on GitLab and GitHub).
Every app answers "present". The ones on PHP 7.4 answer from the back row.
Front page: site/index.html. It is static, with no build step (see site/README.md).
On Citadel, the raw-PHP deploy layer in deploy/ serves it: a Squire kit whose front controller puts site/ behind HELMET's security headers. For local development, serve site/ directly.
Rollcall is the fleet scanner for the Wayne State application stack. For each app it records the PHP image, the
lowest PHP its composer.json allows, the Laravel version, the auth package and its version, the PROCTOR result,
and, when the app commits one, the result, Booster version and finish time of Booster's hop record
(booster-hop.json). Then it looks up each version by date in CREED's policy.json. It keeps one snapshot per
scan, so you can see drift and an EOL burn-down over time. It prunes old snapshots after the retention window
(default 90 days; the newest one always stays).
Rollcall enforces nothing. It never opens an issue, leaves a comment or deploys anything, and scan and report
exit 0 whatever the fleet looks like (only rollcall owners, a check of the owners file, exits 1). The public
report has totals only: counts and progress, no app names, owners or rankings. The per-app list is internal. Like a good attendance sheet, it is for noticing who is missing, not for shaming them.
One page of the roll book, called name by name. Sample data: the apps are fictional, and a real scan's per-app list stays internal.
Where it sits in the stack
The parts of the Wayne State application stack, and their jobs. WELD is the Laravel starter app that has most of them installed:
| Part | Job |
|---|---|
| WayneUI (project 0) | The interface layer: tokens, components, four consumer paths |
| CREED | The standards and policy.json, the dates Rollcall reads |
| PROCTOR | Measures one app against the policy; Rollcall reads its JSON report and never re-runs a rule |
| SESAME | Protocol-neutral auth; Rollcall reports which auth package each app uses |
| HELMET | Baseline runtime and its own optional /metrics |
| Sourdough | Starters for every app shape |
| Squire | The Citadel deploy kit; the layer that serves this repo's front page is one |
| Parity | Citadel on your computer: its PHP image, its proxy and MySQL 5.6, so an app that works here works on Citadel (0.1.0; site: parity.apps.wayne.edu) |
| Preflight | CI templates |
| Pinstripe | The coding standard this repo includes for its Pint and PHPStan settings |
| Booster | The upgrade tool; Rollcall reads its hop record (booster-hop.json) to see who is catching up |
| Rollcall | The fleet census and EOL burn-down |
| Drawbridge | The one OpenID Connect front door for the Citadel |
| ADVISOR | The stack's read-only MCP server; Rollcall's module gives it three fleet tools |
| WELD | The Laravel starter app with most of the stack installed |
How it is built
A framework-free core (src/) plus thin entry points that hold no rules:
bin/rollcall: the CLI (scan,report,digest,owners,drift,advisories,prune). One PHP command, so it works the same on Windows, macOS and Linux.public/index.php: a raw-PHP front controller forGET /metricsandGET /report.json.rollcall_dashboard(): the dashboard page for a raw PHP app, one call in a file you serve (see "The dashboard in a raw PHP app").src/Laravel/: a Laravel adapter with a dashboard page (the Blade view, or an Inertia page in your own layout), a/metricsroute andphp artisan rollcall:scanandrollcall:prune.resources/js/RollcallDashboard.vue: the same dashboard as a Vue component, for an Inertia app's own page (see "The dashboard in an Inertia app (Vue)").
The Blade view and rollcall_dashboard() print the same renderer (src/Dashboard/DashboardPage.php) from the same
report, so they cannot drift, and CI fails the Vue component on any difference from that renderer's markup.
CREED's policy reader lives under src/Creed/ (namespace Waynestate\Rollcall\Creed) as a generated copy, made
by CREED's bin/export.php. CREED is on Packagist now, so the copy can become a require of waynestate/creed;
until Rollcall switches, the copy stays. To refresh it, run
php <creed>/bin/export.php --namespace='Waynestate\Rollcall\Creed' --to=src/Creed from a CREED checkout.
composer creed-copy:check proves the copy has not drifted (it reads the checkout from CREED_PATH); a hand edit
to src/Creed/ fails that check.
Weekly CREED copy refresh: a scheduled GitLab job (creed-copy-refresh, Mondays, an hour after CREED's policy
robot) re-exports the copy from CREED main, rebuilds the versions table and docs, runs composer creed-copy:check
and composer ci, and pushes to main only when both pass. A red run leaves main untouched. Details in
MAINTAINING.md, "Refreshing the CREED copy".
Data comes in through three interfaces. Each has a fixture adapter, so you can try everything without a live host:
| Source | Interface | Adapters |
|---|---|---|
Repositories (composer.json, composer.lock, booster-hop.json) |
RepositorySource |
a directory of fixtures; GitLab over PSR-18, tested against recorded responses |
| Runtime image per app | ImageSource |
a JSON export of the app list from any platform, or Citadel's own registrations export (which adds forced upgrade dates) |
| PROCTOR result | ProctorReportSource |
a directory of PROCTOR --format=json reports (the default); or, with ROLLCALL_PROCTOR_SOURCE=gitlab, each project's proctor job artifact in GitLab CI (see docs/architecture.md) |
Rollcall only reads from every source. It writes its own snapshot directory, and digest files only when
rollcall digest --out asks for them.
The decisions behind this shape (saved files over live calls, counts in public, one image source, the contract) are recorded in DECISIONS.md and ADR/.
Install
composer require waynestate/rollcall
Rollcall 1.2.0 is on Packagist. No extra repository needed. Requires PHP ^8.3. The CLI is vendor/bin/rollcall.
From 1.0 Rollcall follows SemVer against its contract (contract/): inside 1.x the report,
the stored snapshot and the image list may gain a field (a minor release) but never lose or retype one. Promoted
to 1.0 with perfect attendance.
Quick start
This runs on the fixtures in the repo, so you need no network and no token. Run composer install once
(or the Docker line under "Run the checks"), then the commands below.
Linux and macOS (bash):
export ROLLCALL_POLICY_FILE=tests/fixtures/policy.json
export ROLLCALL_REPOS_DIR=tests/fixtures/repos
export ROLLCALL_IMAGES_FILE=tests/fixtures/images.json
export ROLLCALL_PROCTOR_DIR=tests/fixtures/proctor
export ROLLCALL_STORE_DIR=var/snapshots
php bin/rollcall scan
php bin/rollcall report
Windows (PowerShell, no bash or WSL needed):
$env:ROLLCALL_POLICY_FILE = "tests/fixtures/policy.json"
$env:ROLLCALL_REPOS_DIR = "tests/fixtures/repos"
$env:ROLLCALL_IMAGES_FILE = "tests/fixtures/images.json"
$env:ROLLCALL_PROCTOR_DIR = "tests/fixtures/proctor"
$env:ROLLCALL_STORE_DIR = "var/snapshots"
php bin/rollcall scan
php bin/rollcall report
policy.json is CREED's file; the copy under tests/fixtures/ is a snapshot for tests. Use the released one in real
runs.
Commands
rollcall scan [--today=YYYY-MM-DD] [--prune[=DAYS]]
rollcall report [--format=text|json|prometheus] [--internal] [--today=YYYY-MM-DD]
rollcall digest [--owner=CONTACT] [--format=text|json] [--out=DIR] [--send] [--today=YYYY-MM-DD]
rollcall owners [--format=text|json]
rollcall drift --feed=<file> [--component=php] [--today=YYYY-MM-DD]
rollcall advisories --feed=<file> [--today=YYYY-MM-DD]
rollcall prune [--days=N] [--dry-run] [--today=YYYY-MM-DD]
scanscans once and stores<ROLLCALL_STORE_DIR>/<date>.json. A second scan on the same day replaces it. A gap in one source (a missing report, a bad image tag) becomes a note on that app, and the scan carries on. A refused GitLab token stops the scan loudly instead of producing a flattering partial answer.--prune[=DAYS]deletes snapshots older than that many days after saving (default:ROLLCALL_RETENTION_DAYS, 90; 0 keeps everything).reportprints the latest snapshot against the policy as of today.textis a terminal table,jsonis the machine-readable form,prometheusis the metrics text (refused unlessROLLCALL_METRICS_ENABLED=true).--internaladds the per-app list; keep that output inside the project.digestbuilds the opt-in owner digests (see "Owner digests" below): plain words about only one owner's apps, only when something changed since the previous scan. It prints them;--out=DIRwrites one text file each;--sendmails them, and only when sending is switched on too.ownersreads the same owners file asdigest, checks it against the latest scan, and names every scanned app whose owner is unknown: no entry lists it, or no entry that lists it was confirmed (its"confirmed"date) in the lastROLLCALL_OWNERS_CONFIRM_DAYSdays (365 by default). It exits 1 when there is one, and the weekly scan job runs it, so a new app without an owner, or an owner nobody has re-confirmed in a year, fails that job.driftcomparespolicy.jsonwith a saved endoflife.date v1 product page (for examplehttps://endoflife.date/api/v1/products/php/saved to a file). A difference is a flag for a person to look at; the policy stays the source of truth. Rollcall does not fetch that page itself.advisorieschecks each app's lockedlaravel/frameworkand auth-package versions against a saved Packagist security-advisories response (for examplehttps://packagist.org/api/security-advisories/?packages[]=laravel/frameworksaved to a file). One line per package and version, sorted by package then version: the status (affected,clearorno data), the count and the advisory ids, and how many apps hold that pair. A package with no advisory data printsno data, neversafe: an absent row proves nothing about the package, and a version nobody can parse saysno datatoo. Rollcall does not fetch that page itself; a person saves it and--feedpoints at the file. Output is package names and counts only: no app ids.prunedeletes snapshots older than--days(default:ROLLCALL_RETENTION_DAYS, 90; 0 keeps everything). The newest snapshot is never deleted, even if it is older than the cut-off, so the dashboard always has data.--dry-runlists what would go without deleting anything.
Exit codes: 0 ok, 1 owner unknown (rollcall owners only), 2 tool error (a bad option value, an unreadable
policy, a source that refused). Rollcall does not gate the fleet, so no command exits 1 over what the apps run:
rollcall owners exits 1 while an app's owner is unknown, and that is the register, not the fleet. A misspelled
command or an option the CLI does not know never reaches Rollcall: the console library prints the usage and exits
1.
Which command when
Several stack commands sound alike (weld:doctor, squire doctor, proctor check) and do different jobs. Find your question in the second column and run the command beside it. The doctors look at setup, the proctor grades against policy, and the gate decides deploys: same waiting room, different appointments.
| Command | What it checks | When to run it | Where it runs |
|---|---|---|---|
composer ci |
Will my pipeline pass? The repo's own CI contract, the same command the pipeline runs: validation, the tests, Pint, PHPStan, composer audit and whatever checks the repo adds. |
Before every push. | App repo, CI |
bin/weld.sh doctor or .\bin\weld.ps1 doctor (both run php artisan weld:doctor) |
Does my WELD app hold together? The app key, writable storage and bootstrap/cache, the database connection and pending migrations. One PASS, WARN or FAIL line each; exit 1 on a FAIL. Standards are PROCTOR's. |
After up, when the app will not start, and after every deploy off Citadel. |
App repo (in the app container), deploy host (in the app container) |
vendor/bin/squire doctor |
Is my Citadel release setup right? build.sh, the release scripts, the health check, script hygiene, line endings, secrets kept out of git and the local parity setup, against Squire's rules. Exit 1 on a failed rule. The lock file, audit and MySQL 5.6 checks are handed to PROCTOR. |
After squire init or squire update, and before the first deploy. |
App repo, CI |
vendor/bin/squire init --check |
Have the files Squire wrote drifted from its templates? Missing, outdated or edited copies. Writes nothing; exit 1 on drift. | After you upgrade Squire (then run squire update), and in CI. |
App repo, CI |
vendor/bin/squire doctor oracle, or php artisan oracle:check in WELD and Sourdough's Laravel apps |
Can my app reach Oracle? The ORACLE_* settings, the host, the port, the oci8 driver and the login, in plain language, printing setting names and never values. Silent when the app has no Oracle settings. |
After you fill in the ORACLE_* settings, or when a connection fails. Squire's release.sh runs the same check on every release, as a report. |
App repo, deploy host |
vendor/bin/proctor check (composer proctor in WELD and Sourdough's apps) |
Does my app meet CREED's policy? The PHP floor, Laravel, Node and MySQL end of life, the committed lock, composer audit, open-ended constraints, portability, MySQL 5.6 safety, overrides and the rest of its checks. Exit 1 on a FAIL. |
Before you merge; the pipeline runs it too. | App repo, CI |
vendor/bin/proctor gate |
May this commit deploy? The deploy-time subset of proctor check, ratcheted against the last release's verdict, so a deploy that makes nothing worse goes. Exit 1 is a no-go. |
At deploy time. Squire's release.sh calls it for you. |
Deploy host |
sourdough manifest --check |
Which managed files did I change since Sourdough baked my app? Managed files that changed or are missing against .sourdough/manifest.json; seeded files are yours and never reported. Exit 1 on a change. |
Before sourdough feed. |
App repo, CI |
sourdough feed --dry-run |
Is my app behind its Sourdough template? The plan a feed would apply, with nothing written. Exit 1 when feeding would change files. | After you install a new Sourdough, and in CI to catch an app falling behind. | App repo, CI |
booster plan |
What does my upgrade take? The ordered PHP, Laravel and front-end hops, the dependencies that block them, and advisory PHPCompatibility and PHPStan scans. Changes nothing. | Before an upgrade, and when PROCTOR says your PHP or Laravel is past support. | App repo |
booster replay check |
Does my app still answer the same after a change? Replays the requests in booster-replay.json and compares the answers with the ones booster replay record saved. Exit 1 on a changed answer. |
After an upgrade hop or a hand fix, once you have a recording. | App repo (in Docker) |
booster init --check |
Are Booster's coding-tab playbooks current? The playbooks in .agents/skills. Changes nothing; exit 1 when one is missing or out of date. |
After you upgrade Booster, and in CI. | App repo, CI |
php bin/regen-check.php --generated <dir> |
Is WELD still Sourdough's Inertia shape? WELD, file by file, against a fresh sourdough new --inertia; fails only on drift that .sourdough/regen-baseline.json does not already accept. |
When Sourdough's Inertia shape or WELD changes. | WELD repo, CI |
rollcall report |
Where does the whole fleet stand? The latest scan's totals against CREED's policy: PHP, Laravel, the auth package, PROCTOR results and the end-of-life burn-down. Always exit 0; it never gates. | After rollcall scan, on the scan's schedule. |
CI (a scheduled scan job) |
The canonical copy of this table is in WELD's docs: Which command when.
What the report says
-
Apps present and scan notes: the apps the scan read, then the notes it printed and carried on past (
totals.scan_errorsin JSON). Today a note means a source is not configured (no image export, no PROCTOR reports). A note is not a failed scan: a source that refuses stops the scan instead. -
PHP image, declared PHP floor, Laravel: apps per version, the state from the policy (
active,security_only,eol,unknown), the date security support ends and the days left (negative once past). -
Auth package and PROCTOR: apps per auth package, and per PROCTOR result (
pass,fail,none). -
Drift, counted per kind:
image_eol,image_unknown,image_below_floor,floor_allows_eol,floor_unbounded,eol_past_grace(past the policy's grace days),laravel_eol,proctor_missing,proctor_failing,override_expired. -
Progress: apps that moved since the previous scan and apps that went from an EOL image to a supported one. In the internal view each upgraded app carries the day it landed.
-
EOL burn-down: for each scan day, how many apps ran an EOL image on that day. It reads the image, not the declared floor, so it stays
unknownuntil an image export is configured. Each day also carries the same roll three ways, counts only: per support state (states), per PHP minor of the image (php_image, such as{"8.1": 3, "8.4": 9}) and per Laravel major (laravel). Every stored snapshot gets the breakdown, including the ones written before it existed, so the history reaches back as far asrollcall prunekeeps snapshots. -
Forced image upgrades: with Citadel's export as the image source, how many apps have a forced base-image upgrade pending, how many are due today or earlier, and the next date (
forced_upgrades). The same counts reach/metrics(rollcall_forced_upgrades_pending_apps,rollcall_forced_upgrades_overdue_appsandrollcall_forced_upgrades_next_due_timestamp_seconds) and ADVISOR'srollcall_fleet_summary. The internal per-app list carries each app'supgrade_due. Zero with any other image source. The dashboard shows the three counts under its totals, and its internal table has an "Upgrade due" column, badged "date has come" once a date arrives. See docs/guides/citadel.md.
State is never decided in code: it is derived from the dates in policy.json by CREED's reader. A version the
policy does not list is unknown.
Configuration
Every setting is an environment variable. .env.example holds placeholders; never commit a real token.
| Variable | Meaning | Default |
|---|---|---|
ROLLCALL_POLICY_FILE |
Path to CREED's policy.json |
none (required for report, drift) |
ROLLCALL_STORE_DIR |
Snapshot directory, the only place Rollcall writes | var/snapshots |
ROLLCALL_SOURCE |
directory (fixtures) or gitlab |
directory |
ROLLCALL_REPOS_DIR |
Fixture repositories as <group>/<project>/composer.{json,lock}, plus booster-hop.json where an app has one |
none |
ROLLCALL_GITLAB_URL |
https:// base URL of the GitLab instance |
none |
ROLLCALL_GITLAB_TOKEN |
A GitLab group or project access token (a bot), or a service account's token, with the read_api scope only, the Reporter role and an expiry. The stack's is the group token rollcall-scanner, rotated by the stack maintainer (docs/security.md). Never in git, never logged, never printed | none |
ROLLCALL_GITLAB_GROUPS |
Comma-separated group ids or paths; subgroups are included. Ignored when ROLLCALL_GITLAB_PROJECTS is set | none |
ROLLCALL_GITLAB_PROJECTS |
Comma-separated full group/project paths; when set, only those projects are scanned and no group is listed |
none |
ROLLCALL_IMAGES_FILE |
Export of the app list: {"apps": [{"project": "group/project", "image": "php:8.4-apache"}]} |
none |
ROLLCALL_CITADEL_EXPORT |
Citadel's saved registrations export, used instead of ROLLCALL_IMAGES_FILE (not both): base images plus forced upgrade dates. See docs/guides/citadel.md |
none |
ROLLCALL_PROCTOR_SOURCE |
Where PROCTOR reports come from: directory (ROLLCALL_PROCTOR_DIR) or gitlab (each project's proctor job artifact from its newest finished default-branch pipeline, with the same read_api token and GitLab settings) |
directory |
ROLLCALL_PROCTOR_DIR |
PROCTOR JSON reports, one per app: group/project is read from group__project.json. Not read when ROLLCALL_PROCTOR_SOURCE is gitlab |
none |
ROLLCALL_PROCTOR_JOB |
ROLLCALL_PROCTOR_SOURCE=gitlab: the CI job whose artifact holds the report; set it when Preflight's proctor component is included with another job_name |
proctor |
ROLLCALL_PROCTOR_ARTIFACT |
ROLLCALL_PROCTOR_SOURCE=gitlab: the PROCTOR --format=json report's path inside that job's artifact |
proctor.json |
ROLLCALL_AUTH_PACKAGES |
Comma-separated Composer packages that count as an auth package. An entry without a slash matches that package under any vendor (wayne-cas matches anyvendor/wayne-cas); an entry with a slash matches exactly. First match in list order wins |
waynestate/sesame, waynestate/wayne-cas, apereo/phpcas, jasig/phpcas, subfission/cas, wayne-cas, simplecas |
ROLLCALL_RETENTION_DAYS |
How many days of snapshots to keep; the newest is never deleted | 90 (0 keeps everything) |
ROLLCALL_OWNERS_FILE |
Owners file for the digests: {"owners": [{"contact": "team@example.test", "digest": true, "projects": ["group/project"]}]}. Rollcall's own, for the stack's projects, is owners.json in the repo (roles only); keep another fleet's outside a public repo |
none (no digests) |
ROLLCALL_OWNERS_CONFIRM_DAYS |
How long an owners-file entry's "confirmed" date counts; past it, rollcall owners calls that owner unknown and exits 1 |
365 (0 turns the check off) |
ROLLCALL_DIGEST_MAIL_ENABLED |
Allow rollcall digest --send to mail |
false |
ROLLCALL_DIGEST_MAIL_DSN |
Symfony Mailer DSN for sending, such as smtp://mail.example.test:25. A secret: never in git, never printed |
none |
ROLLCALL_DIGEST_MAIL_FROM |
The from address of the digests | none |
ROLLCALL_METRICS_ENABLED |
Turn metrics on (CLI report --format=prometheus and /metrics) |
false |
ROLLCALL_METRICS_TOKEN |
Bearer token a scraper must present | none |
ROLLCALL_METRICS_ALLOW |
Comma-separated scraper IP addresses (exact match) | none |
ROLLCALL_PUBLIC_REPORT_ENABLED |
Serve GET /report.json (public counts only) |
false |
ROLLCALL_DASHBOARD_ENABLED |
Laravel and raw PHP: serve the dashboard page | false |
ROLLCALL_DASHBOARD_PATH |
Laravel: dashboard URL path | rollcall |
ROLLCALL_INTERNAL_ENABLED |
Laravel and raw PHP: serve the per-app page (Laravel at <path>/apps, behind your sign-in middleware; raw PHP only where you call rollcall_dashboard(['internal' => true]) behind your sign-in) |
false |
ROLLCALL_DASHBOARD_INERTIA |
Laravel + Inertia: answer the dashboard routes with the app's Vue page (Rollcall/Dashboard, published with vendor:publish --tag=rollcall-inertia) instead of the Blade view; same switches, same report. Needs inertiajs/inertia-laravel |
false |
ROLLCALL_WAYNEUI_CSS |
Laravel and raw PHP: https:// or absolute URL of WayneUI's stylesheet for the dashboard |
none |
To scan GitLab you need the token and either a group or the project allowlist. The narrow way is
ROLLCALL_GITLAB_PROJECTS: name the exact group/project paths and Rollcall reads only those, never listing a
group. Otherwise set ROLLCALL_GITLAB_GROUPS. The token is a GitLab bot or personal access token with read_api
only and an expiry, whose user can read only the projects to scan; until it exists Rollcall runs on its fixtures.
Set ROLLCALL_SOURCE=gitlab and the GitLab variables. The rollcall-scan job in .gitlab-ci.yml does this on a
schedule or by hand (see below). Rollcall sends only GET and HEAD, fetches the two Composer files and Booster's
booster-hop.json without cloning, skips a Composer file whose blob id has not changed, follows Link pagination
only to the configured host, and waits out 429 Retry-After.
PROCTOR results can come from GitLab CI too: with ROLLCALL_PROCTOR_SOURCE=gitlab the scan reads each project's
proctor.json from its proctor job's artifact, with the same token. That needs apps whose CI keeps proctor.json
as an artifact: Preflight 0.5.0 or later, or a proctor job of your own that does (see
docs/architecture.md). Elsewhere every app reads none.
Run the collector in Docker
No PHP on the machine? The repo ships a Dockerfile that builds a small image of the collector. It runs as a
non-root user, writes only to its snapshot folder, and takes every setting from the environment at run time.
Never put a token in the image: the build stays clean, and the token travels with -e (or --env-file) each
time you run. Two lines, and every app answers present.
Build it, from the repo root (again whenever the code changes):
docker build -t rollcall-collector .
That reads the Dockerfile next to it and tags the result rollcall-collector. Then run a scan. Each -e
flag is a setting from the table above; for the narrow scan add
-e ROLLCALL_GITLAB_PROJECTS=group/project,other-group/other-project and only those projects are read, no group
is listed. The two -v flags mount your policy file and snapshot folder so the answer survives the container:
docker run --rm -e ROLLCALL_SOURCE=gitlab -e ROLLCALL_GITLAB_URL=https://gitlab.example.test -e ROLLCALL_GITLAB_TOKEN="$ROLLCALL_GITLAB_TOKEN" -e ROLLCALL_GITLAB_GROUPS=your-group -e ROLLCALL_POLICY_FILE=/app/policy.json -v "$PWD/policy.json:/app/policy.json" -v "$PWD/var:/app/var" rollcall-collector scan
Next: after a good scan, var/snapshots/<today>.json holds the day's attendance, and the same run with
report instead of scan prints it. On Windows PowerShell, set $env:ROLLCALL_GITLAB_TOKEN first and use
${PWD} for the mount paths.
Scheduled scan on GitLab CI
Rollcall's own repository (on git.wayne.edu, its canonical home) carries a rollcall-scan job in .gitlab-ci.yml. It
runs scan over the 13 stack projects read-only and keeps the snapshot in var/snapshots/ as a 30 day artifact.
It runs when a GitLab schedule says so, or when a person starts it by hand from the web; without a token it skips
green. It needs three things in GitLab, and on git.wayne.edu all three exist:
- A token with the
read_apiscope only, the Reporter role and an expiry. The stack's is the group access tokenrollcall-scanneron theenterprise-appsgroup, which expires 2027-11-06 (Rollcall prints a note 14 days before). - A CI/CD variable
ROLLCALL_GITLAB_TOKENon the ROLLCALL project: masked and hidden, protected (the schedule runs on the protected default branch), and not a file. - A schedule on
main: CI/CD > Schedules, weekly (Monday), with the variableROLLCALL_JOBset toscan.
The token is rotated by a role, the stack maintainer, not a named person. The runbook (where the token lives, when it expires, the five steps, and what to look for in the job log) is "The scanner token and how to rotate it" in docs/security.md.
About reach: a group token reads every project in its group. The project owner chose group reach for the stack's
token; the allowlist ROLLCALL_GITLAB_PROJECTS keeps what Rollcall asks for to the 13 projects (it never lists the
group and never asks for another project). If your fleet needs a tighter fence, give a service account Reporter on
just the projects to scan and use its token instead, because only membership limits what a token can read.
Exactly which scope, and why each other scope stays off: read_api covers every call Rollcall makes (listed
one by one, with the role and the expiry rules, under "The GitLab token, exactly" in
docs/security.md). Not api, not read_repository (Rollcall never clones), not read_user,
not self_rotate (the stack maintainer rotates the token, never Rollcall).
Owner digests (opt-in)
An owner who asks can get a short digest of only their own apps: what changed since the previous scan (an image upgrade, a new drift flag, one cleared, a PROCTOR result that moved), then where each app stands. Nothing changed, no digest. Nobody gets one by default, and no owner is ever guessed from commit authors.
-
Point
ROLLCALL_OWNERS_FILEat an owners file that maps each scanned project to its contacts (a mail address, a team alias or a role). An owner opts in with"digest": true; leaving the key out means no."confirmed"is the day the contact last said it still answers for those apps;rollcall ownerscalls the owner unknown once that day is older thanROLLCALL_OWNERS_CONFIRM_DAYS. The shape iscontract/owners.schema.json.{ "$schema": "contract/owners.schema.json", "owners": [ {"contact": "team@example.test", "digest": true, "confirmed": "2026-11-01", "projects": ["group/project", "group/other-project"]} ] }Rollcall keeps its own in the repo: owners.json lists the 13 stack projects the scheduled scan reads, all answered for by the stack maintainer. The repo is public, so it names roles and teams, never a person. For another fleet, keep that fleet's file next to its snapshots, outside a public repo.
-
After a scan,
rollcall digestprints each digest with news (--format=jsonfor a script,--owner=CONTACTfor one owner).--out=DIRwrites them as<date>-<contact>.txtinstead, for a mail tool you already have. A scanned app that no entry lists is never dropped: every run names it on stderr as "no owner on file", and the JSON lists it underno_owner_on_file. -
To have Rollcall mail them itself, install
symfony/mailer, setROLLCALL_DIGEST_MAIL_ENABLED=true,ROLLCALL_DIGEST_MAIL_DSNandROLLCALL_DIGEST_MAIL_FROM, and runrollcall digest --send. Without all four, it sends nothing. Every contact must be a mail address, or nothing goes out at all.
A digest names apps, so it is internal like the per-app list. It uses the report's own states and drift flags, so a
digest and the report never disagree. Schedule it after rollcall scan (weekly suits the burn-down).
WSU values (Playbook)
ROLLCALL_GITLAB_URL is a Wayne State value, so it may come from Playbook (waynestate/playbook) when the
environment has none. The environment always wins; Playbook only fills what the environment leaves out. The GitLab
token never comes through Playbook and stays an environment variable.
| Setting | Value |
|---|---|
ROLLCALL_GITLAB_URL |
The https:// base URL of the GitLab instance |
Playbook is private and lives on git.wayne.edu. Getting it into your app:
Composer: add the repository to your composer.json, then require the package. Composer authenticates to
git.wayne.edu with the token in auth.json.
{
"repositories": [
{"type": "vcs", "url": "https://git.wayne.edu/enterprise-apps/playbook.git"}
]
}
composer require waynestate/playbook
curl (Linux, macOS):
curl --fail -H "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://git.wayne.edu/api/v4/projects/enterprise-apps%2Fplaybook/repository/files/playbook.env/raw?ref=main" -o .env.playbook
PowerShell (Windows):
Invoke-WebRequest -Headers @{ 'PRIVATE-TOKEN' = $env:GITLAB_TOKEN } -Uri "https://git.wayne.edu/api/v4/projects/enterprise-apps%2Fplaybook/repository/files/playbook.env/raw?ref=main" -OutFile .env.playbook
Clone:
git clone https://git.wayne.edu/enterprise-apps/playbook.git
The token is your own: read_api for curl, read_repository for clone and Composer.
Playbook is private on git.wayne.edu. If you get a 404, ask the Enterprise Applications team for read access.
Metrics
Metrics are off by default (the stack's metrics rule). With ROLLCALL_METRICS_ENABLED=true, /metrics serves
Prometheus text built from the latest snapshot (a request never triggers a scan). It needs ROLLCALL_METRICS_TOKEN as a bearer token or an address in
ROLLCALL_METRICS_ALLOW; with neither set, nobody gets in. Labels are version numbers, state names, drift kinds and
public package names: no app names or personal data. The dashboard JSON is in grafana/rollcall-burn-down.json; import
it into Grafana once a Prometheus server scrapes the endpoint. Run rollcall scan
on a schedule so the series moves.
Forced image upgrades from a Citadel export come through as three gauges, counts only, in the same style as the
rest: rollcall_forced_upgrades_pending_apps (apps with one pending, overdue ones included),
rollcall_forced_upgrades_overdue_apps (due today or earlier) and
rollcall_forced_upgrades_next_due_timestamp_seconds (midnight of the next date still ahead, only while there is
one). With any other image source the two counts are 0 and the date is absent. The dashboard shows pending and
overdue as two stat panels.
Laravel
The package registers itself (extra.laravel.providers). Publish the config with
php artisan vendor:publish --tag=rollcall-config, set the variables above, and schedule rollcall:scan. The
dashboard shows counts and progress; the per-app page is a second route that stays off until you enable it, and it
runs behind rollcall.dashboard.internal_middleware (default web and auth.sesame), so an app with no such
middleware fails closed. The page uses WayneUI's class names and takes its stylesheet from ROLLCALL_WAYNEUI_CSS.
In an Inertia app it can be one of your own Vue pages instead: see "The dashboard in an Inertia app (Vue)".
The /metrics route is registered on its own path; if your app already serves /metrics (HELMET does), run Rollcall's
on a separate app or leave metrics off.
The dashboard in a raw PHP app
The same page, no framework. rollcall_dashboard() prints the renderer the Laravel page prints, from the same
report, so the two answer the roll in the same words. Drop one file into the folder your web server serves:
<?php // public/rollcall.php require __DIR__ . '/../vendor/autoload.php'; $helmet = \Waynestate\Helmet\helmet_boot(['preset' => 'citadel']); rollcall_dashboard(['nonce' => $helmet['nonce']]);
It answers 404 until ROLLCALL_DASHBOARD_ENABLED=true, sends X-Robots-Tag: noindex with every answer, and never
runs a scan: it reads the latest snapshot, so set ROLLCALL_POLICY_FILE and ROLLCALL_STORE_DIR as for the CLI
and schedule vendor/bin/rollcall scan. The page has no script. Its one small style element takes HELMET's nonce;
link WayneUI's stylesheet with ROLLCALL_WAYNEUI_CSS and the page keeps its look under HELMET's CSP even without
one. No HELMET? Call rollcall_dashboard() with no options.
The per-app page is a second file, behind your sign-in: call rollcall_dashboard(['internal' => true]) after
SESAME's sesame_login() has returned a user. It also needs ROLLCALL_INTERNAL_ENABLED=true; with either one
missing it answers 404, so it fails closed. For a front controller of your own,
Waynestate\Rollcall\Dashboard\RawDashboard::response() returns the same answer as data (status, headers, body).
The dashboard in an Inertia app (Vue)
In a Laravel + Inertia + Vue app (WELD's shape) the dashboard can be one of the app's own pages, inside its own
layout. Same routes, same switches, same report: with ROLLCALL_DASHBOARD_INERTIA=true the controller hands what
DashboardPage::report() built to an Inertia page as props (report, internal, scanCommand) instead of printing
the Blade view. From a WELD app:
php artisan vendor:publish --tag=rollcall-inertia # writes resources/js/pages/Rollcall/Dashboard.vue # .env: ROLLCALL_DASHBOARD_ENABLED=true and ROLLCALL_DASHBOARD_INERTIA=true npm run build
The published page is short and it is yours. In essence it puts the component in WELD's AppLayout with a title
and a noindex tag (the full file adds breadcrumbs and a few lines of scoped CSS, in WayneUI's spacing tokens, that space the sections and set the three totals side by side):
<script setup lang="ts"> import AppLayout from '@/layouts/AppLayout.vue'; import { Head } from '@inertiajs/vue3'; import RollcallDashboard from '../../../../vendor/waynestate/rollcall/resources/js/RollcallDashboard.vue'; defineProps<{ report: Record<string, unknown> | null; internal: boolean; scanCommand: string }>(); </script> <template> <Head title="Rollcall"><meta name="robots" content="noindex" /></Head> <AppLayout> <RollcallDashboard :report="report" :internal="internal" :scan-command="scanCommand" /> </AppLayout> </template>
Why this shape: the page is published because the layout is the app's, and the component is imported straight
from vendor/ because the markup is Rollcall's. composer update moves the component together with the PHP
renderer it must match, and there is no npm package to install or keep in step (Rollcall publishes none). Vite and
vue-tsc follow the relative import like any file in the project, and the component imports nothing but vue,
which the app already has. An app that does not use the Vue page loads none of it; inertiajs/inertia-laravel is
needed only when the switch is on.
The component renders what the Blade page shows inside <main>: the same WayneUI classes, the role="status" line,
the captions and headers, and the per-app table only on the internal page (<path>/apps, still behind
rollcall.dashboard.internal_middleware and ROLLCALL_INTERNAL_ENABLED). It has no style block, no style attribute
and no script of its own, so it works under HELMET's CSP, and it takes its look from the app's WayneUI stylesheet.
Every Inertia answer carries X-Robots-Tag: noindex. CI holds the rooms together: dashboard-vue server-renders
the component with the props the route sends and fails on any difference from the Blade page (elements, attributes
and text; only whitespace, attribute order and Vue's hydration comments are normalized), and dashboard-a11y
checks the three Vue pages with the other six.
Use Rollcall from your coding agent (ADVISOR)
Rollcall ships a module for ADVISOR, the stack's MCP server: three read-only tools, and a small creed goes with them: every app answers present, the agent may ask, and nobody gets ranked.
Install both packages where the MCP server runs:
composer require waynestate/advisor waynestate/rollcall
Then name the module in your own manifest file. Rollcall ships none on purpose, so nothing loads by accident:
{
"modules": [
"Waynestate\\Rollcall\\Advisor\\RollcallModule"
]
}
and point ADVISOR_MODULES_FILE at that file. The tools read the snapshot store behind ROLLCALL_STORE_DIR; with an
empty store each one says so in plain words and names rollcall scan.
| Tool | What it answers |
|---|---|
rollcall_fleet_summary |
Counts from the latest snapshot: apps by PHP image, declared floor, Laravel line, auth package, PROCTOR result, MySQL 5.6 CI job state and Booster hop result, drift per kind, progress since the previous scan, forced image upgrades (forced_upgrades: pending, overdue, next due), and the snapshot date |
rollcall_burn_down |
The dated EOL series, one point per scan day, each with its counts per support state, PHP minor and Laravel major; optional days (an integer, 1 to 365) keeps only the most recent days |
rollcall_supported_versions |
Every version in CREED's policy, grouped by what it says today: active, security only, or end of life |
The tools take no path, command or URL, make no network call, and answer public counts only: the same fields
/report.json serves. The per-app list stays internal and never leaves through a tool. Each answer names its source
and its dates.
Proof
Rollcall's first scheduled scan of the stack on GitLab CI and a rerun over 58 Wayne State applications (2026-11-06): what ran, what held, what it caught in Rollcall and what it does not prove yet, on the Proof docs page.
Docs
The full documentation lives at /docs/ on the project site: install, guides, reference and checks, built
from docs/ by Squire's docs builder. Two tables are generated so they cannot drift: the command reference comes
from php bin/rollcall list --format=json, and the environment table is scanned out of src/, bin/ and
config/.
composer docsrebuildssite/docs/fromdocs/; run it after editing a page.composer docs:checkfails when the built site is stale or a generated table has drifted;composer ciruns it.
The pages are committed because the deploy server serves site/ without building. Every page links back to its
Markdown, and the footer stamps the version the docs describe. Roll call: the docs answer present too.
The docs pages wear the front page's look: the same masthead and menu, ruled paper, Caslon titles, the front
page's red section folios (each section of a page opens with its own "ยง 1") and the green back cover. To change it, edit docs/_header.html (the masthead, links written as if from site/) and
docs/theme/rollcall.css (the front page's tokens mapped onto the kit's --dk-*, plus a derived dark mode), then
run composer docs. Never edit site/assets/docs.css or docs.js: they are Squire's kit and a sync overwrites them.
Run the checks
Maintainers: how to build, test and release this project, and where its data comes from, is in MAINTAINING.md. Why it is built this way is in DECISIONS.md and the ADRs under ADR/.
composer ci runs every check: manifest, tests (the contract suite among them), Pint, the agent-ready files, a
check that the docs site is current, a check that the front page's versions table and quick-start printout still
match CREED's policy, PHPStan and composer audit.
The contract itself is JSON Schema in contract/: the report, the stored snapshot and the
image list export. tests/ContractTest.php runs the real commands on the fixtures and validates their output
against it, so a field cannot appear or vanish without the contract changing in the same commit. PHP is not needed on the host:
docker run --rm -v "${PWD}:/app" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 sh -c "composer install --no-interaction && composer ci"
(On Windows PowerShell ${PWD} works as written; in Git Bash use $(pwd -W) and set MSYS_NO_PATHCONV=1.)
The GitLab pipeline (.gitlab-ci.yml) and the GitHub workflow (.github/workflows/ci.yml) both wrap composer ci,
on PHP 8.3, 8.4 and 8.5. git.wayne.edu now has an instance runner, and the stack's CI runs on it. Every product in
the stack still strongly recommends a git.wayne.edu instance runner, so that capacity stays there.
The front page has its own accessibility gate (axe-core in Playwright, run in Docker): scripts/a11y.sh on Linux
and macOS, scripts/a11y.ps1 on Windows; MAINTAINING.md says when to run it.
Security notes
- Read-only toward GitLab and everything else: one gate in the GitLab adapter allows only
GETandHEAD, and a test fails if a write verb appears insrc/. - The GitLab token is a group or project access token (a GitLab bot), or a service account's token, with the
read_apiscope only, the Reporter role and an expiry; the stack's is the group access tokenrollcall-scanner, which expires 2027-11-06. It goes in the environment asROLLCALL_GITLAB_TOKEN, never in git, is sent only to the configuredhttpshost, and is hidden from debug output and error messages.ROLLCALL_GITLAB_PROJECTSlimits what Rollcall asks for, not what the token can read; only the token's membership does that. When the source is GitLab,scanreads the token's own record (GET /api/v4/personal_access_tokens/self) and prints a note 14 days before it expires, or when it has already expired. The note names the date; the stack maintainer (a role, not a named person) rotates the token before its expiry, never Rollcall, following the runbook in docs/security.md. The check is advisory: a refused, unreachable or unparseable answer prints nothing and never fails the scan, and the token value never appears in output. - Composer files are parsed as data. No
composer install, script or plugin from a scanned repository ever runs. - PROCTOR reports, image tags and app ids are outside input: shapes are validated, text is bounded, and terminal output strips control characters.
- Every GitLab call, the scope that covers it, and the scopes the token must not have are tabled in docs/security.md; a test fails if the adapter calls a path that table does not list.
Watch the back row empty (the burn-down, sample data)
The same line Grafana draws from /metrics. Made-up apps, real arithmetic.
Where the code lives
The canonical repository is enterprise-apps/rollcall on git.wayne.edu. Clone it over SSH as git@git.wayne.edu:enterprise-apps/rollcall.git or over HTTPS as https://git.wayne.edu/enterprise-apps/rollcall.git; open issues and merge requests there, and tags are made there, by the maintainer, with an approver. GitHub (waynestate/rollcall) is a read-only push mirror of git.wayne.edu: nobody pushes to it, and Packagist reads from it. Roll call: git.wayne.edu? Present. GitHub? A copy of the sheet.
Contributing
Issues and merge requests go to git.wayne.edu; see Where the code lives above.
License: MIT, Copyright Wayne State University.
The whole classWayneUI and the stack. Everyone is here today; the ones in the back row know who they are.
scripts/readme-art. Present.
