docs: prop - pici@bfb4fa8

Commit `bfb4fa8`

Eric Bower · 2026-08-15 12:31:41 -0400 EDT

parent b873742

docs: prop

1 files changed, +3, -3

M PROPOSAL.md

+3, -3

......@@ -48,7 +48,7 @@ jobs:
| Input | Description | Default |
| :--- | :--- | :--- |
| `pico_ssh_key` | SSH private key registered with pico.sh for authenticated debug relay access. | `""` (optional, required for debug relay) |
| `debug_on_fail` | Automatically open an interactive `pipe.pico.sh` debug bridge if a job fails. | `"false"` |
| `debug_on_fail` | Automatically open an interactive `pipe.pico.sh` debug bridge if a job fails. If omitted or `auto`, automatically enables when re-running with GitHub debug logging (`RUNNER_DEBUG=1`). | `"auto"` |

### What `pico-sh/pici-action` Does Under the Hood
1. **Tool Installation**: Installs the static `pici` and pinned `zmx` binaries (with SHA256 checksum verification) to `/usr/local/bin`.

......@@ -58,7 +58,7 @@ jobs:
   - `PICI_EVENT="git.${GITHUB_EVENT_NAME}"`
   - `PICI_BRANCH="${GITHUB_REF_NAME}"`
   - `PICI_COMMIT="${GITHUB_SHA}"`
4. **Execution (`pici run`)**: Invokes `pici run --in-place` (with `--debug-on-fail` if enabled).
4. **Execution (`pici run`)**: Invokes `pici run --in-place` (enabling `--debug-on-fail` if `debug_on_fail: true` or if GitHub's native debug re-run is active via `RUNNER_DEBUG=1`).
5. **Job Summaries & Artifact Upload**:
   - `pici` formats the run status table and failed logs into `$GITHUB_STEP_SUMMARY`.
   - If `upload_artifacts` is enabled, the action uploads `/tmp/pici-artifacts/<repo>/<jobid>/` as a workflow artifact.

......@@ -86,7 +86,7 @@ For users who prefer manual step-by-step control or non-GitHub CI environments,
Rather than relying on bash scripts with named FIFOs (`mkfifo`) and background `ssh -N` commands, the relay bridge is implemented directly in Go inside `pici`:

### How it works
1. **Hook into Failure Path**: When `resolveJobExitCode()` detects a non-zero exit in `waitAndReport()` and debug mode is enabled (e.g. `--debug-on-fail` or `-e PICI_DEBUG=1`), `pici` initializes the debug session.
1. **Hook into Failure Path**: When `resolveJobExitCode()` detects a non-zero exit in `waitAndReport()` and debug mode is enabled (via `--debug-on-fail`, `-e PICI_DEBUG=1`, or GitHub Actions' standard `RUNNER_DEBUG=1`), `pici` initializes the debug session.
2. **Native SSH Dialing**: `pici` dials `pipe.pico.sh` using the existing `-pk` / `-ck` SSH key infrastructure.
3. **PTY Allocation (`creack/pty`)**: Spawns an interactive shell (`bash -i` or `$SHELL`) connected to the bidirectional SSH stream.
4. **Attach Instructions & Notifications**: Prints the `ssh -t pipe.pico.sh pipe <topic>` command to stdout and appends it to `$GITHUB_STEP_SUMMARY`.

...	...		@@ -48,7 +48,7 @@ jobs:
48	48		\| Input \| Description \| Default \|
49	49		\| :--- \| :--- \| :--- \|
50	50		\| `pico_ssh_key` \| SSH private key registered with pico.sh for authenticated debug relay access. \| `""` (optional, required for debug relay) \|
51		-	\| `debug_on_fail` \| Automatically open an interactive `pipe.pico.sh` debug bridge if a job fails. \| `"false"` \|
	51	+	\| `debug_on_fail` \| Automatically open an interactive `pipe.pico.sh` debug bridge if a job fails. If omitted or `auto`, automatically enables when re-running with GitHub debug logging (`RUNNER_DEBUG=1`). \| `"auto"` \|
52	52
53	53		### What `pico-sh/pici-action` Does Under the Hood
54	54		1. Tool Installation: Installs the static `pici` and pinned `zmx` binaries (with SHA256 checksum verification) to `/usr/local/bin`.

...	...		@@ -58,7 +58,7 @@ jobs:
58	58		- `PICI_EVENT="git.${GITHUB_EVENT_NAME}"`
59	59		- `PICI_BRANCH="${GITHUB_REF_NAME}"`
60	60		- `PICI_COMMIT="${GITHUB_SHA}"`
61		-	4. Execution (`pici run`): Invokes `pici run --in-place` (with `--debug-on-fail` if enabled).
	61	+	4. Execution (`pici run`): Invokes `pici run --in-place` (enabling `--debug-on-fail` if `debug_on_fail: true` or if GitHub's native debug re-run is active via `RUNNER_DEBUG=1`).
62	62		5. Job Summaries & Artifact Upload:
63	63		- `pici` formats the run status table and failed logs into `$GITHUB_STEP_SUMMARY`.
64	64		- If `upload_artifacts` is enabled, the action uploads `/tmp/pici-artifacts/<repo>/<jobid>/` as a workflow artifact.

...	...		@@ -86,7 +86,7 @@ For users who prefer manual step-by-step control or non-GitHub CI environments,
86	86		Rather than relying on bash scripts with named FIFOs (`mkfifo`) and background `ssh -N` commands, the relay bridge is implemented directly in Go inside `pici`:
87	87
88	88		### How it works
89		-	1. Hook into Failure Path: When `resolveJobExitCode()` detects a non-zero exit in `waitAndReport()` and debug mode is enabled (e.g. `--debug-on-fail` or `-e PICI_DEBUG=1`), `pici` initializes the debug session.
	89	+	1. Hook into Failure Path: When `resolveJobExitCode()` detects a non-zero exit in `waitAndReport()` and debug mode is enabled (via `--debug-on-fail`, `-e PICI_DEBUG=1`, or GitHub Actions' standard `RUNNER_DEBUG=1`), `pici` initializes the debug session.
90	90		2. Native SSH Dialing: `pici` dials `pipe.pico.sh` using the existing `-pk` / `-ck` SSH key infrastructure.
91	91		3. PTY Allocation (`creack/pty`): Spawns an interactive shell (`bash -i` or `$SHELL`) connected to the bidirectional SSH stream.
92	92		4. Attach Instructions & Notifications: Prints the `ssh -t pipe.pico.sh pipe <topic>` command to stdout and appends it to `$GITHUB_STEP_SUMMARY`.

Commit bfb4fa8

Commit `bfb4fa8`