deployctl 0.14.0 — one console for all your projects

[amal-babu-git]

One setup per person (the gh login). Any number of projects on one laptop, each with its own panel, and a switcher between them. Add project handles a new first deployment, a teammate's clone (Import) or a copied-in deployctl. The docs now take a newcomer from nothing to deploying on every merge.

Design brief, with the planning decisions recorded: docs/design/0.14-brief.md.

What changes

1. One setup per person — cli/access.py, deployctl access [show|set-token|forget-token]

• Which registry login a pull uses, in order:

  1. the environment (CI's own GITHUB_TOKEN);
  2. config/local.env (a per-project override);
  3. ~/.deployctl/credentials.env, a read:packages-only token saved once for every project;
  4. the gh login.

  The last two apply only to ghcr.io. The login is resolved only by commands that pull, never by the status the panel polls.

• access set-token checks a classic read:packages token with GitHub before saving it (0600). It never takes the token from argv, and refuses fine-grained tokens.

• The engine: one EXIT/INT/TERM/HUP cleanup logs every host out of the registry and releases the deploy lock. An interrupted or failed run never leaves a login on a host.

• The panel: Your access reads deployctl access --json. The registry row is optional and never raises the Operate alert. A token can be saved from the card, and a refused ssh key comes with the exact line the owner runs.

2. Many projects, one panel each — cli/projects.py, deployctl projects list|add|remove

• ~/.deployctl/projects.json holds name, repository and port. Ports are given once from 8766 and kept. Writes are locked and atomic, and a damaged file is refused, never overwritten.
• deployctl webui:
  • uses the project's own port and reuses a panel already running for it;
  • refuses --port while that panel runs;
  • names whatever else holds the port;
  • new options --detach, --json and --no-browser;
  • outside a project, opens the home panel on 8765.
• /healthz (token-exempt) says which panel a port serves, and replaces panels/<port>.json.
• --stop only ever stops a deployctl panel, and waits for the process to exit.
• paths.find_deploy_dir(repo) finds another project's deploy directory without walking up or reading the caller's DEPLOYCTL_PROJECT.

3. The panel — webui/panel/projects.py; routes.py does not grow

• Projects ▾ switcher: each project's running tag, read lazily with a read-only deploy status. Opening a project sends only its name; the server looks it up and builds the address.
• Add project → open / Import / New project (deployctl init --set KEY=VALUE, allowlisted, never secret) / adopt commands.
• Every dangerous confirmation names the project.
• An unreachable host now reads hosts unreachable — tag unknown; it used to read nothing deployed yet.

4. Docs

• README: the three ways in.
• 05 is now Getting started.
• New 15-FIRST-DEPLOYMENT: every step, what success looks like, what to do on failure.
• 50-WEBUI covers projects and the switcher; the command reference covers the new commands; the 10/20/30/35/40 guides follow the access model.
• CHANGELOG 0.14.0 with upgrade notes; ROADMAP follow-ups. Version 0.14.0.

Hardening found in review:

• Panels are found even with HTTP_PROXY set.
• --stop works without lsof.
• --restart is not refused by a port in TIME_WAIT.

Where this differs from the brief

• projects.json, not .toml: Python has no TOML writer.
• Outside a project, webui always opens the home panel, never the last project used.
• The switcher's running tag is read live, not from a recorded file that goes stale when CI deploys.
• A copied-in deployctl gets the adopt commands to run in a terminal, not plan/apply in the panel.

Testing

• uv run pytest -q: 999 passed, up from 833. New:
  • test_access, test_home, test_projects, test_init_values, test_panel_projects;
  • test_webui_launch: real panel processes, including a dead proxy, no lsof, restart;
  • engine tests: logout after a failed run;
  • a wiring check across every panel module.
• uv run pytest -m e2e: 4 passed. A new Playwright suite, run as its own CI job, drives real panel processes on scratch repositories with TEST-NET hosts and ssh/gh stand-ins:
  • switching projects while a job keeps running;
  • a teammate's clone through Import;
  • a new project to Setup;
  • a confirmation that names the project.
• shellcheck clean. The built wheel installs on its own, and selftest renders all 6 shapes.
• By hand, in the browser pane with scratch projects: the Setup tab's access card, the switcher, and the New form pre-filled from origin.

Upgrading

Stop any running panel first. Then install v0.14.0, gh auth refresh -h github.com -s read:packages, deployctl access, deployctl ci init --env production --force. Panels move to per-project ports; 8765 is now the home panel.

Risk to be aware of

With no read:packages token saved, a laptop-driven pull uses the person's gh token. It can also write to their repositories, and a host holds it for the length of the pull (logged out on any exit). This is the default the brief chose. deployctl access and the panel say so, the docs recommend access set-token for production, and ROADMAP records ways to make a narrow login the default.