Skip to content

Commit 61e6c92

Browse files
juliamuiruri4Copilot
juliamuiruri4
and
Copilot
committed
Add agentic refresh Phase 0 controls
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 792f495 commit 61e6c92

28 files changed

Lines changed: 2077 additions & 4 deletions

‎.gitattributes‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.github/workflows/*.lock.yml linguist-generated=true merge=ours

‎.github/CODEOWNERS‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Julia is the merge authority; Bethany is the independent fallback reviewer.
2+
* @juliamuiruri4 @BethanyJep

‎.github/agentic-refresh/README.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Agentic refresh controls
2+
3+
This directory contains the Phase 0 governance boundary for future quest refresh
4+
automation.
5+
6+
- [`capabilities.json`](./capabilities.json) keeps every repository report-only
7+
until an administrator confirms all write prerequisites.
8+
- [`quests.json`](./quests.json) defines source allowlists, repository ownership,
9+
approval identity, branch shape, and operational limits.
10+
- [`governance.md`](./governance.md) documents the GitHub App and repository
11+
settings that require administrator action.
12+
- [`lifecycle-policy.md`](./lifecycle-policy.md),
13+
[`audience-style-guide.md`](./audience-style-guide.md),
14+
[`report-contract.md`](./report-contract.md),
15+
[`stack-policy.md`](./stack-policy.md), and
16+
[`asset-policy.md`](./asset-policy.md) define the non-negotiable content and
17+
workflow contracts.
18+
19+
Run the local Phase 0 checks with:
20+
21+
```bash
22+
node scripts/validate-refresh-config.mjs
23+
node scripts/validate-content-links.mjs
24+
mkdocs build --strict
25+
gh aw compile --strict --validate
26+
```
27+
28+
No scheduled or write-capable agentic workflow is enabled in Phase 0.

‎.github/agentic-refresh/asset-policy.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Asset policy
2+
3+
Asset work begins with an approved brief and stays inside the quest's owned
4+
paths.
5+
6+
- Prefer existing assets or text when they explain the step adequately.
7+
- Use original SVG for static diagrams and Remotion only when motion adds
8+
instructional value.
9+
- Preserve editable source and deterministic rendering commands.
10+
- Record dimensions, file size, alt text, source files, and render commands in
11+
an asset manifest.
12+
- Verify light and dark readability, current branding, and the absence of
13+
credentials or personal data.
14+
- Use controlled product screenshots and document any manual validation.
15+
- Keep asset revisions on the same `01-core` branch initially.
16+
- Stop after two automated revision rounds and request human guidance.

‎.github/agentic-refresh/audience-style-guide.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Audience and style guide
2+
3+
Content serves beginner and intermediate JavaScript and TypeScript developers.
4+
5+
- State prerequisites, expected cost, cleanup, and platform limitations before
6+
a learner starts a billable or environment-specific step.
7+
- Prefer a short working path, then use progressive disclosure for optional or
8+
expensive exploration.
9+
- Explain product terms at first use and avoid unexplained architecture jumps.
10+
- Keep commands and code copyable, language-appropriate, and consistent with
11+
the target repository.
12+
- Separate verified product facts from repository observations and proposed
13+
teaching choices.
14+
- Do not claim a lifecycle, feature, or recommended pattern without an
15+
allowlisted citation.
16+
- Preserve the quest scenario unless an approved plan explicitly changes it.

‎.github/agentic-refresh/capabilities.json‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
{
2+
"version": 1,
3+
"defaultMode": "report-only",
4+
"lastReviewedAt": "2026-07-23",
5+
"repositories": [
6+
{
7+
"name": "Azure-Samples/JavaScript-AI-Buildathon",
8+
"status": "blocked",
9+
"writeAutomationAllowed": false,
10+
"capabilities": {
11+
"githubAppInstalled": false,
12+
"copilotCodeReviewEnabled": true,
13+
"aiCreditBudgetAvailable": false,
14+
"repositoryAdministratorAvailable": true,
15+
"refreshBranchCreationAllowed": false,
16+
"rulesetConfigured": false,
17+
"conversationResolutionRequired": true,
18+
"codeOwnerReviewRequired": false,
19+
"requiredChecksKnown": true
20+
},
21+
"requiredChecks": [
22+
"validate-content",
23+
"validate-agentic-workflows"
24+
],
25+
"pendingRequiredChecks": [
26+
"copilot-review-gate"
27+
],
28+
"approval": {
29+
"approvedBy": null,
30+
"approvedAt": null,
31+
"evidence": null
32+
},
33+
"auditEvidence": {
34+
"copilotCodeReviewWorkflowId": 209015997,
35+
"rulesetId": 19622585,
36+
"approverVariable": "REFRESH_APPROVER_LOGIN=juliamuiruri4",
37+
"labelsConfigured": true
38+
},
39+
"blockers": [
40+
"An Azure-Samples organization owner must create or approve and install the dedicated GitHub App.",
41+
"The Copilot Code Review AI-credit budget has not been confirmed.",
42+
"Ruleset 19622585 must be activated after CODEOWNERS and both Phase 0 validation checks are merged and have successful check runs.",
43+
"The human-only merge ruleset template must be created or confirmed in repository settings; the REST API returned 404 when user bypass was requested.",
44+
"Automation permission to create refresh/** branches has not been approved."
45+
]
46+
},
47+
{
48+
"name": "Azure-Samples/serverless-chat-langchainjs",
49+
"status": "blocked",
50+
"writeAutomationAllowed": false,
51+
"capabilities": {
52+
"githubAppInstalled": false,
53+
"copilotCodeReviewEnabled": true,
54+
"aiCreditBudgetAvailable": false,
55+
"repositoryAdministratorAvailable": false,
56+
"refreshBranchCreationAllowed": false,
57+
"rulesetConfigured": false,
58+
"conversationResolutionRequired": false,
59+
"codeOwnerReviewRequired": false,
60+
"requiredChecksKnown": false
61+
},
62+
"requiredChecks": [],
63+
"approval": {
64+
"approvedBy": null,
65+
"approvedAt": null,
66+
"evidence": null
67+
},
68+
"blockers": [
69+
"No repository administrator confirmation has been recorded.",
70+
"An Azure-Samples organization owner must approve and install the dedicated GitHub App.",
71+
"The Copilot Code Review AI-credit budget has not been confirmed.",
72+
"The active rulesets have not been confirmed to satisfy the refresh governance contract.",
73+
"Automation permission to create refresh/** branches has not been approved."
74+
]
75+
},
76+
{
77+
"name": "Azure-Samples/mcp-agent-langchainjs",
78+
"status": "blocked",
79+
"writeAutomationAllowed": false,
80+
"capabilities": {
81+
"githubAppInstalled": false,
82+
"copilotCodeReviewEnabled": true,
83+
"aiCreditBudgetAvailable": false,
84+
"repositoryAdministratorAvailable": false,
85+
"refreshBranchCreationAllowed": false,
86+
"rulesetConfigured": false,
87+
"conversationResolutionRequired": false,
88+
"codeOwnerReviewRequired": false,
89+
"requiredChecksKnown": false
90+
},
91+
"requiredChecks": [],
92+
"approval": {
93+
"approvedBy": null,
94+
"approvedAt": null,
95+
"evidence": null
96+
},
97+
"blockers": [
98+
"No repository administrator confirmation has been recorded.",
99+
"An Azure-Samples organization owner must approve and install the dedicated GitHub App.",
100+
"The Copilot Code Review AI-credit budget has not been confirmed.",
101+
"No qualifying main-branch ruleset or classic branch protection was visible.",
102+
"Automation permission to create refresh/** branches has not been approved."
103+
]
104+
}
105+
]
106+
}

‎.github/agentic-refresh/capability-matrix.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Refresh capability matrix
2+
3+
The machine-readable source of truth is
4+
[`capabilities.json`](./capabilities.json). A repository is **report-only**
5+
unless every required capability is confirmed, an administrator records
6+
approval evidence, and `writeAutomationAllowed` is explicitly set to `true`.
7+
8+
| Repository | Current mode | Capability status | Administrator approval |
9+
|---|---|---|---|
10+
| `Azure-Samples/JavaScript-AI-Buildathon` | Report-only | Blocked | Missing |
11+
| `Azure-Samples/serverless-chat-langchainjs` | Report-only | Blocked | Missing |
12+
| `Azure-Samples/mcp-agent-langchainjs` | Report-only | Blocked | Missing |
13+
14+
## Required confirmation
15+
16+
For each repository, an administrator must confirm:
17+
18+
1. The dedicated GitHub App is installed for that repository.
19+
2. Copilot Code Review is enabled and an AI-credit budget is available.
20+
3. `refresh/**` branches may be created by the App.
21+
4. The main-branch ruleset requires pull requests, CODEOWNER approval,
22+
conversation resolution, and the repository's known CI checks.
23+
5. The App cannot bypass the ruleset, push to `main`, force-push, delete a
24+
protected branch, or merge.
25+
6. `REFRESH_APPROVER_LOGIN` is set to the exact approved GitHub login.
26+
7. `AGENTIC_REFRESH_APP_ID` and `AGENTIC_REFRESH_APP_PRIVATE_KEY` are configured
27+
without exposing their values in issues, logs, or repository files.
28+
29+
Record the approver login, UTC timestamp, and a settings or approval reference
30+
in `capabilities.json`. Do not replace an unknown capability with an assumption.
31+
32+
## Audit findings
33+
34+
The SSO-authorized keyring token completed a read-only audit on July 23, 2026.
35+
36+
- Buildathon: Julia has repository administration; Copilot Code Review is
37+
active; refresh labels and `REFRESH_APPROVER_LOGIN` are configured. Active
38+
branch protection requires one approval and conversation resolution. Disabled
39+
ruleset `19622585` is prepared to require the Phase 0 checks, one CODEOWNER
40+
approval, approval after the latest push, conversation resolution, and to
41+
block deletion and force-push after this Phase 0 change lands. A separate
42+
update-restriction template permits only Julia, through a pull request, to
43+
update `main`; the App is not a bypass actor. GitHub returned HTTP 404 when
44+
that user-bypass ruleset was created through the REST API, so an administrator
45+
must confirm or create it in repository settings. The App, AI-credit budget
46+
confirmation, ruleset activation, and explicit App permission for
47+
`refresh/**` branches are missing.
48+
- Serverless Chat: Julia has write but not administration; two active rulesets
49+
and Copilot Code Review are visible. An administrator must confirm the
50+
rulesets, budget, App installation, and `refresh/**` branch policy.
51+
- MCP Agent: Julia has write but not administration; Copilot Code Review is
52+
visible, but no qualifying ruleset or classic main-branch protection was
53+
visible. An administrator must establish the complete governance boundary.
54+
55+
Julia cannot access the Azure-Samples organization settings needed to create an
56+
organization-owned App. An organization owner must complete that action.
57+
58+
## Organization-owner handoff
59+
60+
Ask an Azure-Samples owner to:
61+
62+
1. Create an organization-owned **Azure Samples Agentic Refresh** GitHub App
63+
with the repository permissions in `github-app.json` and no organization
64+
permissions.
65+
2. Disable webhooks and restrict installation to the Azure-Samples account.
66+
3. Install it only on `Azure-Samples/JavaScript-AI-Buildathon`.
67+
4. Provide the App ID through repository variable
68+
`AGENTIC_REFRESH_APP_ID`.
69+
5. Store the generated PEM private key directly in repository secret
70+
`AGENTIC_REFRESH_APP_PRIVATE_KEY`; never send it through chat or an issue.
71+
6. Confirm that Copilot Code Review has an available AI-credit budget.
72+
7. Confirm that the App may create `refresh/**` branches but cannot bypass
73+
ruleset `19622585`, write to `main`, or merge.
74+
8. After the Phase 0 pull request merges and both validation checks have run
75+
successfully, activate ruleset `19622585` and the human-only merge ruleset.
76+
9. Confirm that App installation tokens are available only to the pinned
77+
deterministic safe-output action and never to an agent or generic shell step.
78+
79+
The external repositories stay report-only. Their App installation requires a
80+
separate capability approval after a repository administrator confirms each
81+
ruleset, CI, CODEOWNER, branch, and budget requirement.

‎.github/agentic-refresh/github-app.json‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
{
2+
"version": 1,
3+
"name": "agentic-refresh",
4+
"installationScope": "selected-repositories",
5+
"repositories": [
6+
"Azure-Samples/JavaScript-AI-Buildathon",
7+
"Azure-Samples/serverless-chat-langchainjs",
8+
"Azure-Samples/mcp-agent-langchainjs"
9+
],
10+
"permissions": {
11+
"metadata": "read",
12+
"contents": "write",
13+
"pullRequests": "write",
14+
"issues": "write",
15+
"actions": "read",
16+
"checks": "read"
17+
},
18+
"forbiddenPermissions": [
19+
"administration",
20+
"deployments",
21+
"environments",
22+
"organizationAdministration",
23+
"releases"
24+
],
25+
"credentials": {
26+
"appIdVariable": "AGENTIC_REFRESH_APP_ID",
27+
"privateKeySecret": "AGENTIC_REFRESH_APP_PRIVATE_KEY"
28+
},
29+
"constraints": {
30+
"allowedBranchPrefix": "refresh/",
31+
"defaultBranchWritesAllowed": false,
32+
"mergeAllowed": false,
33+
"humanMergeRuleset": ".github/agentic-refresh/rulesets/human-merge.json",
34+
"installationTokenMaximumLifetimeMinutes": 60
35+
},
36+
"tokenHandling": {
37+
"exposedToAgent": false,
38+
"consumer": "pinned-deterministic-safe-output-action",
39+
"allowedOperations": [
40+
"createRefreshBranch",
41+
"updateRefreshBranch",
42+
"createPullRequest",
43+
"updatePullRequest",
44+
"createIssue",
45+
"updateIssue",
46+
"comment"
47+
],
48+
"forbiddenOperations": [
49+
"mergePullRequest",
50+
"updateDefaultBranch",
51+
"deleteBranch",
52+
"forcePush"
53+
]
54+
}
55+
}

‎.github/agentic-refresh/governance.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Agentic refresh governance
2+
3+
## Safety boundary
4+
5+
Phase 0 creates policy, validation, and authoring support only. It does not
6+
enable scheduled discovery, issue creation, content edits, branch creation, pull
7+
requests, or merge. Any later workflow must read `capabilities.json` and stop in
8+
report-only mode unless the target repository is explicitly approved for write
9+
automation.
10+
11+
## GitHub App
12+
13+
Create a dedicated GitHub App from [`github-app.json`](./github-app.json):
14+
15+
1. Select **Only on this account** for installation.
16+
2. Grant only the listed repository permissions.
17+
3. Install it only on repositories whose capability matrix is approved.
18+
4. Store the App ID as `AGENTIC_REFRESH_APP_ID`.
19+
5. Store the private key as `AGENTIC_REFRESH_APP_PRIVATE_KEY`.
20+
6. Never grant administration, deployment, environment, release, organization,
21+
ruleset-bypass, or merge authority.
22+
23+
Tokens must be installation tokens scoped to one target repository and must
24+
expire within one hour. Workflows may create only `refresh/**` branches. The
25+
agent process must never receive an App token. A pinned deterministic safe-output
26+
action mints and consumes the token only after validating the target repository,
27+
branch, paths, operation count, and patch size. That action exposes no merge,
28+
default-branch update, deletion, or force-push operation.
29+
30+
## Repository settings
31+
32+
Apply the disabled templates in [`rulesets/main.json`](./rulesets/main.json) and
33+
[`rulesets/human-merge.json`](./rulesets/human-merge.json) only after both
34+
validation workflows have produced successful check runs. Review the generated
35+
settings before changing `enforcement` to `active`.
36+
37+
Create the labels in [`labels.json`](./labels.json). Configure:
38+
39+
- variable `REFRESH_APPROVER_LOGIN`;
40+
- variable `AGENTIC_REFRESH_APP_ID`;
41+
- secret `AGENTIC_REFRESH_APP_PRIVATE_KEY`.
42+
43+
The main ruleset must require:
44+
45+
- pull requests;
46+
- one CODEOWNER approval;
47+
- approval after the latest push;
48+
- conversation resolution;
49+
- `validate-content`;
50+
- `validate-agentic-workflows`;
51+
- no force-push or branch deletion.
52+
53+
The App must not be a bypass actor. Phase 3 adds `copilot-review-gate` only after
54+
that check has been proven on every pull-request head SHA.
55+
56+
The human-only ruleset contains only an update restriction. Julia is its sole
57+
initial bypass actor and may bypass it only through a pull request. The main
58+
protections are in a separate ruleset with no bypass actors, so the human merge
59+
actor cannot bypass required checks, review, conversation resolution, or
60+
force-push and deletion protections.
61+
62+
The platform update restriction protects the final `main` update. The App must
63+
update `refresh/**` branches to build a stack, so intermediate stack bases cannot
64+
use that restriction. Their no-merge boundary is enforced by token isolation:
65+
only the pinned safe-output action receives the App token, and merge is not an
66+
available output. Changes to that action, workflow policy, or permissions require
67+
the protected automation review path.
68+
69+
## SAML authorization
70+
71+
If `gh api repos/Azure-Samples/JavaScript-AI-Buildathon` returns HTTP 403:
72+
73+
1. Run `gh auth status` and identify the active token.
74+
2. Open the SSO authorization URL printed by `gh`.
75+
3. Authorize that exact token for the Microsoft Open Source enterprise.
76+
4. Re-run the API request.
77+
5. If an environment `GH_TOKEN` overrides an authorized keyring token, remove
78+
the override for the audit or authorize the overriding token.
79+
80+
Do not replace this control with a broader personal access token.

0 commit comments

Comments
 (0)