Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 89 additions & 6 deletions .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,8 @@ jobs:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
statuses: write
outputs:
sha: ${{ steps.commit.outputs.sha }}
steps:
Expand All @@ -146,7 +148,7 @@ jobs:
- env:
VOCABULARY_PLAN: ${{ needs.discover.outputs.plan }}
run: node scripts/vocabulary-maintenance.mjs apply --artifact "$RUNNER_TEMP/vocabulary"
- id: commit
- id: candidate
env:
GH_TOKEN: ${{ github.token }}
run: |
Expand All @@ -156,12 +158,93 @@ jobs:
test -n "$changed"
test -z "$(printf '%s\n' "$changed" | grep -Ev '^(data/public-vocabulary.json|src/public-vocabulary.ts)$')"
git diff --check
git add -- data/public-vocabulary.json src/public-vocabulary.ts
git -c user.name='github-actions[bot]' -c user.email='41898282+github-actions[bot]@users.noreply.github.com' \
-c core.hooksPath=/dev/null commit -m 'chore(telemetry): refresh released public vocabulary'
data_blob=$(git hash-object data/public-vocabulary.json)
source_blob=$(git hash-object src/public-vocabulary.ts)
pending_head=$(git ls-remote origin refs/heads/automation/public-vocabulary | cut -f1)
if [[ -n "$pending_head" ]]; then
merged_head=$(gh pr list --repo "$GITHUB_REPOSITORY" --base main --head automation/public-vocabulary \
--state merged --limit 1 --json headRefOid --jq '.[0].headRefOid // empty')
# A pushed candidate can survive failed PR creation or a closed PR.
# Only a proven merged head may be replaced with different snapshots.
if [[ "$pending_head" != "$merged_head" ]]; then
git fetch --no-tags origin "$pending_head"
pending_data=$(git rev-parse "$pending_head:data/public-vocabulary.json")
pending_source=$(git rev-parse "$pending_head:src/public-vocabulary.ts")
other_paths=$(git diff --name-only "$GITHUB_SHA" "$pending_head" | grep -Ev '^(data/public-vocabulary.json|src/public-vocabulary.ts)$' || true)
if [[ "$pending_data" != "$data_blob" || "$pending_source" != "$source_blob" || -n "$other_paths" ]]; then
echo "Unmerged vocabulary branch has a different candidate; recover or merge it before publishing another payload." >&2
exit 1
fi
fi
fi
printf 'data_blob=%s\nsource_blob=%s\n' "$data_blob" "$source_blob" >> "$GITHUB_OUTPUT"
- id: pr
uses: peter-evans/create-pull-request@3ffccacd46053766916f087ce41d627c0b8cf2d1 # v8.0.0
with:
token: ${{ github.token }}
branch-token: ${{ github.token }}
path: .
base: main
branch: automation/public-vocabulary
add-paths: |
data/public-vocabulary.json
src/public-vocabulary.ts
commit-message: 'chore(telemetry): refresh released public vocabulary'
title: 'chore(telemetry): refresh released public vocabulary'
body: 'Publishes the released public vocabulary validated by this workflow before deployment.'
draft: false
- id: commit
env:
GH_TOKEN: ${{ github.token }}
PR_NUMBER: ${{ steps.pr.outputs.pull-request-number }}
PR_HEAD: ${{ steps.pr.outputs.pull-request-head-sha }}
DATA_BLOB: ${{ steps.candidate.outputs.data_blob }}
SOURCE_BLOB: ${{ steps.candidate.outputs.source_blob }}
run: |
set -euo pipefail
test -n "$PR_NUMBER"
trap 'echo "Publication incomplete; inspect https://github.com/$GITHUB_REPOSITORY/pull/$PR_NUMBER" >&2' ERR
# The action must preserve the exact checked artifact, even if its
# branch preparation observed a newer base. A moved main aborts here.
test "$(git rev-parse "$PR_HEAD:data/public-vocabulary.json")" = "$DATA_BLOB"
test "$(git rev-parse "$PR_HEAD:src/public-vocabulary.ts")" = "$SOURCE_BLOB"
# Keep candidate validation with this publisher; the neutral status
# supplies GitHub's strict up-to-date merge check, including base races.
node scripts/vocabulary-maintenance.mjs admit --target "$GITHUB_SHA" --head "$PR_HEAD"
ready=false
for ((attempt=0; attempt<15; attempt++)); do
state=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" --jq '[.head.sha,(.mergeable|tostring)] | @tsv')
IFS=$'\t' read -r head mergeable <<< "$state"
test "$head" = "$PR_HEAD"
if [[ "$mergeable" == true ]]; then ready=true; break; fi
test "$mergeable" = null
sleep 2
done
if [[ "$ready" != true ]]; then
echo "GitHub has not resolved mergeability; retained the candidate for a later run." >&2
exit 1
fi
node scripts/vocabulary-maintenance.mjs guard-main --target "$GITHUB_SHA"
if ! gh pr merge "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --squash --match-head-commit "$PR_HEAD"; then
echo "Merge did not confirm success; checking the PR before continuing." >&2
fi
receipt=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" --jq '[.merged,.head.sha,.merge_commit_sha,.base.ref,.base.repo.full_name,.head.repo.full_name] | @tsv')
IFS=$'\t' read -r merged head sha base base_repo head_repo <<< "$receipt"
test "$merged" = true
test "$head" = "$PR_HEAD"
test "$base" = main
test "$base_repo" = "$GITHUB_REPOSITORY"
test "$head_repo" = "$GITHUB_REPOSITORY"
test -n "$sha"
gh auth setup-git
git -c gc.auto=0 -c maintenance.auto=false push origin HEAD:refs/heads/main
sha="$(git rev-parse HEAD)"
git fetch --no-tags origin main:refs/remotes/origin/main "$sha"
git merge-base --is-ancestor "$sha" origin/main
if [[ "$(git rev-parse "$sha^")" != "$GITHUB_SHA" ]]; then
echo "Main advanced during merge; a fresh run must validate before deployment." >&2
exit 1
fi
test "$(git rev-parse "$sha:data/public-vocabulary.json")" = "$DATA_BLOB"
test "$(git rev-parse "$sha:src/public-vocabulary.ts")" = "$SOURCE_BLOB"
node scripts/vocabulary-maintenance.mjs guard-main --target "$sha"
printf 'sha=%s\n' "$sha" >> "$GITHUB_OUTPUT"

Expand Down
28 changes: 28 additions & 0 deletions .github/workflows/publication-admission.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
name: Publication admission gate

on:
pull_request_target:
branches: [main]
types: [opened, synchronize, reopened, edited, ready_for_review]

permissions:
contents: read
pull-requests: read
statuses: write

jobs:
inspect-publication-metadata:
runs-on: ubuntu-latest
steps:
- name: Checkout trusted base code
uses: actions/checkout@v7
with:
ref: ${{ github.workflow_sha }}
persist-credentials: false
- uses: actions/setup-node@v7
with:
node-version: 24.22.1
- name: Admit current pull request metadata
env:
GH_TOKEN: ${{ github.token }}
run: node scripts/vocabulary-maintenance.mjs gate
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

## Unreleased

- Publish checked public vocabulary through pull requests with strict GitHub Actions merge admission, and verify the exact source parent and merged payload before the existing deployment step.
- Batch main CodeQL analysis weekly while preserving PR and manual scans.

- Accept identifier-free reporting-installation counts into an optional aggregate-only D1 `(day, gap, reports)` histogram with 90-day pruning; successful update answers advertise the server UTC day only when the binding exists, and production stays unbound. Thanks @roboclaw-bot.
Expand Down
23 changes: 18 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -296,24 +296,37 @@ The existing Deploy workflow owns the whole update:
then runs the normal checks, complete-vocabulary byte-budget tests, and Wrangler dry-run.
4. A separate job can publish only `data/public-vocabulary.json` and `src/public-vocabulary.ts`.
It checks the artifact again without installing dependencies or executing producer-supplied code.
Existing snapshots and aliases cannot change. Publication is a fast-forward from the exact
discovered main commit; concurrent changes stop it instead of overwriting source.
Existing snapshots and aliases cannot change. Publication uses a pull request and a normal
expected-head squash merge. The candidate must have exactly the validated source parent and
change only those two files. A strict GitHub Actions `Publication merge admission` status rule
rejects a merge if main advances after validation. The merged payload, parent, and current main
are verified again before deployment. Unmerged candidates are retained instead of replaced.
5. The existing deployment job checks out the exact checked or published commit. All production
runs share one concurrency group, and stale runs fail the current-main guard. The job tags the
Worker with its commit and verifies that the newest deployment sends 100% of traffic to that
exact tagged version before recording success. It retains the existing trusted npm/Wrangler
toolchain; the artifact cannot replace package files, scripts, or workflow code.

Generation never learns names from client requests. The publisher alone receives `contents: write`;
the deployment job alone receives `statuses: write` and the existing `CLOUDFLARE_API_TOKEN`.
Generation never learns names from client requests. The publisher alone receives `contents: write`
and `pull-requests: write`. It and a trusted metadata-only `pull_request_target` gate can write the
neutral admission status; the gate never executes candidate code. The deployment job retains its
deployment status permission and alone receives the existing `CLOUDFLARE_API_TOKEN`.
No new credential or cross-repository write is required. A commit made with `GITHUB_TOKEN` does not
start the normal push workflow, so its checked deployment happens in the same run.

Before enabling automatic publication, an administrator must activate and verify a default-branch
rule requiring `Publication merge admission` from the GitHub Actions App (ID `15368`), with strict
up-to-date checks and no bypass actors, plus non-fast-forward protection. The publisher verifies
the effective rules before posting its own admission status; it does not depend on a new PR event.
GitHub can redact bypass metadata from its token, so no-bypass configuration is an administrator
admission check. Exposed bypasses or missing protection hold publication and retain the PR.
Existing open PRs without this status need a normal handled PR event after activation.

Merging this workflow into main enables daily generation, data-only publication, and deployment.
Review that operational authority before activation. Coverage can lag until the next daily run plus
GitHub queue delays. GitHub can disable schedules in inactive public repositories. Changed upstream
metadata contracts, moved or deleted tags, incomplete pagination, byte-budget growth, and blocked
fast-forward publication fail visibly and still need maintainer review; automation does not remove
pull-request publication fail visibly and still need maintainer review; automation does not remove
those maintenance boundaries. A failed rollout leaves a retryable status even if its source commit
was already published. Inspect the failed Deploy run, repair the named contract or permission, then
run Deploy manually from current main. Do not weaken the allowlist or force-push past a guard.
Expand Down
72 changes: 71 additions & 1 deletion scripts/vocabulary-maintenance.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ const FILES = ["data/public-vocabulary.json", "src/public-vocabulary.ts"];
const SHA = /^[a-f0-9]{40}$/u;
const NAME = /^[a-z0-9][a-z0-9._/-]{0,63}$/u;
const CONTEXT = "telemetry/deploy";
const ADMISSION = "Publication merge admission";
const ACTIONS_APP = 15368;
const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
const equal = (actual, expected, message) => assert.deepEqual(actual, expected, message);
const sorted = (values) => [...new Set(values)].sort();
Expand Down Expand Up @@ -119,6 +121,56 @@ export function assertCurrentMain(target, current) {
equal(immutable(target), immutable(current), "Main advanced; retry from current main instead of rolling back");
}

function currentPullRequest(repository, number, head) {
const pr = gh(`repos/${repository}/pulls/${number}`);
return pr.state === "open" && pr.base.ref === "main" &&
pr.base.repo.full_name === repository && pr.head.sha === head ? pr : null;
}

function admissionStatus(repository, head) {
gh(`repos/${repository}/statuses/${immutable(head)}`, "-f", "state=success",
"-f", `context=${ADMISSION}`, "-f", "description=Pull request metadata admitted");
}

function requirePublicationRules(repository) {
const rules = gh(`repos/${repository}/rules/branches/main`);
const configs = new Map();
const active = (rule) => {
if (!configs.has(rule.ruleset_id)) {
configs.set(rule.ruleset_id, gh(`repos/${repository}/rulesets/${rule.ruleset_id}`));
}
const config = configs.get(rule.ruleset_id);
// Metadata readers can receive redacted bypasses. An administrator must
// verify no bypass at activation; runtime rejects any exposed exception.
return config.enforcement === "active" &&
(!Object.hasOwn(config, "bypass_actors") ||
(Array.isArray(config.bypass_actors) && config.bypass_actors.length === 0)) &&
(!Object.hasOwn(config, "current_user_can_bypass") || config.current_user_can_bypass === "never");
};
assert(rules.some((rule) => rule.type === "non_fast_forward" && active(rule)),
"Publication held: missing active non-fast-forward protection");
assert(rules.some((rule) => rule.type === "required_status_checks" &&
rule.parameters?.strict_required_status_checks_policy === true &&
rule.parameters.required_status_checks.some((check) =>
check.context === ADMISSION && check.integration_id === ACTIONS_APP) && active(rule)),
"Publication held: missing strict GitHub Actions publication admission rule");
}

function admitPublication(repository, number, head, base) {
const pr = currentPullRequest(repository, number, head);
assert(pr?.head.repo?.full_name === repository, "Publication held: candidate PR identity changed");
equal(command("git", ["rev-list", "--parents", "-n", "1", immutable(head)]).trim().split(" "),
[head, immutable(base)], "Publication held: candidate must have only its validated source parent");
const changes = command("git", ["diff", "--no-renames", "--name-status", base, head]).trim().split("\n");
assert(changes.length > 0 && changes.every((line) => FILES.some((path) => line === `M\t${path}`)),
"Publication held: candidate must change only the two owned files without renames");
requirePublicationRules(repository);
assertCurrentMain(base, gh(`repos/${repository}/git/ref/heads/main`).object.sha);
assert(currentPullRequest(repository, number, head)?.head.repo?.full_name === repository,
"Publication held: candidate PR identity changed");
admissionStatus(repository, head);
}

/** Runs from trusted base code in check/publish jobs; candidate TypeScript is never imported. */
export function validateCandidate(previous, candidate, generated, releases) {
keys(candidate, ["schemaVersion", "legacyAliases", "snapshots", "releases"]);
Expand Down Expand Up @@ -191,8 +243,26 @@ async function main() {
const { values, positionals } = parseArgs({ allowPositionals: true, options: {
base: { type: "string" }, event: { type: "string" }, source: { type: "string" },
artifact: { type: "string" }, target: { type: "string" },
head: { type: "string" },
} });
const [mode] = positionals;
if (mode === "gate") {
const event = JSON.parse(await readFile(process.env.GITHUB_EVENT_PATH, "utf8"));
const repository = process.env.GITHUB_REPOSITORY;
const pr = event.pull_request;
if (event.repository.default_branch === "main" && currentPullRequest(repository, pr.number, pr.head.sha)) {
// This status is commit-wide and neutral. Payload and provenance checks
// belong exclusively to the publisher, not other PRs sharing this SHA.
admissionStatus(repository, pr.head.sha);
} else {
console.log("Obsolete pull request event; no status written");
}
return;
}
if (mode === "admit") {
admitPublication(process.env.GITHUB_REPOSITORY, process.env.PR_NUMBER, values.head, values.target);
return;
}
if (mode === "guard-main") {
assertCurrentMain(values.target, gh("repos/openclaw/telemetry/git/ref/heads/main").object.sha);
return;
Expand Down Expand Up @@ -243,7 +313,7 @@ async function main() {
await writeFile(join(ROOT, FILES[0]), candidate.metadata);
await writeFile(join(ROOT, FILES[1]), candidate.source);
} else {
throw new Error("Use plan, generate, apply, guard-main, or verify-deployment");
throw new Error("Use plan, generate, apply, admit, gate, guard-main, or verify-deployment");
}
}

Expand Down
Loading
Loading