Redeploying

Redeploying OpenPhoenix

This is the operational runbook for rebuilding and republishing the repository from a clean state. It records the environment quirks, test landmines, and platform limits that are not obvious from reading the source.

Environment

Two settings are required on this host and are the most common cause of a confusing failure.

Need	Command prefix
GitHub CLI authentication	HOME=/root GH_CONFIG_DIR=/root/.config/gh gh ...
Cargo on PATH	PATH=/root/.cargo/bin:$PATH cargo ...

Without the first, gh reports that you are not logged in even though credentials exist. Without the second, cargo is not found.

The repository clone is /root/OpenPhoenix. The wiki clone is /root/OpenPhoenix.wiki and pushes to HEAD:master.

Local gates

Run these before any push. They mirror the Build workflow exactly.

cargo fmt --all --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --all-targets --locked -- --test-threads=1
cargo build --release --locked --bins

Notes that save time:

• The crate is a single package with two binaries, not a workspace. Flags such as --workspace and --all-features add nothing.
• Nothing is published to a crate registry, so cargo package is not part of the gate.
• The full test run takes several minutes and exceeds a two minute foreground shell limit. Start it as a background task.
• --test-threads=1 is required because several tests mutate process-wide environment variables.

Test landmines

Provider credential fixture. The Colab recovery test supplies a provider credential through its in-memory configuration fixture. It does not depend on a host credential and does not make a network call. Do not reintroduce a CI environment placeholder for this test.

Source hygiene tests. The suite asserts that no source file contains an em dash and that no source file contains comments outside string literals. Both fail the build. Keep this in mind whenever you write new prose or code.

Toolchain policy

rust-toolchain.toml selects the stable channel rather than a fixed version. Workflows call rustup update stable and then let the toolchain file decide, so no workflow hardcodes a version number.

This trades compiler reproducibility for currency, which is the intended policy. Two things offset it:

• Cargo.lock plus --locked still pins the entire dependency graph.
• Every Build and Publish run writes the concrete rustc --version into the job summary, so the exact compiler behind any release is recoverable.

A newer stable can introduce new Clippy lints. Because the workflow denies warnings, the first run after a toolchain bump is the most likely place to see a failure.

Workflows

File	Trigger	Purpose
.github/workflows/first-flight-ci.yml	pushes to main, pull requests, manual dispatch	formatting, lint, tests, release build
.github/workflows/first-flight-release.yml	v*.*.* tags, manual dispatch with a tag input	verify, build five platforms, Debian packages, checksums, container, GitHub release

Build grants no token permissions at all and uses no third party actions. It checks out with a plain unauthenticated shallow git fetch, which keeps credentials out of the job entirely. Do not replace this with a checkout action; the absence is deliberate.

Publish needs artifacts and a registry, so it uses third party actions pinned to full commit hashes. Write permissions are scoped to the final publish job only.

Release procedure

1. Confirm the working tree is clean and the local gates pass.
2. Commit the release.
3. Push main.
4. Create an annotated tag and push it.
5. Watch Publish. Do not publish around a failing leg; fix it.
6. Verify the release assets, the container tag, and the tag target commit.

git tag -a v0.0.1 -m 'phoenix 0.0.1: first flight' HEAD
git push origin refs/tags/v0.0.1

If a tag already exists and must be replaced, delete the GitHub release first, then delete and recreate the tag, then rerun Publish with the tag input.

Release integrity

Publish creates SHA256SUMS for every binary and Debian package and verifies the file before uploading it. The updater checks the selected binary against that manifest before replacing the installed executable. The workflow has no operator-managed signing credential.

Platform limits

These are confirmed by direct testing and are not worked around.

Closed pull requests cannot be deleted. GitHub exposes no API or interface for it. The GraphQL delete mutation rejects pull request node identifiers, and the CLI refuses with an explicit message. Rewriting the commit graph does not help, because pull request records are stored outside it. Only deleting and recreating the repository removes them, which also discards stars, watchers, the wiki association, and the creation date.

Run numbering does not reset when runs are deleted. The counter belongs to the workflow identity, which is keyed to the file path. Deleting every run leaves the next run at the old number. Reusing a path that existed earlier resurrects the old identity and its counter. Only a genuinely new workflow file path starts at run 1.

A queued run can become unremovable. A run stuck in the queued state with no jobs may reject cancel, force cancel, and delete. Disabling the workflow and disabling Actions for the repository do not clear it. Record it and move on.