Dependency update runbook

This runbook is the step-by-step procedure for the two kinds of dependency session that ADR-0017 allows: the monthly update session, which brings every dependency of one repository up to date in one batch, and the security-alert session, which answers one Dependabot security alert. The session prompts in plan/06-agent-workflow.md start these sessions; this page is what the agent then follows. It was written for work package X-003, which also added the automatic checks it refers to.

A dependency here is anything the project downloads instead of writing itself: library packages (Rust crates, npm packages), toolchains (Rust, Node.js, pnpm, Qt), command-line tools (cargo-deny, grype, CMake and the like), Python tools used in CI, container images, and the GitHub Actions that the workflows run. A pin is the place where the project names the exact version of one of them, often together with a hash: a fingerprint of the file that lets a download be checked byte for byte.

The rules every session follows

These are ADR-0017’s rules, as they apply to the work of a session:

• 24-hour minimum age. Never install, pin or upgrade to a version published less than 24 hours ago. Before the session starts, write down its cutoff: the current time in UTC minus 24 hours. Every new version must have been published before the cutoff, and the pull request states each one’s publish date. A newer version that is too young is skipped and noted for next month.
• Exact pins and committed lockfiles. Versions are exact (=1.2.3 in Cargo manifests, 1.2.3 in package.json, ==1.2.3 with hashes for Python tools, a full commit SHA for an action, a digest for a container image). Cargo.lock and pnpm-lock.yaml are regenerated by the tools, never edited by hand.
• No update bots. Never add Dependabot version updates, Renovate or anything like them. The supply-chain workflow fails on their configuration files.
• Install scripts stay disabled. Never allow a package’s install or build script (allowBuilds entries stay false); a Rust crate with a build script is reviewed before it is added.
• Every gate stays green and strong. Run the repository’s full verification gate, fix what breaks, and never weaken, skip or disable a check to get green. If a check is genuinely wrong, fix it in its own commit and explain why.
• Licenses. A new package must use a license on the ADR-0017 allowlist. cargo-deny enforces this for Rust crates; for npm packages, Python tools and everything else, check the license yourself and state it in the pull request (bayan-web’s licence-notice check only makes sure that the license text of every bundled package ships with the app).
• One pull request per repository per session, whose description lists every change (see The pull request). If the change alters a repository’s dependency posture (a new mechanism, a new kind of exception), update its AGENTS.md dependency section, and ADR-0017 if needed, in the same pull request.

How the rules are enforced

Knowing what the machines check tells you what is left for you to check by hand.

Finding publish dates

Before you start

1. Read docs/AGENTS.md §5, ADR-0017 with its amendments, and the “Dependency mechanisms” section of the repository’s AGENTS.md.
2. Start from the latest main, on the branch your session was given.
3. Write down the cutoff (now minus 24 hours, in UTC), for example 2026-11-02T09:00:00Z.
4. Check your tools: in a BayanDocs cloud session, bayandocs-tools lists them. Install pip-audit with docs/scripts/dev-setup.sh --pip-audit; the cloud environment will run that command itself once the batch of cloud-environment changes collected in issue #7 is applied. For bayan-desktop, load . ~/.local/share/bayandocs/desktop-tools/env.sh first.
5. Run the repository’s verification gate once before changing anything, so that you know which failures, if any, were there before you.

Monthly update session

The common steps first; the sections after them list, for each repository, every pin and how to update it.

1. Inventory. Go through the repository’s table below and note, for each pin, the current version, the newest version published before the cutoff, and any newer version you are skipping because it is too young.
2. Read the changelogs of every update, looking for breaking changes, security fixes, new install or build scripts, changed licenses and new dependencies (each new transitive dependency must be on the license allowlist; a new direct dependency needs the justification of AGENTS.md §5, which a routine update does not add).
3. Update the pins, in the order of the repository’s section, regenerating lockfiles and hash lists with the commands given there. Keep the pins that several files repeat equal (the sections name them). Then, for every pin you moved, search every BayanDocs repository, this runbook included, for its old version (also in the shorter form some copies use, such as 1.x for Rust 1.x.0) and for its old hashes, and update every copy that states the current pin, also where no test checks it: AGENTS.md files, READMEs, and the comments of scripts and workflows. Leave dated records, such as reviews and spike reports, as they are.
4. Run the gate and fix what breaks, in the code or the configuration, never by weakening a check. A major version that would need a large change can stay where it is for this month; say so in the pull request and propose a work package.
5. Run the shared checks: python3 .github/supply-chain/check_update_bots.py and python3 .github/supply-chain/audit_python_tools.py (after docs/scripts/dev-setup.sh --pip-audit).
6. Open the pull request described below.

Shared files (all five repositories)

Some files are identical in all five repositories. When one of them changes, change it in all five, in the same session, so that the five pull requests carry the same copy.

After changing any of them, run python3 .github/supply-chain/audit_python_tools.py, which audits every hash-pinned requirements file of the repository.

bayan-core

Gate: cargo xtask verify.

bayan-server

Gate: cargo xtask verify. CI also builds the container and runs scripts/container-smoke-test.sh and grype, and the PostgreSQL tests (cargo xtask test-postgres, cargo xtask sqlx-prepare --check); run them locally when you have Docker and PostgreSQL.

bayan-web

Gate: pnpm verify (it re-installs nothing; run scripts/dev-setup.sh first, which does a frozen install of the new lockfile). The lockfile-integrity check and the audit are part of it.

bayan-desktop

Gate: cmake --workflow --preset verify; scripts/test-engine-sdk.sh when the change could affect how the engine is linked; and when the bayan-core pin moves, scripts/build-engine-sdk.sh and BAYAN_REQUIRE_MOCK_DOCUMENT=1 scripts/test-engine-sdk.sh --sdk build/bayan-core-sdk.

docs

Gate: scripts/verify.sh.

The pull request

The description follows the hand-off template. In “Dependencies added or changed”, give one row per change:

Also list the newer versions you skipped because they were younger than 24 hours, so that the next session picks them up, and any update you deferred (with the reason). For Rust repositories, paste the output of cargo xtask check-lockfile-age. If a pin of the cloud environment changed, end with a reminder to the owner to paste the new setup script.

Security-alert session

A Dependabot security alert (repository → Security → Dependabot) names a vulnerable package, the affected versions and, usually, the fixed versions. The nightly CI runs can raise the same alarm first: cargo deny check (bayan-core, bayan-server), scripts/audit.ts (bayan-web, high and critical advisories) and pip-audit (every repository) fail when a new advisory affects a pinned version.

1. Understand the advisory. Note the package, the ecosystem, the affected and fixed versions, the severity, and the advisory’s identifiers (GHSA, RUSTSEC, PYSEC or CVE).
2. Assess the exposure. Find out which repositories use the package and how: cargo tree -i <crate> (Rust), pnpm why <package> (web), the requirements files (Python tools, which run only in CI or agent sessions). Read the advisory’s description of the vulnerable function or feature and search the code for it. A package that is only a build or test tool is a smaller exposure than one that ships, but it is still fixed.
3. Find the lowest fixed version that is at least 24 hours old. Look up the publish times of the fixed versions as in Finding publish dates.
4. If such a version exists, update to it, with whatever must move with it, and nothing else:
   • Rust: raise the exact requirement in [workspace.dependencies] if the crate is a direct dependency; then cargo +nightly-2026-10-02 update -p <crate> --precise <version> (until Rust 1.100; after that, the pinned stable Cargo).
   • npm: pnpm add -E <package>@<version> (or -D for a development dependency); for a package that only arrives through another one, first try updating the package that brings it in; otherwise add an override of the exact registry version to overrides in pnpm-workspace.yaml (the lockfile-integrity check refuses any override that is not a registry version), and remove it in the next monthly session if it is no longer needed.
   • Python tools: regenerate the affected requirements file with scripts/python-tool-hashes.py and a cutoff 24 hours in the past, in every repository that has the file.
   • Qt: move to the fixed Qt patch release as in the monthly session.
5. If the only fixed version is younger than 24 hours, do not install it. Never bypass the age rule: no minimumReleaseAgeExclude, no hand-edited lockfile, no cargo update with a toolchain that ignores the minimum age, no disabled check. Instead:
   • Mitigate, in this order of preference: pin an unaffected older version if the vulnerability came with a recent release; switch off the affected feature (a Cargo feature, a configuration setting, a code path you can avoid); or add a narrow guard in our own code that keeps attacker-controlled input away from the vulnerable function. Explain to the owner, in plain language, what remains exposed until the fix can be installed.
   • Keep the gates honest while you wait. If the advisory makes a gate fail on every pull request, add a temporary, documented exception, never a broader one: in deny.toml, an entry in [advisories] ignore of the form { id = "RUSTSEC-YYYY-NNNN", reason = "<why we are not exposed or how it is mitigated>; the fix <crate> <version> becomes eligible on <date>; remove then" }; in bayan-web, the advisory’s GHSA identifier in auditConfig.ignoreGhsas of pnpm-workspace.yaml (pnpm audit --ignore <GHSA> writes it) with a comment line above it giving the same information (the checks refuse a comment after the identifier), which scripts/audit.ts repeats on every run; for a Python tool, the fix is usually eligible before anyone needs the gate, so wait. A moderate or lower npm advisory does not fail the gate, so it needs no exception.
   • Come back when the fix is eligible: note the date and time (publish time plus 24 hours), ask the owner to start the follow-up session then (or schedule it, where the session can), and in that session install the fix and remove the exception.
6. Run the gate and open one pull request that explains the vulnerability, our exposure, and the change or mitigation, in plain language, with the advisory’s identifiers and links, the fix’s publish date, and (for a mitigation) the date the fix becomes eligible.

When something does not fit

Stop and ask the owner, with your options and a recommendation, when a fix needs a version younger than 24 hours and no mitigation is possible, when an update needs a new dependency, a new license or a new kind of exception, when a check seems wrong, or when a tool behaves differently from what this runbook says. In the last case, also correct this runbook in a pull request to this repository, so that the next session finds it right.