Deploy workshop achievements, Discussions, and download metrics safely

• Use a dedicated administrator or service account with write or admin access to microsoft/aibast-agents-library. GitHub traffic endpoints require repository push access for the account even though the PAT permission itself is read-only.
• Define the token owner, backup owner, creation date, expiration date, rotation lead time, and incident contact in the approved secure system of record.
• Prefer the shortest practical expiration that fits the operating cadence. Do not use a personal, unmanaged credential.

Create a fine-grained personal access token with resource owner Microsoft and repository access limited to Only select repositories → aibast-agents-library.

Do not add organization-wide repository access, Contents write, workflows write, or unrelated permissions.

• Open the token's GitHub settings and choose Configure SSO or the organization authorization control shown for Microsoft.
• Authorize the token for the Microsoft organization when SAML/SSO is required.
• If authorization is unavailable, confirm the account is an organization member, the token's resource owner is correct, and the organization permits the credential policy.

In GitHub, open Settings → Secrets and variables → Actions → New repository secret. Name it METRICS_TOKEN, paste the value into GitHub's masked secret field, save, and close the source from which it was copied.

The safe CLI alternative below prompts securely for the value. Run it interactively. Do not append a value, use a body flag, echo or pipe a value, or paste a token into shell history.

gh secret set METRICS_TOKEN --repo microsoft/aibast-agents-library

• Open Settings → Actions → General → Workflow permissions and select Read and write permissions for GITHUB_TOKEN.
• Confirm .github/workflows/workshop-feedback.yml exists on the repository default branch and receives issue events for opened, edited, closed, and reopened activity.
• Keep its workflow-level permissions explicit: issues: write to reconcile managed signal labels and actions: write to dispatch metrics.yml on the repository default branch.
• Confirm .github/workflows/metrics.yml retains issues: read for workshop-feedback and opt-in achievement progress claims, discussions: write for idempotent rating/acquisition mirror synchronization and aggregate reads, plus contents: write for the snapshot commit.
• Confirm scripts/sync_agent_discussions.py runs before scripts/build_metrics.py. It must preserve existing rating Discussion numbers, create one parallel acquisition Discussion per current AIBAST agent, update renamed agents by stable file identity, and write state/agent_discussions.json.
• Keep the population AIBAST-only. RAR is intentionally excluded from every dashboard, leaderboard, and report count in this release.
• Confirm the metrics workflow installs scripts/impact-report-requirements.txt, runs scripts/build_impact_report.py, commits the stable reports/impact-report.* exports, and uploads the same PDF, HTML, email text, Markdown, and JSON as the aibast-impact-report workflow artifact.
• Confirm branch protection permits the intended Actions identity and reviewed workflow to update the snapshot on main. Do not solve a push failure by adding Contents write to the PAT.

# .github/workflows/workshop-feedback.yml
permissions:
  actions: write
  issues: write

# .github/workflows/metrics.yml
permissions:
  contents: write
  discussions: write
  issues: read

Open Actions → metrics, choose Run workflow, select branch main, and run .github/workflows/metrics.yml.

gh workflow run metrics.yml --repo microsoft/aibast-agents-library --ref main

Review the completed run and generated snapshot. Verify the traffic and workshop-scope signals:

• The run reports traffic read live.
• The workshop scope is 72.
• Grid Outage excluded from the workshop scope.
• There is no unavailable_reason for the authorized traffic read.
• The aibast-impact-report artifact contains the PDF plus email-ready text, and the committed report shows 7-day and 30-day values for every defined metric without converting unavailable coverage to zero.
• totals.agent_file_downloads contains only observable AIBAST agent-file transfers. RAR does not contribute to any count.

Then verify Discussion synchronization and structured issue ingestion using existing production signals or repository test fixtures—never synthetic public signals that would pollute totals:

Run the block in a trusted interactive shell. read -s suppresses terminal echo; the token exists only in the temporary environment variable and is unset after the request.

read -s -p "Fine-grained PAT: " GH_TOKEN
printf "\n"
export GH_TOKEN
gh api repos/microsoft/aibast-agents-library/traffic/clones
unset GH_TOKEN

Confirm the response contains traffic data, not an authorization error. Close or clear any terminal capture used during incident diagnostics; do not copy the response into a public issue if it contains organization-sensitive context.

python3 -m json.tool state/metrics.json

• traffic.live is true, traffic.as_of is current for the run, and traffic.unavailable_reason is empty or absent.
• totals.agent_upvotes equals the sum of available rating Discussion upvotes values in agent_metrics; totals.agent_acquisitions independently reconciles the acquisition Discussion values.
• Every agent_metrics row exposes aggregate upvotes, acquisitions, upvote_discussion_url, and acquisition_discussion_url. leaderboards.most_upvoted and leaderboards.most_acquired rank those same aggregates.
• The workshops summary reports its totals and contains exactly 72 rows; Grid Outage is excluded from that set. Each workshop row exposes agent_upvotes separately from usage_events, and both columns reconcile independently.
• achievements.status, achievements.as_of, achievements.coverage, and achievements.caveat form the internal achievement block and explain freshness and availability. Offline runs carry forward that prior block; without one all achievement totals are unavailable/null, never fabricated zero.
• achievements.totals reconciles participants, points, achievement count, starts, workshop completions, hard completions, completion rate, hard-completion rate, and achievement-completion rate from achievements.profiles. Profiles sort by points, badges, completions, then login.
• Each achievement profile contains only the opted-in public GitHub login, points, achievement_count, starts, workshop_completions, hard_completions, server-defined badges/achievement_ids, and completed_workshops. The snapshot persists no issue body, free text, source issue ID, or body-supplied points.
• The 72 achievements.workshops rows match the canonical workshop slugs and primary agents. Their achievement counts, points, starts, workshop completions, hard completions, and rates reconcile independently from usage_events, agent upvotes, signed-in acquisitions, downloads, and repository stars.
• The six canonical achievements.achievements rows use fixed server points and reconcile claims, participants, workshops, and attainment rates to the profile and workshop rollups. No profile can exceed 150 points per started workshop.
• Download totals reconcile to their documented components, including clones, CDN hits, and release downloads. Workshop rollups reconcile to the 65 rows.
• repo.stars, if retained, is repository popularity only and is never counted as an agent upvote.
• agent_discussion_coverage, agent_upvote_coverage, and agent_acquisition_coverage explain Discussion completeness and freshness. Missing mirror threads remain partial/unavailable rather than becoming zero.
• ecosystem.sources.rar.status is excluded; RAR contributes to no count, row, leaderboard, or report.
• Source and coverage caveats explain GitHub's traffic window, CI clone effects, CDN coverage, Discussion signals, workshop scope, and any unavailable source.

Review the rendered repository file or a local checkout. Do not open or distribute a raw-document URL as an operational shortcut.

Open metrics.html from the published site or repository preview and complete these checks:

• Light and dark themes remain readable with visible keyboard focus and no clipped content.
• Desktop and mobile layouts work at narrow widths without horizontal page overflow.
• Refresh updates live public sources and communicates status.
• Upvote opens the selected agent's canonical rating Discussion. Record acquisition opens its parallel acquisition Discussion; neither control asks the visitor to star the repository.
• The agent leaderboards include Most upvoted and Most acquired using the native per-Discussion aggregates.
• The Verified workshop achievements section shows verified points, badges, starts, workshop completions, hard completions, completion rates, the public leaderboard, per-workshop achievement completion, and the canonical achievement rollup from achievements.
• The page distinguishes local self-paced achievements on achievements.html from verified public achievements and links this administrator checklist. Repository stars are never described as achievement points.
• Downloads, signed-in acquisitions, the workshop leaderboard, and all 72 in-scope workshops render with totals that match the snapshot. Workshop Agent upvotes remain visibly separate from Usage events.
• No RAR count, card, table, leaderboard, or report section appears.
• Source explanations distinguish live, historical, estimated, excluded, and unavailable data.

• Rotate before expiry: create the replacement with the same narrow scope, authorize SAML/SSO, update METRICS_TOKEN, rerun the workflow on main, verify live traffic, then revoke the old credential.
• Exposure: revoke the credential immediately, remove it from every exposed location, create a replacement, update the secret, rerun, and follow Microsoft/GitHub incident procedures.
• Source interruption: snapshots reuse the last authorized traffic read instead of zeroing traffic. The page must label unavailable data and preserve as_of; it must not present an authorization failure as a genuine zero.
• Rollback: if a generated snapshot or display is invalid, restore the last reviewed snapshot through a normal commit, correct the workflow or permission, rerun, and revalidate before declaring recovery.
• Permanent rule: never commit a token, secret-bearing command, captured credential, or unredacted diagnostic.