Files
pipelines/docs/pipeline-transfer.md
alan c42a19f7d3 Improve workflow UI, retain stage diffs, and add portable pipeline transfers
Make OpenCode authoring responsive and expand the managed skill references. Add conflict-aware import/export, real-provider reference workflows, and tracked V2 generation for reliable budget accounting.
2026-10-10 20:55:42 +01:00

82 lines
4.4 KiB
Markdown

# Export and import pipeline definitions
In the TUI, run `:export`. Search, move with ↑/↓, and use **Space** to select
pipelines. **Ctrl+A** selects/deselects the filtered list; selections survive
filter changes. **Enter** exports; **Esc** cancels without writing a file.
The ZIP is saved in the directory where you launched the client; its path is
recorded in the TUI logs (`:logs`). Existing files are never overwritten.
Run `:import`, enter the ZIP path, select definitions, and confirm publication.
For each selected name that already exists, import compares the stored definition
with the incoming source. Identical source is skipped automatically; differing
source offers:
- **Keep existing** (`k`): skip this incoming definition.
- **Keep both** (`b`): create a copy named `NAME (imported)` (numbered when needed).
- **Use imported** (`i`): publish it as a new version of the existing pipeline.
All previous versions and run history are retained, not overwritten.
- **View diff** (`d`): show a highlighted existing-versus-imported source preview.
- **Cancel** (`c` or empty input): abort before any selected definition is published.
Comparison uses exact source bytes, not exported version numbers: independent
servers may have different version numbers for the same definition. Whitespace-only
changes are therefore differences too. Choices are resolved before the final
publication confirmation; `--yes` does not choose a conflict resolution for you.
The destination is the currently connected server, even when it runs on a
different computer. The ZIP is read/written on the client computer.
CLI equivalents:
```sh
# Interactive multi-selection
pipelines export --output workflows.zip
pipelines import workflows.zip
# Export every latest definition without a picker
pipelines export --all --output workflows.zip
# Select exact names/IDs without a picker
pipelines export "Research" "Review" --output workflows.zip
# Explicit automation: create everything from the archive
pipelines --url ws://other-server:8080/connect import workflows.zip --all --yes --json
# Automation when differing names exist: choose a policy explicitly
pipelines import workflows.zip --all --on-conflict keep --yes --json
pipelines import workflows.zip --all --on-conflict both --yes --json
pipelines import workflows.zip --all --on-conflict import --yes --json
# Original one-pipeline Markdown export remains available
pipelines export "Research" --version 1 > research.md
```
An archive contains a versioned `manifest.json` with original names, version
numbers and SHA-256 checksums, plus one Markdown definition per pipeline. Latest
versions are pinned when selection starts; `--version N` exports that exact
version for each selected pipeline. No model calls are made.
Import checks the archive/checksums, destination names and server validation before
publishing. New names/copies start at v1; choosing imported increments the existing
pipeline's destination version. In JSON mode a differing name without an explicit
`--on-conflict` policy fails before publication, rather than asking interactively.
Exported version numbers are provenance, not destination version numbers.
Confirmation warns that schedules in the definitions will activate. Model/tool
availability and notification delivery still need runtime checks on the destination.
There is no automatic execution of imported stages.
Publication uses individual guarded requests, not an atomic batch. New names use
create-only guards; updates require the exact existing version used for comparison.
Concurrent changes cause a conflict, never a forced overwrite. A network
failure or concurrent name/version collision may leave some definitions published. Failures
report the confirmed accepted names (also in JSON mode); an ambiguous response may
mean the destination accepted a request, so inspect its list before retrying.
Already-accepted definitions are retained, never rolled back. JSON reports
`imported` (all accepted names), `updated` (new versions), and `skipped` (names with
reasons `identical` or `kept-existing`).
This is a portable definition export, **not a complete database backup**: it does
not include older versions, runs/diffs, audit history, retained drafts, repository
files, provider credentials or server notification settings. Definitions may
themselves contain sensitive prompts; archives are private local files, not
encrypted. Limits: 1,000 definitions, 1 MiB per definition and 32 MiB total source.