From f443773a818dc726fe281e62cfcde9bfbef50049 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Thu, 2 Jul 2026 20:31:26 +0300 Subject: ci: track Context7 variant by branch (circinus companion) (#2128) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Companion to vyos-documentation#2127 (rolling). That PR switched the Context7 1.5/1.4 variants to branch-backed and moved context7-refresh to a push trigger, but a push-triggered workflow only fires from the copy present on the pushed branch. Land the same two workflow changes on circinus so pushes here self-refresh the branch variant: - context7-refresh.yml: workflow_run chain → push trigger on rolling/circinus/sagitta; refresh payload uses branch:"circinus". - Delete update-version-tags.yml (obsolete — no more git-tag indirection; branch variant tracks HEAD natively). No context7.json on this branch — Context7 reads config only from the default branch (rolling). Workflow-only change. 🤖 Generated by [robots](https://vyos.io) --- .github/workflows/context7-refresh.yml | 90 +++++++++++------------- .github/workflows/update-version-tags.yml | 113 ------------------------------ 2 files changed, 42 insertions(+), 161 deletions(-) delete mode 100644 .github/workflows/update-version-tags.yml diff --git a/.github/workflows/context7-refresh.yml b/.github/workflows/context7-refresh.yml index 8072c389..c4c33635 100644 --- a/.github/workflows/context7-refresh.yml +++ b/.github/workflows/context7-refresh.yml @@ -1,38 +1,42 @@ name: Context7 refresh -# Listens for completion of "Update version tags" via workflow_run, then -# refreshes the Context7 variant for the branch that fed it. The upstream -# workflow is matched by name — DO NOT rename `Update version tags` without -# updating the `workflows:` field below. +# Refreshes the Context7 variant for the pushed branch. Context7 indexes +# three variants of this library, all tracking a branch HEAD directly: +# - rolling → default variant (omit both `branch` and `tag`) +# - circinus → branch variant `branch: "circinus"` (VyOS 1.5) +# - sagitta → branch variant `branch: "sagitta"` (VyOS 1.4) # -# Context7 API addresses variants by their TYPE: -# - default variant (rolling) → omit both `branch` and `tag` -# - tag-backed variants (1.5/1.4) → `tag: "1.5"` / `tag: "1.4"` -# - branch-backed non-default → `branch: ""` (none used here) -# `branch: "1.5"` returns 404 branch_not_found; `branch: "rolling"` returns -# 400 branch-not-found. Empirically verified 2026-05-10 against the live API. +# The circinus/sagitta variants are declared as branch entries in +# context7.json `previousVersions`. There is no longer any git-tag +# indirection — Context7 re-crawls the branch HEAD on refresh, so the +# variant always reflects current branch content. # -# OPERATOR NOTE: do NOT use GitHub's "Re-run jobs" on `Update version tags`. -# Re-runs replay the original SHA, which would move the version tag -# BACKWARD and trigger this workflow to refresh Context7 against stale -# content. To force a Context7 refresh, use the workflow_dispatch input -# below — it calls Context7 directly without touching any tag. +# Docs-only gating: the `paths:` filter scopes to `docs/**` and +# `context7.json`, so infra-only pushes (workflows, scripts, Docker, +# README, etc.) never trigger a refresh — Context7 only ingests `docs/**` +# (per context7.json `folders`) plus the config file itself. # -# Docs-only gating is enforced upstream: `Update version tags` has a -# `paths:` filter scoped to `docs/**` and `context7.json`, so infra-only -# pushes (workflows, scripts, README, etc.) never fire that workflow and -# this one never sees a workflow_run event for them. +# NOTE: circinus/sagitta must be registered as BRANCH variants in the +# Context7 dashboard (driven by the context7.json `previousVersions` +# branch entries on the default branch). A refresh with `branch: ""` +# returns 404 until Context7 has crawled the config and registered the +# branch variant. on: - workflow_run: - workflows: ["Update version tags"] - types: [completed] + push: + branches: + - rolling + - circinus + - sagitta + paths: + - 'docs/**' + - 'context7.json' workflow_dispatch: inputs: variant: - description: "Context7 variant to refresh (rolling = default; 1.5 = circinus; 1.4 = sagitta)" + description: "Context7 variant to refresh (rolling = default; circinus = 1.5; sagitta = 1.4)" type: choice - options: [rolling, "1.5", "1.4"] + options: [rolling, circinus, sagitta] default: rolling permissions: {} @@ -40,58 +44,48 @@ permissions: {} concurrency: group: >- context7-refresh-${{ - (contains(fromJSON('["rolling","1.5","1.4"]'), inputs.variant) && inputs.variant) - || (github.event.workflow_run.head_branch == 'circinus' && '1.5') - || (github.event.workflow_run.head_branch == 'sagitta' && '1.4') - || (github.event.workflow_run.head_branch == 'rolling' && 'rolling') - || 'invalid' + (github.event_name == 'workflow_dispatch' && inputs.variant) + || github.ref_name }} cancel-in-progress: true jobs: refresh: - if: >- - github.event_name == 'workflow_dispatch' || - (github.event.workflow_run.conclusion == 'success' && - contains(fromJSON('["rolling","circinus","sagitta"]'), github.event.workflow_run.head_branch)) runs-on: ubuntu-latest permissions: {} steps: - name: Refresh Context7 library env: CONTEXT7_API_KEY: ${{ secrets.CONTEXT7_API_KEY }} - HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }} + EVENT_NAME: ${{ github.event_name }} + REF_NAME: ${{ github.ref_name }} DISPATCH_VARIANT: ${{ inputs.variant }} + REPO: ${{ github.repository }} run: | set -euo pipefail if [[ -z "${CONTEXT7_API_KEY:-}" ]]; then echo "ERROR: CONTEXT7_API_KEY is unset or empty" >&2 exit 1 fi - if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then + if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then VARIANT="$DISPATCH_VARIANT" else - case "$HEAD_BRANCH" in - rolling) VARIANT=rolling ;; - circinus) VARIANT=1.5 ;; - sagitta) VARIANT=1.4 ;; - *) echo "Unexpected head_branch: $HEAD_BRANCH" >&2; exit 1 ;; - esac + VARIANT="$REF_NAME" fi - # Defense-in-depth: type:choice UI constraint is bypassable when + # Defense-in-depth: the type:choice UI constraint is bypassable when # workflow_dispatch is invoked via API (`gh workflow run -f variant=…`). case "$VARIANT" in - rolling|1.5|1.4) ;; - *) echo "Invalid variant: '${VARIANT}'. Expected one of: rolling, 1.5, 1.4." >&2; exit 1 ;; + rolling|circinus|sagitta) ;; + *) echo "Invalid variant: '${VARIANT}'. Expected one of: rolling, circinus, sagitta." >&2; exit 1 ;; esac echo "Refreshing Context7 variant: $VARIANT" - # rolling = default variant (no field). 1.5/1.4 = tag-backed. + # rolling = default variant (no field). circinus/sagitta = branch-backed. if [[ "$VARIANT" == "rolling" ]]; then - PAYLOAD="$(jq -nc --arg lib "/${{ github.repository }}" \ + PAYLOAD="$(jq -nc --arg lib "/$REPO" \ '{libraryName: $lib}')" else - PAYLOAD="$(jq -nc --arg lib "/${{ github.repository }}" --arg tg "$VARIANT" \ - '{libraryName: $lib, tag: $tg}')" + PAYLOAD="$(jq -nc --arg lib "/$REPO" --arg br "$VARIANT" \ + '{libraryName: $lib, branch: $br}')" fi curl -fsSL \ --connect-timeout 10 \ diff --git a/.github/workflows/update-version-tags.yml b/.github/workflows/update-version-tags.yml deleted file mode 100644 index cf03c57a..00000000 --- a/.github/workflows/update-version-tags.yml +++ /dev/null @@ -1,113 +0,0 @@ -name: Update version tags - -# context7-refresh.yml triggers via workflow_run on this workflow's name. -# DO NOT rename the `name:` field above without updating context7-refresh.yml. -# -# The `paths` filter gates BOTH this tag-move AND the downstream Context7 -# refresh: Context7 only ingests `docs/**` (per context7.json `folders`), so -# infra-only pushes (workflows, scripts, Docker, CODEOWNERS, README, etc.) -# don't need a version-tag move and don't need a Context7 refresh. The tag's -# only consumer is Context7, so skipping the move on infra-only pushes is -# semantically correct — the tag still represents the latest docs state. -# `context7.json` is included because changes to its `rules`, `folders`, or -# `excludeFolders` affect what Context7 returns even when no .md files moved. - -on: - push: - branches: - - rolling - - circinus - - sagitta - paths: - - 'docs/**' - - 'context7.json' - -permissions: - contents: write - -jobs: - check_head: - runs-on: ubuntu-latest - outputs: - is_current: ${{ steps.head_check.outputs.is_current }} - tag: ${{ steps.branch_tag.outputs.tag }} - steps: - - name: Resolve version tag for branch - id: branch_tag - env: - BRANCH: ${{ github.ref_name }} - run: | - set -euo pipefail - case "$BRANCH" in - rolling) TAG=rolling ;; - circinus) TAG=1.5 ;; - sagitta) TAG=1.4 ;; - *) echo "Unexpected branch: $BRANCH" >&2; exit 1 ;; - esac - echo "tag=$TAG" >> "$GITHUB_OUTPUT" - - - name: Check event SHA matches current branch HEAD - id: head_check - env: - GH_TOKEN: ${{ github.token }} - REPO: ${{ github.repository }} - SHA: ${{ github.sha }} - BRANCH: ${{ github.ref_name }} - run: | - set -euo pipefail - HEAD_SHA="$(gh api "repos/$REPO/branches/$BRANCH" --jq '.commit.sha')" - if [ "$HEAD_SHA" != "$SHA" ]; then - echo "Skipping stale run: event SHA=$SHA, current $BRANCH HEAD=$HEAD_SHA" - echo "is_current=false" >> "$GITHUB_OUTPUT" - exit 0 - fi - - echo "is_current=true" >> "$GITHUB_OUTPUT" - - retag: - needs: check_head - if: needs.check_head.outputs.is_current == 'true' - runs-on: ubuntu-latest - concurrency: - # Per-branch job concurrency serializes tag moves while letting stale - # re-runs exit before they contend for the single pending slot. - group: version-tag-${{ github.ref_name }} - cancel-in-progress: false - steps: - - name: Move version tag to pushed SHA - env: - GH_TOKEN: ${{ github.token }} - REPO: ${{ github.repository }} - SHA: ${{ github.sha }} - BRANCH: ${{ github.ref_name }} - TAG: ${{ needs.check_head.outputs.tag }} - run: | - set -euo pipefail - - # Re-validate HEAD inside retag too: GitHub's "Re-run failed jobs" - # can re-execute retag in isolation without re-running check_head, - # and the branch HEAD may have advanced since the original run. - # Without this guard, a re-run of just retag would PATCH the tag - # to a stale github.sha. - HEAD_SHA="$(gh api "repos/$REPO/branches/$BRANCH" --jq '.commit.sha')" - if [ "$HEAD_SHA" != "$SHA" ]; then - echo "Skipping stale retag: event SHA=$SHA, current $BRANCH HEAD=$HEAD_SHA" - exit 0 - fi - - echo "Pointing tag '$TAG' at $SHA (branch $BRANCH)" - - # PATCH the tag if it exists; create on 404; fail loud on any other - # gh-api error (auth, rate-limit, 5xx) instead of silently falling - # through to POST. - patch_err="" - if ! patch_err="$(gh api -X PATCH "repos/$REPO/git/refs/tags/$TAG" \ - -f sha="$SHA" -F force=true 2>&1)"; then - if grep -q "HTTP 404" <<<"$patch_err"; then - gh api -X POST "repos/$REPO/git/refs" \ - -f ref="refs/tags/$TAG" -f sha="$SHA" - else - echo "$patch_err" >&2 - exit 1 - fi - fi -- cgit v1.2.3