José Almeida
2549704bc1
* docs: expand public user and contributor guides * docs: address public guide review feedback * docs: align web e2e coverage guidance * test: cover collapsed docs references * fix: validate shortcut docs references * fix: parse balanced docs links * fix: handle indented docs code blocks
121 lines
5.1 KiB
Markdown
121 lines
5.1 KiB
Markdown
---
|
|
title: "Workflow Sync"
|
|
description: "Keep workspace workflows synchronized with reviewed definitions in a GitHub repository."
|
|
---
|
|
|
|
# Workflow Sync - Manage Workflows from a GitHub Repo
|
|
|
|
Kandev can keep a workspace's workflows in sync with definition files stored
|
|
in a GitHub repository. Point a workspace at a repo directory, commit workflow
|
|
export files there, and Kandev polls the repo and creates, updates, or removes
|
|
the matching workflows automatically. Synced workflows coexist with workflows
|
|
you create by hand — manual workflows are never touched by a sync.
|
|
|
|
This is useful for:
|
|
|
|
- **Sharing workflows across a team:** everyone's Kandev pulls the same
|
|
definitions from one reviewed repo.
|
|
- **Versioning workflows:** changes go through pull requests and history
|
|
instead of ad-hoc UI edits.
|
|
- **Provisioning new workspaces:** configure the repo once and the standard
|
|
workflows appear on the next sync.
|
|
|
|
---
|
|
|
|
## Setup
|
|
|
|
1. Open **Settings → Workspaces → \<workspace\> → Workflows** and click the
|
|
**GitHub Sync** button at the top.
|
|
2. In the dialog, paste a GitHub link into **Repository link** — a plain repo
|
|
URL, an SSH remote, or a `…/tree/<branch>/<directory>` link that also
|
|
carries the branch and directory. The resolved target (owner/repo and
|
|
directory) is shown under the field; the directory defaults to
|
|
`.kandev/workflows` when the link doesn't include one.
|
|
3. The branch comes from the pasted link (`main` when the link doesn't carry
|
|
one). Toggle **Auto-sync**: when on, Kandev polls the repo on the given
|
|
interval (default 300 seconds, minimum 60); when off, nothing syncs until
|
|
you press **Sync now**.
|
|
4. Save. A status card appears on the page showing what is syncing, the last
|
|
sync result, and any warnings; use its **Sync now** button to run a sync
|
|
immediately instead of waiting for the poller. Reopen the dialog via
|
|
**GitHub Sync** to change or remove the configuration.
|
|
|
|
Authentication reuses Kandev's existing GitHub access (the `gh` CLI login, a
|
|
`GITHUB_TOKEN`/`GH_TOKEN` environment variable, or a PAT stored in the secret
|
|
manager). Private repos work as long as that identity can read them.
|
|
|
|
## File format
|
|
|
|
The directory should contain `.yml`, `.yaml`, or `.json` files in the portable
|
|
`kandev_workflow` export format — exactly what **Export** produces on the
|
|
Workflows settings page. See
|
|
[workflow-import-export.md](workflow-import-export.md) for the full field
|
|
reference. Files with other extensions are ignored; subdirectories are not
|
|
scanned.
|
|
|
|
A minimal file:
|
|
|
|
```yaml
|
|
version: 1
|
|
type: kandev_workflow
|
|
workflows:
|
|
- name: Dev Flow
|
|
steps:
|
|
- name: Todo
|
|
position: 0
|
|
is_start_step: true
|
|
- name: In Progress
|
|
position: 1
|
|
- name: Done
|
|
position: 2
|
|
```
|
|
|
|
The easiest authoring path: build the workflow in the Kandev UI, export it,
|
|
and commit the exported YAML to the repo.
|
|
|
|
## Sync semantics
|
|
|
|
- **Matching:** a synced workflow is identified by its source file path plus
|
|
its `name` inside that file. Renaming a workflow in the repo counts as
|
|
removing one workflow and adding another.
|
|
- **Create:** definitions with no matching workflow are created and marked as
|
|
synced (they show a **Synced** badge in the workflow list).
|
|
- **Update:** matched workflows are updated in place. Steps are matched **by
|
|
name**, so tasks sitting in a step keep their position when the step's
|
|
color, prompt, events, or order change.
|
|
- **Read-only:** the repo is the source of truth. Synced workflows cannot be
|
|
renamed, edited, or deleted from the UI (the API rejects such changes) —
|
|
edit their definitions in the repo instead. Any drift that slips in anyway
|
|
is repaired on the next sync. Reordering workflows on the board and
|
|
exporting them remain available.
|
|
- **Delete:** a previously-synced workflow whose definition disappeared from
|
|
the repo is deleted — but only if it holds no tasks.
|
|
- **Manual workflows** (created in the UI) are never modified or deleted by a
|
|
sync, even if they share a name with a synced definition.
|
|
|
|
### When a workflow can't be updated
|
|
|
|
Some changes can't be applied safely, and Kandev records a **warning** instead
|
|
of forcing them. The warning appears in the status banner of the Sync from
|
|
GitHub section until you resolve it and sync again. Cases:
|
|
|
|
- A step was removed from the definition but still has tasks in it.
|
|
- A removed workflow still has tasks.
|
|
- Step names inside a definition (or the existing workflow) are not unique,
|
|
so steps can't be matched reliably.
|
|
- A file is not valid workflow-export YAML/JSON. The file is skipped and its
|
|
previously-synced workflows are left untouched.
|
|
|
|
A failed sync (repo unreachable, directory missing, GitHub not authenticated)
|
|
is also surfaced in the same banner with the error message.
|
|
|
|
## Notes
|
|
|
|
- Sync configuration is **per workspace**; different workspaces can track
|
|
different repos, branches, or directories.
|
|
- Every sync — periodic or manual — reconciles the workspace against the repo,
|
|
but only writes what actually differs, so a no-drift sync changes (and
|
|
broadcasts) nothing.
|
|
- Removing the sync configuration releases the previously-synced workflows:
|
|
they stay in place but become regular, editable workflows again.
|