Document first-time setup draft publication and run workflow

This commit is contained in:
2026-10-10 01:53:12 +01:00
parent 6bc344dd29
commit c05789d8a6
+76 -9
View File
@@ -1,13 +1,15 @@
# Pipelines
Reusable, sequential workflows for your repositories. A Go CLI/TUI and native
server reuse your OpenCode login; Docker ntfy handles phone notifications.
Reusable, sequential workflows for your repositories, with a Go CLI/TUI,
OpenCode model stages, retained run history, and optional phone notifications.
## Install
`./install.sh` defaults to full **Docker server + ntfy** setup; use `--native` for
native binaries only. Docker mode needs Docker Compose and Python 3; native
mode needs Go 1.27+ and uses your existing OpenCode for model stages.
For the host CLI/TUI walkthrough below, also install Go 1.27+; the Docker
installer installs/updates those clients when host Go is available.
```sh
git clone https://git.a-wan.net/alan/pipelines.git
@@ -25,10 +27,25 @@ Native mode installs the Go binaries and shared OpenCode `pipelines` skill witho
login checks or automatic services. Docker mode configures ntfy accounts/token,
checks publishing/health, and opens container OpenCode provider login on first setup;
existing settings, credentials and volumes are retained on reinstall.
Docker provider credentials live in its persistent container volume, separately
from your host OpenCode login. Setup asks for ntfy account passwords, then your
model-provider login and a model; it validates that model with a small real
generation (provider charges may apply).
With plain `go install ./cmd/...`, also run `pipelines skill install`.
For system-wide use, install the binaries into your chosen system bin directory
with the appropriate permissions. Configuration and data remain per-user.
Docker setup starts the server and saves its client endpoint (default host port
**8081**). Do **not** also start `pipelines serve` for this setup. Explicit `--url`
and `PIPELINES_URL` override the saved endpoint; restart existing TUIs after setup.
Docker mounts your home and installation checkout at their original paths and
uses your UID/GID. Other host repositories need a bind mount at the same absolute
path; repositories on another client computer are not automatically transferred.
These unauthenticated server ports are for trusted networks only—do not expose
them to the public Internet.
### Native server instead (optional)
Start a native server explicitly; fresh databases contain no pipelines:
```sh
@@ -49,6 +66,54 @@ directory you invoke `pipelines run` from. Preview with `--print`. Stop any exis
foreground/legacy server first. Disable with `pipelines service disable` before
uninstalling. See [installation](docs/install.md) for environment and boot options.
## Your first pipeline and run
Start in the repository you want the workflow to operate on:
```sh
cd /path/to/your/repository
pipelines
```
1. **Create:** press **n** or use **:new**. Choose **OpenCode** to author a
workflow together, or **nvim** to edit the Markdown yourself. The selected
editor must be installed on your client computer. Describe the stages, their
inputs/outputs, and the tools they need. Templates (**b** on Home) are optional;
a fresh installation has no published pipelines.
2. **Keep a draft:** finish/exit the editor. Nothing is published just because you
edited it. Press **d** / **:drafts** to find retained drafts; **e** edits and
**v** validates the selected draft.
3. **Publish:** press **s** in Drafts. If it has no name, type one into the name
prompt and press Enter. Then review and explicitly confirm submission. The
server validates it and creates an immutable pipeline version; the draft stays.
4. **Run:** select the published pipeline, press Enter to open it, then **:run** to
start a run. Supply your task and review the confirmation. The run uses the
directory from which you launched the client, not the installer checkout.
5. **Inspect:** watch the full graph and stage progress. **Tab** expands/focuses
panes; **n/p** select recorded stage visits; **hjkl** pan a focused graph.
On a failed run, **D** / **:debug** opens a fresh OpenCode debugging conversation;
retry requires confirmation and restarts the pinned workflow, so earlier side
effects may happen again.
Quit with **:quit**; **q** does not exit. For a terminal-only run after publication:
```sh
pipelines run "your pipeline name" "Describe the task"
```
### Phone notifications
Open **:status** for the server and ntfy connection details. In the ntfy phone
app, add the displayed ntfy server, sign in as **phone-reader** with the password
you set during installation, and subscribe to the displayed topic. Stages must
include a `notify` block to send notifications; see [ntfy setup](docs/ntfy.md).
Installation checks publishing, not reception on your phone.
For Tailscale, both devices must be connected; use
`http://<server-Tailscale-IP>:8090`. Binding to `0.0.0.0` does not bypass firewalls:
UFW/Docker forwarding rules can allow LAN sources but drop Tailscale sources.
See [Tailscale troubleshooting](docs/ntfy.md#tailscale-address-times-out-while-lan-works).
## Uninstall
```sh
@@ -128,9 +193,10 @@ commands support `--json` for agents and scripts.
In the TUI, press **d** (or use **:drafts**) to browse retained drafts, including
CLI-created ones. **e** reopens a draft, **v** validates it, and **s** opens explicit
submission confirmation. Drafts remain retained after submission.
submission confirmation, asking for a name first if needed. Drafts remain retained
after submission.
From a run, press **p** / **:pipeline** to open the pipeline version it used.
From a run, press **P** / **:pipeline** to open the pipeline version it used.
Initial run input also records `pwd`. Press **r** / **:retry** on a failed run
(or `pipelines retry <run-id>`) to start a new attempt with the same original
input, directory, and pipeline version. Completed side effects are not undone.
@@ -138,7 +204,8 @@ Retries restart at the entry stage with fresh OpenCode sessions, never the previ
conversation or intermediate stage output. Pipelines does not automatically delete
generation, agent, or formatting-repair sessions, including on failure/cancellation.
Primary session IDs are retained in run steps (`pipelines inspect <run-id> --json`).
On Home, **r** opens all recent runs; both Home panels show the shortcut.
On Home, **r** opens global run history; **/** fuzzy-searches it. Inside a pipeline,
**r** / **:runs** opens only that pipeline's history.
Quit the TUI with **:quit**; **q** does not exit. **Ctrl+C** remains an interrupt.
Starting/retrying/canceling runs and deleting drafts require confirmation. CLI
publication also prompts; use `--yes` only for explicitly approved automation.
@@ -150,12 +217,12 @@ The TUI uses soft light/dark-adaptive cards, muted metadata, subtle selections,
and local loading animations instead of heavy character borders and inverted bars.
The dashboard includes all-history usage, success rate, average completed duration,
per-pipeline usage, and a 14-day activity chart. CLI: `pipelines stats [--json]`.
Use **:status** for a scrollable server/ntfy popup with health, ports, server-computer
IPs and candidate URLs. CLI: `pipelines status [--json]`. Candidate URLs are not
Use **:status** for two panels: server addresses and ntfy phone connection details.
CLI: `pipelines status [--json]`. Candidate URLs are not
verified reachable; publishing endpoints and credentials are not disclosed.
Retry is offered only after the failed run and its agent have fully stopped.
The run inspector shows its actual path above the details, using the same graph
renderer as pipeline definitions. **g** focuses the graph (arrows pan, j/k scroll).
The run inspector shows the entire pinned graph above the details, dimming stages
and routes not executed. **g** focuses the graph; **hjkl** or arrows pan it.
The path and elapsed duration update while running. **a** opens the active/latest
OpenCode session's recorded tool evidence; this does not attach a live OpenCode UI.
Press **D** / **:debug** (or `pipelines debug <run-id>`) for a fresh OpenCode