The documented CI secrets procedure produces an archive CI cannot read

[adamtheturtle]

What happens

The two documents describing how to build the CI secrets archive disagree with each other, and one of them describes a procedure which produces an archive CI cannot read.

The archive layout. .github/workflows/test.yml extracts the archive at the repository root and then reads a relative path:

          tar xvf "${HOME}"/secrets/secrets.tar
          cp "./ci_secrets/vuforia_secrets_${JOB_INDEX}.env" ./vuforia_secrets.env

So the archive must contain a ci_secrets/ directory at its root.

docs/source/ci-setup.rst gets this right:

$ mkdir -p ci_secrets
$ tar cvf secrets.tar ci_secrets/

docs/source/contributing.rst does not. It never mentions the name ci_secrets, and archives whatever NEW_SECRETS_DIR happens to be:

$ export NEW_SECRETS_DIR=...
$ tar cvf secrets.tar "${NEW_SECRETS_DIR}"

admin/create_secrets_files.py calls Path(os.environ["NEW_SECRETS_DIR"]).expanduser(), so the variable is expected to hold something like ~/secrets. Archiving an absolute path stores its members with the leading slash stripped, so extraction in CI produces ./Users/<name>/secrets/... and the cp fails. The documented procedure only works if NEW_SECRETS_DIR is exactly the relative path ci_secrets and tar is run from its parent, which the document does not say.

The file numbering. ci-setup.rst says to start at 1:

$ cp vuforia_secrets.env.example ci_secrets/vuforia_secrets_1.env
$ cp vuforia_secrets.env.example ci_secrets/vuforia_secrets_2.env

strategy.job-index is zero-based, so the first matrix job reads vuforia_secrets_0.env. create_secrets_files.py agrees with CI and not with the document — it writes range(num_databases), so vuforia_secrets_0.env through vuforia_secrets_99.env. Anyone following ci-setup.rst by hand produces an archive whose first job fails.

Stale prose about what is needed. contributing.rst says:

Two Cloud databases are necessary in order to run all the Cloud Target tests.
One of those must be an inactive project.
VuMark tests require one VuMark database.

vuforia_secrets.env.example currently needs five sets of credentials: an active cloud database, an inactive cloud database, an active VuMark database, an inactive VuMark database, and Model Target Web API client credentials plus a CAD data URL. It also needs VUFORIA_DATABASE_ID, added recently for the reco counts work in #3359. None of the last three is mentioned.

Why it matters

Lower impact than #3387, because only whoever regenerates the credentials follows these steps, and they can read test.yml. But that is also why it is worth fixing: the procedure runs rarely, the failure appears as 96 CI jobs failing to find a file rather than as anything pointing at the archive, and there is no test that would catch the drift.

It is the same class as #3387 — documented shell commands are shellchecked but never executed, so nothing keeps them in step with the code they drive.

Suggested resolution

Make contributing.rst defer to ci-setup.rst for the archive steps rather than repeating them differently. One correct copy is easier to keep correct than two.

Fix the numbering in ci-setup.rst to start at vuforia_secrets_0.env, and say that it must match zero-based strategy.job-index.

Update the contributing.rst database list to match vuforia_secrets.env.example, or better, point at that file as the source of truth so it cannot drift again.

A check that every variable in vuforia_secrets.env.example is read somewhere in tests/ — and that everything read is in the example — would fit alongside the existing consistency checks in ci/test_custom_linters.py, and would cover the third item permanently.