qbit-mobile-scanners/docs/CI-CD.md

CI and release operation

The primary forge for source, reviews and checks is Gitea (git.kof22.com/QRun-IO); GitHub is a shadow/archive and receives no ordinary writes. The CircleCI and GitHub Actions material below describes the legacy shared QBit pipeline files kept in this repository and is not a statement of which hosted checks currently gate Gitea changes; confirm the checks a pull request actually runs on Gitea. Run the commands in Verification locally either way.

This repository follows the QRun-IO QBit pipeline structure: a canonical CircleCI setup caller and a small .qqq-ci.yml manifest. The default development branch is develop; main is reserved for reviewed releases.

Verification

Check	What runs
CircleCI setup and generated verify	Shared kingsrook/qqq-orb@0.8 QBit verification, including Maven tests and reports
GitHub Demo acceptance / Verify demo HTTP contract	Wrapper-pinned root verification/install, real demo HTTP acceptance, then browser E2E against the packaged frontend
GitHub Demo acceptance / Check Windows demo helpers	PSScriptAnalyzer checks for the local Windows launcher and credential helpers
GitHub CodeQL	QRun-IO's shared QBit source analysis worker, pinned to an immutable commit
Dependabot	Weekly grouped Maven and GitHub Actions update pull requests targeting develop

The three orb version declarations must match exactly. The 0.8 minor track receives centrally managed patch updates, matching the live QRun-IO QBit fleet. Use an exact published patch in all three positions when reproducing a historical pipeline or rolling back. The canonical setup caller does not accept extra jobs; the project-specific demo check therefore lives in GitHub Actions.

Run the same project checks locally with ./mvnw verify install and ./mvnw -f demo/pom.xml verify. The wrapper pins Maven 3.9.9 and validates its distribution checksum. Java 21 is required. The demo uses no external database or user credentials in CI.

Process acceptance tests documents the browser and native test runners. Browser E2E runs inside the existing required demo job, so failures block that check. The Android repository runs the isolated scanner-host E2E against a pinned server revision on pull requests and pushes, in addition to its shared native UI suite.

For workflow syntax, run actionlint .github/workflows/codeql.yml .github/workflows/demo-acceptance.yml. Validate the setup caller with circleci config validate --org gh/QRun-IO .circleci/config.yml, using your existing CircleCI authentication. The shared orb is private; without organization scope and authorization, the compiler can report that it cannot find the orb. Do not place tokens in config files or command arguments.

Development snapshot publication (enabled, November 3)

PR 7 merged as 795a0a2; its post-merge run 3607 on develop passed but captured nothing because publish.snapshot was false. PR 12 set only publish.snapshot: true in .qqq-ci.yml and merged as 286e2e0. Run 3645 succeeded and the snapshot 0.1.0-20261103.233448-3645 was read back anonymously from Central (JAR, POM, sources and Javadocs; the 37 published Java source files match the reviewed source). PR 13 (1345197, Echo defaults to released Printing 1.0.0) then passed CI runs 4157 and 4158.

develop builds therefore publish development snapshots. Every other publication value is unchanged: publish.release_candidate, release, feature, hotfix and asciidoc, release_on_main and release_completion stay false, and the orb stays on 0.8. A snapshot is not a stable release or a promotion to main, and source publication does not equal production 1.0.

Initial publishing policy (historical bootstrap)

At bootstrap, every publish switch and release_completion was explicitly false; only the snapshot switch has since changed (above). Branch pushes, including initial main/develop pushes, and vX.Y.Z tags perform verification without deploying Maven artifacts. There is no automatic RC-cut workflow in this bootstrap configuration. GitHub test-report artifacts are diagnostic outputs, not releases.

RC and stable publication still require a reviewed manifest change after TC22 acceptance and production readiness work are complete. Verify the organization registry context, signing configuration and Maven coordinates. Add the then-current shared qbit-release-rc.yml caller pinned to an immutable commit before enabling release_completion. Update protections and documentation using observed checks from successful hosted runs. The development-snapshot change above does not enable these release paths. The local demo does not depend on any of this pipeline.

Repository settings

These are external settings; files alone cannot enable them:

1. Set the default branch to develop; protect develop, main and release/*. Require pull requests, signed commits, resolved conversations and successful applicable checks; block force pushes/deletion. Bootstrap allows a pull request with zero mandatory human approvals, matching a maintainer-operated project. CODEOWNERS identifies the responsible maintainer; add mandatory reviewers when the organization assigns a review team. Protect release tags when releases are enabled.
2. Connect the repository to the QRun-IO CircleCI organization and enable dynamic configuration. The shared QBit job expects its established qqq-maven-registry-credentials context even for test-only verification; grant only the intended trusted repositories and actors access. Do not put its values in this repository.
3. Require CircleCI setup and verify plus demo acceptance and CodeQL using the actual check names/apps emitted by the first successful hosted run. Do not guess status contexts and leave every pull request permanently blocked.
4. Enable Actions with read-only default workflow permissions, the dependency graph, Dependabot security updates, secret scanning/push protection and private vulnerability reporting when supported.
5. Limit merges to the agreed strategy and configure automatic branch deletion after merges. Keep @KofTwentyTwo as the code owner unless the organization assigns a team.

Sources

The bootstrap was checked against live QRun-IO sources on 2026-10-29:

Local verification passed: CircleCI registry-backed config validation, Actionlint, root Checkstyle and 11 tests, and demo Checkstyle and one HTTP acceptance scenario. The live shared generator also accepted the manifest and selected verification-only jobs for develop, main, feature, release, hotfix and tag cases. The authenticated registry resolved the managed track to 0.8.32 during inspection. Hosted runs remain the authority for actual status-check names.

• QBit canonical caller and manifest.
• Generated pipeline contract and managed patch policy.
• Shared CodeQL caller.

Local older templates may still show orb 0.6.x; they are not the current CI contract.