dashboard

LizardByte developer dashboard.

Overview

A dashboard for viewing LizardByte repository data inside a Jekyll static site.

Organizations and repository identity

The collector discovers public repositories from the shared organizations.json registry. Add organizations there; dashboard has no separate organization list. Charts, PR links, and PR metrics use each repository's current owner/name, and the dashboard can show all organizations together or filter to one organization. Chart labels show the repository name, adding the owner on a second line for duplicate names; hover details include the full repository identity. Archived repositories remain in the raw inventory but are excluded from active metrics.

The published github/repos.json remains the raw repository catalog. Each record adds dashboard_key, dashboard_aliases, and dashboard_paths for its banner, small banner, and coverage badge. Consumers should use the supplied paths rather than constructing them from the repository's current name or owner.

github/catalog.json is generated state, keyed by GitHub's persistent repository ID. On the first run, it restores existing storage keys from the published github/repos.json. Those keys stay unchanged across transfers and renames, so existing badge/banner URLs, star and coverage history, commit activity, and PR caches continue to work. New repositories use owner/name storage keys, keeping repositories with the same name in different orgs separate. PR metrics pages also retain their original report routes. Coverage points from destination Codecov projects are merged into the existing series by timestamp.

The Update workflow restores github, codecov, readthedocs, shields, and azure data from gh-pages before collecting. Keep the published identity catalog and these caches when moving or restoring a deployment; deleting them discards the mapping to existing public URLs and history. Other services and Azure collection settings are independent of the org registry.

GitHub and Codecov collections run separately for each organization. If an organization cannot be refreshed, its available cache remains published and the dashboard shows a collection notice. Repositories without Codecov uploads are skipped until Codecov reports them active; an organization with no coverage uploads is not treated as a collection failure. Registry outages use the last successful organization list; a first run without a valid registry fails. metadata.json reports registry freshness and per-organization collection status. The existing GITHUB_TOKEN and CODECOV_TOKEN collector credentials need access to the desired organizations; the workflow supplies these from GH_BOT_TOKEN (or GITHUB_TOKEN) and CODECOV_API_TOKEN, respectively. Read the Docs projects are matched by full GitHub identity, including saved pre-transfer URLs.

Azure code signing metrics

The optional Azure Code Signing section displays Artifact Signing (formerly Trusted Signing) completed signing requests: UTC month-to-date and last-30-day totals, plus daily history. Counts cover the entire signing account. Azure's standard SignCompleted metric does not include repository, file, certificate profile, failure-rate, or signing-duration dimensions; these counts are not billing records. Azure reporting can be delayed and the current day is incomplete. Missing metric samples are not presented as confirmed zero usage.

Azure collection is currently paused by default while the signing account's Azure Monitor chart has no reported counts. The collector and dashboard section remain available. Workflows make no Azure requests unless the repository variable DASHBOARD_AZURE_SIGNING_ENABLED is set to true; pull-request builds always use cached data. With no published Azure cache, the section and its navigation link stay hidden.

Collection costs

The collector refreshes the current UTC day and recent unsettled days, with a three-hour cache for successful collections and no automatic retries. Any failed collection can be retried on the next production or manual workflow run immediately. Each update also backfills at most seven missing historical days, starting with the oldest dates in Azure's available 90-day window. Once a complete day has had two full days of reporting grace and is fetched successfully, it is finalized and never fetched again. Historical gaps are queried separately, so a backfill request never spans finalized days. Finalized history is retained indefinitely in the existing gh-pages branch, without Azure storage. Successfully queried days with no numeric samples remain unknown, rather than becoming zero; partial month and 30-day totals are labeled while history fills in. Queries use SignCompleted's supported one-minute interval in the resource's default metric namespace, then sum the samples into UTC days locally. Each bounded time window still uses one query.

The scheduled job runs eight times per day: one metric query per update when caught up, or at most two while backfilling (at most 496 queries in a 31-day month for one account). Site visitors read the generated JSON and never query Azure. Pull-request builds use only the Azure data restored from the published gh-pages cache and make no Azure API calls, even when signing secrets are available. Their preview displays cached counts when available; without published Azure data, the section stays hidden. No diagnostic settings, Azure Storage, Log Analytics, Event Hubs, custom metrics, or Azure alerts are created or required.

Microsoft currently lists unlimited standard platform metric ingestion as free and the first 1,000,000 metric query API calls per month as included. This allowance is shared with other consumers in the Azure subscription; exceeding it can incur charges. With no other monitoring consumers, this collector's scheduled usage fits comfortably within the included allowance. Your existing signing plan and any signature overage charges still apply independently of this dashboard. See Azure Monitor pricing and Artifact Signing's supported metric.

Setup

1. Set the repository or organization secret AZURE_SIGNING_RESOURCE_ID to the full existing account ID: /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CodeSigning/codeSigningAccounts/<account>. In the Azure portal, open the signing account, select Overview → JSON View, and copy its ID. AZURE_SIGNING_ACCOUNT supplies only the final account name; it is not the full resource ID. AZURE_SIGNING_CERT_PROFILE is not needed for these account-wide metrics. The resource ID does not grant access by itself, but using a secret keeps the subscription and resource identifiers private and enables GitHub Actions log masking.
2. Make the secrets AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET available to this repository. These are the same credential names used by the organization's signing workflows. The service principal needs read access to metrics on this account; Monitoring Reader scoped to the signing account supplies that permission. The signing role alone may not allow metric reads. In the signing account's Access control (IAM), choose Add role assignment → Monitoring Reader. Select User, group, or service principal, then the app matching AZURE_CLIENT_ID.
3. In Subscriptions → your subscription → Resource providers, verify that Microsoft.Insights is Registered. If it is NotRegistered, select it and choose Register, then wait for registration to complete. This is an Azure Monitor prerequisite for exploring metrics; see Microsoft's empty-chart troubleshooting guide.
4. Once Azure Monitor shows SignCompleted counts for the account, set the repository Actions variable DASHBOARD_AZURE_SIGNING_ENABLED to true to enable collection. Leave it unset or set it to false to keep collection paused. Run the Update workflow or wait for its next scheduled run.

Local collection accepts the same names in the environment or ignored .env file. Collection stays disabled and the section stays hidden until the resource ID is configured. Only counts, dates, and collection status appear in the dashboard data; credentials and raw Azure responses are never published. A failed window retains its previous data and does not discard other successfully collected windows. A cache with status: error is eligible for immediate retry on the next production or manual workflow run, even with existing history and a recent attempted_at. Each run still makes at most two metric queries, with no retries within the run. Repeated runs while the cache has an error status can therefore make additional queries beyond the scheduled monthly estimate.

If the section reports that metrics are unavailable, check the Update workflow's Cat log step. The collector logs when it starts, whether it uses cached data, and the next eligible request time in UTC. A fresh collection logs each query's time window, how many days have reported counts, and the saved status and cache size. Authentication failures report their HTTP status separately from metric request failures. For a metrics HTTP 403, check the app's Monitoring Reader assignment on the signing account; HTTP 400 indicates a rejected query, and HTTP 404 indicates the resource could not be found. If requests succeed but all counts remain unknown, compare the account's SignCompleted chart in Azure Monitor with the collected data, and verify the subscription's Microsoft.Insights registration. Failure logs include HTTP status codes, exception types, and fixed categories for recognized query errors, without raw responses, resource IDs, or credentials. A run within three hours of a successful collection reuses the cache, even after a role assignment or other configuration change. An error status logs that it is retrying without the three-hour wait. For troubleshooting, setting DASHBOARD_AZURE_SIGNING_DEBUG=true also logs Azure's structured error code and message with credentials, resource identifiers, GUIDs, and URLs redacted. This uses the existing failed response and makes no additional API calls. Remove the setting after diagnosis. Successful responses also log the number of samples and how many contain total or count fields, without logging raw samples or dimension values.

Testing

Python unit tests

uv sync --locked
uv run --locked pytest

JavaScript unit tests

npm ci --ignore-scripts
npm test

Both test suites enforce 100% coverage.