Add GA checklist and rollback runbook
Authored by
mfwolffe <wolffemf@dukes.jmu.edu>
- SHA
01264c23e3a23d9ff788d03a710b5932d5a15c4c- Parents
-
a8becdc - Tree
9e9caff
gardesk/garcard
/
01264c2
Browse files
4 changed files
| Status | File | + | - |
|---|---|---|---|
| M |
README.md
|
2 | 0 |
| M |
RELEASE_NOTES.md
|
13 | 3 |
| A |
docs/release/ga-checklist.md
|
31 | 0 |
| A |
docs/runbooks/rollback-plan.md
|
32 | 0 |
README.mdmodified@@ -79,6 +79,8 @@ gartk prompt path with a persistent in-process modal session and falls back to | ||
| 79 | 79 | 1. `docs/runbooks/migrate-from-external-agent.md` |
| 80 | 80 | 2. `docs/runbooks/incident-triage.md` |
| 81 | 81 | 3. `docs/runbooks/garcardctl-cookbook.md` |
| 82 | +4. `docs/runbooks/rollback-plan.md` | |
| 83 | +5. `docs/release/ga-checklist.md` | |
| 82 | 84 | |
| 83 | 85 | ## Known Limitations |
| 84 | 86 | 1. Policy results are host-specific; some actions may auto-authorize and not trigger prompts. |
RELEASE_NOTES.mdmodified@@ -4,7 +4,10 @@ | ||
| 4 | 4 | 1. Polkit authentication agent backend with queue-aware auth state tracking. |
| 5 | 5 | 2. Built-in gartk prompt path with timeout/cancel behavior and ask-password fallback. |
| 6 | 6 | 3. Daemon health/reconnect loop with forced reconnect support (`SIGHUP` + maintenance pass). |
| 7 | -4. `garcardctl` operational commands: `ping`, `status`, `version`, `auth-summary`, `quit`. | |
| 7 | +4. Lifecycle controls in `garcardctl`: `ping`, `status`, `diagnose`, `version`, `auth-summary`, `temp-list`, `temp-revoke`, `temp-revoke-all`, `quit`. | |
| 8 | +5. Session helper child lifecycle handling and improved helper-protocol fallback behavior. | |
| 9 | +6. Auth lifecycle metadata and retention mapping exposed via `auth-summary`. | |
| 10 | +7. Status health surface now includes authority connectivity and subject-kind fields for control-surface consumers. | |
| 8 | 11 | |
| 9 | 12 | ## Hardening Included In Sprint 04 |
| 10 | 13 | 1. Same-UID enforcement for local IPC control clients. |
@@ -25,8 +28,15 @@ | ||
| 25 | 28 | - `examples/validate-sprint-04.sh` |
| 26 | 29 | - `examples/validate-sprint-04-runtime.sh` |
| 27 | 30 | - `examples/sprint-04-validation.md` |
| 31 | +4. Sprint 07 authorization lifecycle coverage: | |
| 32 | + - `examples/validate-sprint-07.sh` | |
| 33 | + - `examples/sprint-07-validation.md` | |
| 34 | +5. Sprint 08 parity matrix scaffolding: | |
| 35 | + - `examples/sprint-08-parity-matrix.md` | |
| 36 | + - `examples/validate-sprint-08-parity.sh` | |
| 28 | 37 | |
| 29 | -## Known Limitations | |
| 38 | +## Explicit Out-Of-Scope For 0.1.0 | |
| 30 | 39 | 1. Challenge prompting depends on host polkit policy; some actions may auto-authorize. |
| 31 | 40 | 2. Scope is logged-in user sessions (X11), not greeter/session-manager flows. |
| 32 | -3. Full panel controls in `gargears` remain limited to discovery/visibility for now. | |
| 41 | +3. `gargears` integration is limited to command/control-surface parity contracts; native UI parity is tracked separately. | |
| 42 | +4. Multi-seat/remote-session policy nuances are not fully certified in this release cycle. | |
docs/release/ga-checklist.mdadded@@ -0,0 +1,31 @@ | ||
| 1 | +# GA Checklist | |
| 2 | + | |
| 3 | +## Release Candidate Gate | |
| 4 | +1. `cargo test --workspace` passes. | |
| 5 | +2. `./examples/validate-sprint-08-parity.sh` completed. | |
| 6 | +3. `examples/sprint-08-parity-matrix.md` marked with scenario status and evidence links. | |
| 7 | +4. Incident/migration/operator runbooks reviewed: | |
| 8 | + - `docs/runbooks/migrate-from-external-agent.md` | |
| 9 | + - `docs/runbooks/incident-triage.md` | |
| 10 | + - `docs/runbooks/garcardctl-cookbook.md` | |
| 11 | +5. `RELEASE_NOTES.md` reviewed and approved. | |
| 12 | + | |
| 13 | +## Integration Certification | |
| 14 | +1. Gar startup default path validated for daemon availability. | |
| 15 | +2. User-service lifecycle validated (`enable`, `restart`, `disable`). | |
| 16 | +3. Status/diagnostics surface validated for external control-plane consumers. | |
| 17 | + | |
| 18 | +## Tagging | |
| 19 | +1. Candidate tag: | |
| 20 | + - `git tag -a v0.1.0-rc1 -m "garcard 0.1.0-rc1"` | |
| 21 | +2. Push tag: | |
| 22 | + - `git push origin v0.1.0-rc1` | |
| 23 | + | |
| 24 | +## GA Signoff | |
| 25 | +1. No unresolved critical gaps in parity matrix. | |
| 26 | +2. Rollback plan reviewed: | |
| 27 | + - `docs/runbooks/rollback-plan.md` | |
| 28 | +3. Operator handoff includes: | |
| 29 | + - parity report | |
| 30 | + - daemon logs for interactive scenarios | |
| 31 | + - final command cookbook | |
docs/runbooks/rollback-plan.mdadded@@ -0,0 +1,32 @@ | ||
| 1 | +# Rollback Plan | |
| 2 | + | |
| 3 | +## Trigger Conditions | |
| 4 | +1. Critical auth regressions (correct password denied, prompt deadlock, no-agent after restart). | |
| 5 | +2. Authority connectivity failures not recoverable by daemon/polkit restart. | |
| 6 | +3. Control-plane failures in `garcardctl` lifecycle commands. | |
| 7 | + | |
| 8 | +## Immediate Containment | |
| 9 | +1. Stop garcard user service: | |
| 10 | + - `systemctl --user disable --now garcard.service` | |
| 11 | +2. Re-enable prior known-good external agent: | |
| 12 | + - `systemctl --user enable --now <previous-agent>.service` | |
| 13 | +3. Verify authentication fallback path: | |
| 14 | + - `pkcheck --allow-user-interaction --process $$ --action-id com.mesonbuild.install.run` | |
| 15 | + | |
| 16 | +## Artifact Rollback | |
| 17 | +1. Revert to prior release tag/commit in deployment repo. | |
| 18 | +2. Reinstall previous binaries/packages. | |
| 19 | +3. Restart user service stack for session. | |
| 20 | + | |
| 21 | +## Verification | |
| 22 | +1. `pkcheck` challenge opens and accepts valid credentials. | |
| 23 | +2. Previous agent remains stable across repeated auth attempts. | |
| 24 | +3. Incident evidence captured for postmortem: | |
| 25 | + - daemon logs | |
| 26 | + - `garcardctl` outputs | |
| 27 | + - exact rollback commit/tag | |
| 28 | + | |
| 29 | +## Recovery Path Back To Garcard | |
| 30 | +1. Resolve root cause in staging. | |
| 31 | +2. Re-run Sprint 08 parity script and matrix. | |
| 32 | +3. Reattempt controlled rollout with rollback gate in place. | |