Document first-time setup draft publication and run workflow
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user