;
};
+ readOnly: boolean;
};
+// SyncedBadge marks workflows managed by workflow sync (workflow.source ===
+// "github"). Hovering / focusing shows which repo-relative file it came from
+// so users don't accidentally edit a workflow that the next poll will
+// overwrite.
+function SyncedBadge({ sourcePath }: { sourcePath?: string }) {
+ return (
+
+
+
+ Synced
+
+
+
+ Read-only — managed by workflow sync from {sourcePath || "a configured repository"}. Edit or
+ remove it in the synced repository.
+
+
+ );
+}
+
function WorkflowCardBody({
workflow,
isWorkflowDirty,
@@ -257,6 +321,7 @@ function WorkflowCardBody({
workflowLoading,
workflowSteps,
stepActions,
+ readOnly,
}: WorkflowCardBodyProps) {
const healthyProfiles = useHealthyAgentProfiles(workflow.agent_profile_id);
@@ -267,10 +332,17 @@ function WorkflowCardBody({
Workflow Name
{isWorkflowDirty &&
+ Read-only — managed by workflow sync
+
+ )}
@@ -283,6 +355,7 @@ function WorkflowCardBody({
onValueChange={(value) =>
onUpdateWorkflow({ agent_profile_id: value === "none" ? "" : value })
}
+ disabled={readOnly}
>
@@ -320,6 +394,7 @@ function WorkflowCardBody({
onAddStep={stepActions.handleAddWorkflowStep}
onRemoveStep={stepActions.handleRemoveWorkflowStep}
onReorderSteps={stepActions.handleReorderWorkflowSteps}
+ readOnly={readOnly}
/>
)}
@@ -386,12 +461,17 @@ function useWorkflowCardState(props: WorkflowCardProps) {
const wfDel = useWorkflowDeleteState();
const stepDel = useStepDeleteState();
const isNewWorkflow = workflow.id.startsWith("temp-");
+ // Workflows synced from a configured GitHub repo are read-only: the
+ // backend rejects definition mutations with a 409, so the UI disables the
+ // matching affordances (name/agent-profile/steps/delete) up front.
+ const readOnly = workflow.source === "github";
const deleteWorkflowRequest = useRequest(onDeleteWorkflow);
const { workflowSteps, setWorkflowSteps, workflowLoading, refreshWorkflowSteps } =
useWorkflowSteps(workflow.id, initialWorkflowSteps, isNewWorkflow, toast);
const stepActions = useWorkflowStepActions({
workflow,
isNewWorkflow,
+ readOnly,
workflowSteps,
setWorkflowSteps,
refreshWorkflowSteps,
@@ -404,6 +484,7 @@ function useWorkflowCardState(props: WorkflowCardProps) {
const { activeSaveRequest, handleSaveWorkflow } = useWorkflowSaveActions({
workflow,
isNewWorkflow,
+ readOnly,
workflowSteps,
templateStepCount,
onSaveWorkflow,
@@ -413,6 +494,7 @@ function useWorkflowCardState(props: WorkflowCardProps) {
const wfDeleteHandlers = useWorkflowDeleteHandlers({
workflow,
isNewWorkflow,
+ readOnly,
otherWorkflows,
wfDel,
deleteWorkflowRun: deleteWorkflowRequest.run,
@@ -436,6 +518,7 @@ function useWorkflowCardState(props: WorkflowCardProps) {
wfDel,
stepDel,
isNewWorkflow,
+ readOnly,
deleteWorkflowRequest,
workflowSteps,
workflowLoading,
@@ -468,6 +551,7 @@ export function WorkflowCard(props: WorkflowCardProps) {
workflowLoading={s.workflowLoading}
workflowSteps={s.workflowSteps}
stepActions={s.stepActions}
+ readOnly={s.readOnly}
/>
+
+
+
+
+
+
+
+ );
+}
diff --git a/apps/web/components/settings/workflow-sync-dialog.tsx b/apps/web/components/settings/workflow-sync-dialog.tsx
new file mode 100644
index 0000000000..17cff5957d
--- /dev/null
+++ b/apps/web/components/settings/workflow-sync-dialog.tsx
@@ -0,0 +1,190 @@
+"use client";
+
+import {
+ Dialog,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+} from "@kandev/ui/dialog";
+import { Button } from "@kandev/ui/button";
+import { Input } from "@kandev/ui/input";
+import { Label } from "@kandev/ui/label";
+import { Switch } from "@kandev/ui/switch";
+import type {
+ WorkflowSyncController,
+ WorkflowSyncFormState,
+} from "@/hooks/domains/settings/use-workflow-sync";
+
+const HELP_TEXT =
+ "The directory should contain workflow export files (.yml/.yaml/.json) in the kandev_workflow format — the same format produced by workflow export.";
+
+type RepoUrlFieldProps = {
+ url: string;
+ invalid: boolean;
+ resolved: string;
+ onChange: (value: string) => void;
+};
+
+// RepoUrlField is the primary input: a full GitHub link (optionally with
+// /tree//) that resolves into the stored owner, repo,
+// branch, and directory. The resolved target is echoed underneath so the
+// structured fields stay visible to the user.
+function RepoUrlField({ url, invalid, resolved, onChange }: RepoUrlFieldProps) {
+ return (
+
+
Repository link
+
onChange(e.target.value)}
+ aria-invalid={invalid}
+ />
+ {invalid ? (
+
Not a recognized GitHub repository link.
+ ) : (
+
+ {resolved || "Paste a GitHub link — /tree/… links carry the branch and directory too."}
+
+ )}
+
(key: K, value: WorkflowSyncFormState[K]) => void;
+};
+
+// PollFields is a single compact row: the auto-sync switch and, when on, the
+// interval right beside it. The branch needs no field of its own — it comes
+// from the pasted link (or defaults to main) and is echoed in the resolved
+// summary under the link input.
+function PollFields({ form, update }: FieldsProps) {
+ return (
+
+
+
+ {form.poll_enabled
+ ? "Checks the repository on this interval (minimum 60s)."
+ : "Syncs only run when you press Sync now."}
+
+
+
+
+ GitHub Sync
+
+ Automatically sync workflow definitions from a GitHub repository into this workspace.
+
+
+
+
+ {hasConfig && (
+
+ Remove
+
+ )}
+
+ {saveLabel(sync.saving, hasConfig)}
+
+
+
+
+ );
+}
+
+function saveLabel(saving: boolean, hasConfig: boolean): string {
+ if (saving) return "Saving...";
+ return hasConfig ? "Update" : "Save";
+}
diff --git a/apps/web/components/settings/workflow-sync-section.tsx b/apps/web/components/settings/workflow-sync-section.tsx
new file mode 100644
index 0000000000..2b26d84969
--- /dev/null
+++ b/apps/web/components/settings/workflow-sync-section.tsx
@@ -0,0 +1,65 @@
+"use client";
+
+import { IconBrandGithub } from "@tabler/icons-react";
+import { Button } from "@kandev/ui/button";
+import { Separator } from "@kandev/ui/separator";
+import { WorkflowSyncDialog } from "@/components/settings/workflow-sync-dialog";
+import { WorkflowSyncStatusCard } from "@/components/settings/workflow-sync-status-banner";
+import { useWorkflowSync } from "@/hooks/domains/settings/use-workflow-sync";
+
+// WorkflowSyncButton is the GitHub Sync entry point, rendered alongside the
+// other workflow actions (Export / Import / Add). The dialog open state lives
+// with the caller so button and section can sit in different parts of the
+// layout.
+export function WorkflowSyncButton({ onClick }: { onClick: () => void }) {
+ return (
+
+
+ );
+}
+
+type WorkflowSyncSectionProps = {
+ workspaceId: string;
+ dialogOpen: boolean;
+ onDialogOpenChange: (open: boolean) => void;
+};
+
+// WorkflowSyncSection renders the GitHub-sync state inside the Workflows
+// settings section: the configuration dialog (opened via WorkflowSyncButton
+// in the section's action row) and — once a sync is configured — a compact
+// status card above the workflow list showing what is syncing and how the
+// last attempt went. Unconfigured workspaces render nothing visible.
+export function WorkflowSyncSection({
+ workspaceId,
+ dialogOpen,
+ onDialogOpenChange,
+}: WorkflowSyncSectionProps) {
+ const sync = useWorkflowSync(workspaceId);
+
+ return (
+ <>
+ {sync.config && (
+ // pl-8 matches the workflow list's drag-handle gutter so the card's
+ // left edge lines up with the workflow cards below.
+
+
+ )}
+ {parts.join(" · ")}
;
+}
+
+function WarningsAlert({ warnings }: { warnings: string[] }) {
+ if (warnings.length === 0) return null;
+ return (
+
+
+
+ {warnings.map((warning, index) => (
+ // Warnings are free-form backend sentences with no stable id;
+ // include the index so repeated sentences keep unique keys.
+ {warning}
+ ))}
+
+
+
+ );
+}
+
+type WorkflowSyncStatusCardProps = {
+ config: WorkflowSyncConfig;
+ syncing: boolean;
+ onSyncNow: () => void;
+};
+
+// WorkflowSyncStatusCard is the compact always-visible summary of an active
+// GitHub sync (mirrors the GitHub integration's connection-status card):
+// headline with state icon, repo and branch, a muted metadata line, the last
+// error when failing, and any warnings from the most recent attempt —
+// warnings can be present even when last_ok is true (e.g. one file failed to
+// parse but the rest synced).
+export function WorkflowSyncStatusCard({
+ config,
+ syncing,
+ onSyncNow,
+}: WorkflowSyncStatusCardProps) {
+ const state = syncState(config);
+ return (
+
+
+
+
+ Syncing from{" "}
+
+ {config.repo_owner}/{config.repo_name}
+
+
+ {config.branch}
+
+
+ {syncing ? (
+
+
+
+ {state === "failed" && (
+
{config.last_error || "Sync failed"}
+ )}
+
+
>();
+const setWorkflowSyncConfigMock = vi.fn<(payload: unknown, opts?: unknown) => Promise>();
+const deleteWorkflowSyncConfigMock = vi.fn<(opts?: unknown) => Promise>();
+const forceWorkflowSyncMock = vi.fn<(opts?: unknown) => Promise>();
+
+vi.mock("@/lib/api/domains/workflow-sync-api", () => ({
+ getWorkflowSyncConfig: (opts?: unknown) => getWorkflowSyncConfigMock(opts),
+ setWorkflowSyncConfig: (payload: unknown, opts?: unknown) =>
+ setWorkflowSyncConfigMock(payload, opts),
+ deleteWorkflowSyncConfig: (opts?: unknown) => deleteWorkflowSyncConfigMock(opts),
+ forceWorkflowSync: (opts?: unknown) => forceWorkflowSyncMock(opts),
+}));
+
+import { useWorkflowSync } from "./use-workflow-sync";
+
+function makeConfig(overrides: Partial = {}): WorkflowSyncConfig {
+ return {
+ workspace_id: "ws-1",
+ repo_owner: "kdlbs",
+ repo_name: "kandev",
+ branch: "main",
+ path: ".kandev/workflows",
+ interval_seconds: 300,
+ poll_enabled: true,
+ last_ok: false,
+ created_at: "2026-01-01T00:00:00Z",
+ updated_at: "2026-01-01T00:00:00Z",
+ ...overrides,
+ };
+}
+
+describe("useWorkflowSync", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ getWorkflowSyncConfigMock.mockResolvedValue(null);
+ });
+
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it("loads config and pre-fills the form on mount", async () => {
+ getWorkflowSyncConfigMock.mockResolvedValue(makeConfig({ repo_owner: "acme", branch: "dev" }));
+ const { result } = renderHook(() => useWorkflowSync("ws-1"));
+ await waitFor(() => expect(result.current.loading).toBe(false));
+ expect(result.current.config?.repo_owner).toBe("acme");
+ expect(result.current.form.repo_owner).toBe("acme");
+ expect(result.current.form.branch).toBe("dev");
+ });
+
+ it("falls back to defaults when unconfigured (204/null)", async () => {
+ getWorkflowSyncConfigMock.mockResolvedValue(null);
+ const { result } = renderHook(() => useWorkflowSync("ws-1"));
+ await waitFor(() => expect(result.current.loading).toBe(false));
+ expect(result.current.config).toBeNull();
+ expect(result.current.form.branch).toBe("main");
+ expect(result.current.form.path).toBe(".kandev/workflows");
+ });
+
+ it("handleSave posts the form and updates config from the response", async () => {
+ getWorkflowSyncConfigMock.mockResolvedValue(null);
+ const saved = makeConfig({ repo_owner: "kdlbs", repo_name: "kandev" });
+ setWorkflowSyncConfigMock.mockResolvedValue(saved);
+ const { result } = renderHook(() => useWorkflowSync("ws-1"));
+ await waitFor(() => expect(result.current.loading).toBe(false));
+
+ act(() => result.current.update("repo_owner", "kdlbs"));
+ act(() => result.current.update("repo_name", "kandev"));
+ await act(async () => {
+ await result.current.handleSave();
+ });
+
+ expect(setWorkflowSyncConfigMock).toHaveBeenCalledWith(
+ expect.objectContaining({ repo_owner: "kdlbs", repo_name: "kandev" }),
+ { workspaceId: "ws-1" },
+ );
+ expect(result.current.config?.repo_owner).toBe("kdlbs");
+ });
+
+ it("handleSyncNow updates config from the force-sync response, including failures", async () => {
+ getWorkflowSyncConfigMock.mockResolvedValue(makeConfig({ last_ok: true }));
+ forceWorkflowSyncMock.mockResolvedValue({
+ config: makeConfig({ last_ok: false, last_error: "clone failed" }),
+ error: "clone failed",
+ });
+ const { result } = renderHook(() => useWorkflowSync("ws-1"));
+ await waitFor(() => expect(result.current.loading).toBe(false));
+
+ await act(async () => {
+ await result.current.handleSyncNow();
+ });
+
+ expect(forceWorkflowSyncMock).toHaveBeenCalledWith({ workspaceId: "ws-1" });
+ expect(result.current.config?.last_ok).toBe(false);
+ expect(result.current.config?.last_error).toBe("clone failed");
+ expect(result.current.syncing).toBe(false);
+ });
+
+ it("handleDelete clears config and resets the form when confirmed", async () => {
+ getWorkflowSyncConfigMock.mockResolvedValue(makeConfig());
+ deleteWorkflowSyncConfigMock.mockResolvedValue({ deleted: true });
+ vi.stubGlobal(
+ "confirm",
+ vi.fn(() => true),
+ );
+ const { result } = renderHook(() => useWorkflowSync("ws-1"));
+ await waitFor(() => expect(result.current.loading).toBe(false));
+
+ await act(async () => {
+ await result.current.handleDelete();
+ });
+
+ expect(deleteWorkflowSyncConfigMock).toHaveBeenCalledWith({ workspaceId: "ws-1" });
+ expect(result.current.config).toBeNull();
+ expect(result.current.form.repo_owner).toBe("");
+ });
+
+ it("polls getWorkflowSyncConfig on the background refresh interval", async () => {
+ vi.useFakeTimers();
+ getWorkflowSyncConfigMock.mockResolvedValue(makeConfig({ last_ok: true }));
+ const { result } = renderHook(() => useWorkflowSync("ws-1"));
+ await vi.waitFor(() => expect(result.current.loading).toBe(false));
+ expect(getWorkflowSyncConfigMock).toHaveBeenCalledTimes(1);
+
+ getWorkflowSyncConfigMock.mockResolvedValue(makeConfig({ last_ok: false, last_error: "boom" }));
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(90_000);
+ });
+ expect(getWorkflowSyncConfigMock.mock.calls.length).toBeGreaterThanOrEqual(2);
+ expect(result.current.config?.last_error).toBe("boom");
+ });
+});
diff --git a/apps/web/hooks/domains/settings/use-workflow-sync.ts b/apps/web/hooks/domains/settings/use-workflow-sync.ts
new file mode 100644
index 0000000000..5e5f50c7bd
--- /dev/null
+++ b/apps/web/hooks/domains/settings/use-workflow-sync.ts
@@ -0,0 +1,263 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import { useToast } from "@/components/toast-provider";
+import { useRouter } from "@/lib/routing/client-router";
+import { INTEGRATION_STATUS_REFRESH_MS } from "@/hooks/domains/integrations/use-integration-availability";
+import {
+ getWorkflowSyncConfig,
+ setWorkflowSyncConfig,
+ deleteWorkflowSyncConfig,
+ forceWorkflowSync,
+} from "@/lib/api/domains/workflow-sync-api";
+import type { WorkflowSyncConfig, WorkflowSyncSetConfigRequest } from "@/lib/types/workflow-sync";
+import { buildGitHubRepoUrl, parseGitHubRepoUrl } from "@/lib/utils/github-repo-url";
+
+export type WorkflowSyncFormState = {
+ repo_owner: string;
+ repo_name: string;
+ branch: string;
+ path: string;
+ interval_seconds: number;
+ poll_enabled: boolean;
+};
+
+const DEFAULT_FORM: WorkflowSyncFormState = {
+ repo_owner: "",
+ repo_name: "",
+ branch: "main",
+ path: ".kandev/workflows",
+ interval_seconds: 300,
+ poll_enabled: true,
+};
+
+function configToForm(cfg: WorkflowSyncConfig | null): WorkflowSyncFormState {
+ if (!cfg) return DEFAULT_FORM;
+ return {
+ repo_owner: cfg.repo_owner,
+ repo_name: cfg.repo_name,
+ branch: cfg.branch,
+ path: cfg.path,
+ interval_seconds: cfg.interval_seconds,
+ poll_enabled: cfg.poll_enabled,
+ };
+}
+
+// Background refresh so the status banner picks up new poller results
+// (last_ok / last_error / last_warnings) without requiring a page reload. We
+// re-fetch the config rather than the loud full `load()` to avoid flashing
+// the form while the user is editing it.
+function useWorkflowSyncConfigRefresh(
+ workspaceId: string,
+ setConfig: (cfg: WorkflowSyncConfig | null) => void,
+) {
+ useEffect(() => {
+ let cancelled = false;
+ const id = setInterval(() => {
+ getWorkflowSyncConfig({ workspaceId })
+ .then((cfg) => {
+ if (!cancelled) setConfig(cfg);
+ })
+ .catch(() => {
+ /* transient failures are fine — next tick retries */
+ });
+ }, INTEGRATION_STATUS_REFRESH_MS);
+ return () => {
+ cancelled = true;
+ clearInterval(id);
+ };
+ }, [workspaceId, setConfig]);
+}
+
+// useWorkflowSyncForm owns the editable form state. The repository link is
+// the primary input: owner, repo, and directory only change through it (or a
+// loaded config), while branch and interval remain individually editable via
+// `update`. Branch and directory are only overwritten when the link actually
+// carried them (/tree/... or /blob/... forms), so a bare repo URL keeps the
+// current values.
+function useWorkflowSyncForm() {
+ const [form, setForm] = useState(DEFAULT_FORM);
+ const [url, setUrl] = useState("");
+
+ const update = useCallback(
+ (key: K, value: WorkflowSyncFormState[K]) =>
+ setForm((prev) => ({ ...prev, [key]: value })),
+ [],
+ );
+
+ const setUrlInput = useCallback((value: string) => {
+ setUrl(value);
+ const parsed = parseGitHubRepoUrl(value);
+ if (!parsed) return;
+ setForm((prev) => ({
+ ...prev,
+ repo_owner: parsed.owner,
+ repo_name: parsed.repo,
+ branch: parsed.branch ?? prev.branch,
+ path: parsed.path ?? prev.path,
+ }));
+ }, []);
+
+ // reset re-derives both the structured form and the displayed link from a
+ // loaded/saved config (or clears them when the config was removed).
+ const reset = useCallback((cfg: WorkflowSyncConfig | null) => {
+ setForm(configToForm(cfg));
+ setUrl(
+ cfg
+ ? buildGitHubRepoUrl({
+ owner: cfg.repo_owner,
+ repo: cfg.repo_name,
+ branch: cfg.branch,
+ path: cfg.path,
+ })
+ : "",
+ );
+ }, []);
+
+ const urlInvalid = !!url.trim() && !parseGitHubRepoUrl(url);
+ return { form, url, urlInvalid, update, setUrlInput, reset };
+}
+
+type SyncToast = { description: string; variant?: "success" | "error" | "default" };
+
+function syncOutcomeToast(error: string | undefined, warnings: string[] | undefined): SyncToast {
+ if (error) return { description: `Sync failed: ${error}`, variant: "error" };
+ if (warnings?.length) return { description: "Sync completed with warnings", variant: "default" };
+ return { description: "Workflow sync completed", variant: "success" };
+}
+
+type InitialLoadDeps = {
+ setConfig: (cfg: WorkflowSyncConfig | null) => void;
+ reset: (cfg: WorkflowSyncConfig | null) => void;
+ setLoading: (loading: boolean) => void;
+ toast: ReturnType["toast"];
+};
+
+// useWorkflowSyncInitialLoad fetches the stored config on mount / workspace
+// change. It guards against stale responses: if the hook re-renders for a
+// different workspace while a fetch is in flight, the old workspace's config
+// must not populate the new one's form.
+function useWorkflowSyncInitialLoad(
+ workspaceId: string,
+ { setConfig, reset, setLoading, toast }: InitialLoadDeps,
+) {
+ useEffect(() => {
+ let cancelled = false;
+ setLoading(true);
+ getWorkflowSyncConfig({ workspaceId })
+ .then((cfg) => {
+ if (cancelled) return;
+ setConfig(cfg);
+ reset(cfg);
+ })
+ .catch((err) => {
+ if (cancelled) return;
+ toast({
+ description: `Failed to load workflow sync config: ${String(err)}`,
+ variant: "error",
+ });
+ })
+ .finally(() => {
+ if (!cancelled) setLoading(false);
+ });
+ return () => {
+ cancelled = true;
+ };
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [workspaceId]);
+}
+
+export function useWorkflowSync(workspaceId: string) {
+ const { toast } = useToast();
+ const router = useRouter();
+ const [config, setConfig] = useState(null);
+ const { form, url, urlInvalid, update, setUrlInput, reset } = useWorkflowSyncForm();
+ const [loading, setLoading] = useState(true);
+ const [saving, setSaving] = useState(false);
+ const [syncing, setSyncing] = useState(false);
+
+ useWorkflowSyncInitialLoad(workspaceId, { setConfig, reset, setLoading, toast });
+
+ useWorkflowSyncConfigRefresh(workspaceId, setConfig);
+
+ const handleSave = useCallback(async () => {
+ setSaving(true);
+ try {
+ const payload: WorkflowSyncSetConfigRequest = {
+ repo_owner: form.repo_owner.trim(),
+ repo_name: form.repo_name.trim(),
+ branch: form.branch.trim(),
+ path: form.path.trim(),
+ interval_seconds: form.interval_seconds,
+ poll_enabled: form.poll_enabled,
+ };
+ const saved = await setWorkflowSyncConfig(payload, { workspaceId });
+ setConfig(saved);
+ reset(saved);
+ toast({ description: "Workflow sync configuration saved", variant: "success" });
+ return true;
+ } catch (err) {
+ toast({ description: `Save failed: ${String(err)}`, variant: "error" });
+ return false;
+ } finally {
+ setSaving(false);
+ }
+ }, [workspaceId, form, toast, reset]);
+
+ const handleDelete = useCallback(async () => {
+ if (
+ !confirm("Remove workflow sync configuration? This will not delete already-synced workflows.")
+ ) {
+ return false;
+ }
+ try {
+ await deleteWorkflowSyncConfig({ workspaceId });
+ setConfig(null);
+ reset(null);
+ toast({ description: "Workflow sync removed — synced workflows are editable again" });
+ // Released workflows lose their read-only state server-side; reload the
+ // page data so the cards unlock without a manual refresh.
+ router.refresh();
+ return true;
+ } catch (err) {
+ toast({ description: `Delete failed: ${String(err)}`, variant: "error" });
+ return false;
+ }
+ }, [workspaceId, toast, reset, router]);
+
+ const handleSyncNow = useCallback(async () => {
+ setSyncing(true);
+ try {
+ const res = await forceWorkflowSync({ workspaceId });
+ setConfig(res.config);
+ reset(res.config);
+ toast(syncOutcomeToast(res.error, res.result?.warnings));
+ // Reload the workflow list when the sync actually changed something so
+ // created/updated/deleted workflows show up without a manual refresh.
+ if (res.result && !res.result.unchanged) {
+ router.refresh();
+ }
+ } catch (err) {
+ toast({ description: `Sync failed: ${String(err)}`, variant: "error" });
+ } finally {
+ setSyncing(false);
+ }
+ }, [workspaceId, toast, reset, router]);
+
+ return {
+ config,
+ form,
+ url,
+ urlInvalid,
+ loading,
+ saving,
+ syncing,
+ update,
+ setUrlInput,
+ handleSave,
+ handleDelete,
+ handleSyncNow,
+ };
+}
+
+export type WorkflowSyncController = ReturnType;
diff --git a/apps/web/lib/api/domains/workflow-sync-api.test.ts b/apps/web/lib/api/domains/workflow-sync-api.test.ts
new file mode 100644
index 0000000000..9e4a700a60
--- /dev/null
+++ b/apps/web/lib/api/domains/workflow-sync-api.test.ts
@@ -0,0 +1,112 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+ getWorkflowSyncConfig,
+ setWorkflowSyncConfig,
+ deleteWorkflowSyncConfig,
+ forceWorkflowSync,
+} from "./workflow-sync-api";
+
+const CONFIG_PATH = "/api/v1/workflow-sync/config";
+const WS_PARAM = "workspace_id=ws-1";
+
+const originalFetch = global.fetch;
+
+function mockResponse(data: unknown, status = 200) {
+ return new Response(data === undefined ? null : JSON.stringify(data), {
+ status,
+ headers: { "Content-Type": "application/json" },
+ });
+}
+
+function makeConfigBody(overrides: Record = {}) {
+ return {
+ workspace_id: "ws-1",
+ repo_owner: "kdlbs",
+ repo_name: "kandev",
+ branch: "main",
+ path: ".kandev/workflows",
+ interval_seconds: 300,
+ last_ok: true,
+ created_at: "2026-01-01T00:00:00Z",
+ updated_at: "2026-01-01T00:00:00Z",
+ ...overrides,
+ };
+}
+
+describe("workflow-sync-api", () => {
+ let fetchSpy: ReturnType;
+
+ beforeEach(() => {
+ fetchSpy = vi.fn();
+ global.fetch = fetchSpy as unknown as typeof fetch;
+ });
+
+ afterEach(() => {
+ global.fetch = originalFetch;
+ vi.restoreAllMocks();
+ });
+
+ it("getWorkflowSyncConfig calls /api/v1/workflow-sync/config with workspace_id", async () => {
+ fetchSpy.mockResolvedValueOnce(mockResponse(makeConfigBody()));
+ const config = await getWorkflowSyncConfig({ workspaceId: "ws-1" });
+ expect(fetchSpy).toHaveBeenCalledTimes(1);
+ const url = fetchSpy.mock.calls[0]![0] as string;
+ expect(url).toContain(CONFIG_PATH);
+ expect(url).toContain(WS_PARAM);
+ expect(config?.repo_owner).toBe("kdlbs");
+ });
+
+ it("getWorkflowSyncConfig returns null on 204 (not configured)", async () => {
+ fetchSpy.mockResolvedValueOnce(mockResponse(undefined, 204));
+ const config = await getWorkflowSyncConfig({ workspaceId: "ws-1" });
+ expect(config).toBeNull();
+ });
+
+ it("setWorkflowSyncConfig POSTs the payload", async () => {
+ fetchSpy.mockResolvedValueOnce(mockResponse(makeConfigBody({ last_ok: false })));
+ const saved = await setWorkflowSyncConfig(
+ { repo_owner: "kdlbs", repo_name: "kandev" },
+ { workspaceId: "ws-1" },
+ );
+ const url = fetchSpy.mock.calls[0]![0] as string;
+ const init = fetchSpy.mock.calls[0]![1] as RequestInit;
+ expect(url).toContain(CONFIG_PATH);
+ expect(url).toContain(WS_PARAM);
+ expect(init.method).toBe("POST");
+ expect(JSON.parse(init.body as string)).toEqual({ repo_owner: "kdlbs", repo_name: "kandev" });
+ expect(saved.repo_name).toBe("kandev");
+ });
+
+ it("deleteWorkflowSyncConfig issues DELETE", async () => {
+ fetchSpy.mockResolvedValueOnce(mockResponse({ deleted: true }));
+ const result = await deleteWorkflowSyncConfig({ workspaceId: "ws-1" });
+ const url = String(fetchSpy.mock.calls[0]![0]);
+ expect(url).toContain(CONFIG_PATH);
+ expect(url).toContain(WS_PARAM);
+ const init = fetchSpy.mock.calls[0]![1] as RequestInit;
+ expect(init.method).toBe("DELETE");
+ expect(result.deleted).toBe(true);
+ });
+
+ it("forceWorkflowSync POSTs with no body and returns config + result", async () => {
+ fetchSpy.mockResolvedValueOnce(
+ mockResponse({
+ config: makeConfigBody(),
+ result: { created: ["a"], updated: [], deleted: [], warnings: [], unchanged: false },
+ }),
+ );
+ const res = await forceWorkflowSync({ workspaceId: "ws-1" });
+ const url = fetchSpy.mock.calls[0]![0] as string;
+ const init = fetchSpy.mock.calls[0]![1] as RequestInit;
+ expect(url).toContain("/api/v1/workflow-sync/sync");
+ expect(url).toContain(WS_PARAM);
+ expect(init.method).toBe("POST");
+ expect(res.config.repo_owner).toBe("kdlbs");
+ expect(res.result?.created).toEqual(["a"]);
+ });
+
+ it("forceWorkflowSync rejects with the parsed error body on 404 (not configured)", async () => {
+ fetchSpy.mockResolvedValueOnce(mockResponse({ error: "not configured" }, 404));
+ await expect(forceWorkflowSync({ workspaceId: "ws-1" })).rejects.toThrow("not configured");
+ });
+});
diff --git a/apps/web/lib/api/domains/workflow-sync-api.ts b/apps/web/lib/api/domains/workflow-sync-api.ts
new file mode 100644
index 0000000000..e85543b291
--- /dev/null
+++ b/apps/web/lib/api/domains/workflow-sync-api.ts
@@ -0,0 +1,63 @@
+import { fetchJson, type ApiRequestOptions } from "../client";
+import type {
+ WorkflowSyncConfig,
+ WorkflowSyncForceSyncResponse,
+ WorkflowSyncSetConfigRequest,
+} from "@/lib/types/workflow-sync";
+
+type WorkspaceApiOptions = ApiRequestOptions & { workspaceId?: string };
+
+function withWorkspace(path: string, options?: WorkspaceApiOptions): string {
+ if (!options?.workspaceId) return path;
+ const separator = path.includes("?") ? "&" : "?";
+ return `${path}${separator}workspace_id=${encodeURIComponent(options.workspaceId)}`;
+}
+
+function requestOptions(options?: WorkspaceApiOptions): ApiRequestOptions | undefined {
+ if (!options) return undefined;
+ const { workspaceId: _workspaceId, ...rest } = options;
+ return rest;
+}
+
+// getWorkflowSyncConfig returns null when the backend responds 204 (no
+// config yet for this workspace). fetchJson already maps 204 → undefined; we
+// narrow it to null for callers.
+export async function getWorkflowSyncConfig(
+ options?: WorkspaceApiOptions,
+): Promise {
+ const res = await fetchJson(
+ withWorkspace(`/api/v1/workflow-sync/config`, options),
+ requestOptions(options),
+ );
+ return res ?? null;
+}
+
+export async function setWorkflowSyncConfig(
+ payload: WorkflowSyncSetConfigRequest,
+ options?: WorkspaceApiOptions,
+) {
+ return fetchJson(withWorkspace(`/api/v1/workflow-sync/config`, options), {
+ ...requestOptions(options),
+ init: { ...(options?.init ?? {}), method: "POST", body: JSON.stringify(payload) },
+ });
+}
+
+export async function deleteWorkflowSyncConfig(options?: WorkspaceApiOptions) {
+ return fetchJson<{ deleted: boolean }>(withWorkspace(`/api/v1/workflow-sync/config`, options), {
+ ...requestOptions(options),
+ init: { ...(options?.init ?? {}), method: "DELETE" },
+ });
+}
+
+// forceWorkflowSync triggers an immediate sync. Rejects with an ApiError
+// (404) when the workspace has no config; a failed sync attempt still
+// resolves 200 with `error` set and `config.last_ok === false`.
+export async function forceWorkflowSync(options?: WorkspaceApiOptions) {
+ return fetchJson(
+ withWorkspace(`/api/v1/workflow-sync/sync`, options),
+ {
+ ...requestOptions(options),
+ init: { ...(options?.init ?? {}), method: "POST" },
+ },
+ );
+}
diff --git a/apps/web/lib/api/index.ts b/apps/web/lib/api/index.ts
index 13f5048200..022e41a39b 100644
--- a/apps/web/lib/api/index.ts
+++ b/apps/web/lib/api/index.ts
@@ -8,5 +8,6 @@ export * from "./domains/workspace-api";
export * from "./domains/settings-api";
export * from "./domains/process-api";
export * from "./domains/workflow-api";
+export * from "./domains/workflow-sync-api";
export * from "./domains/github-api";
export * from "./domains/runtime-flags-api";
diff --git a/apps/web/lib/types/http.ts b/apps/web/lib/types/http.ts
index 93f30d2771..78db803e4c 100644
--- a/apps/web/lib/types/http.ts
+++ b/apps/web/lib/types/http.ts
@@ -167,6 +167,14 @@ export type Workflow = {
* shell (kanban board, office task pane, etc). Backend does NOT branch on it.
*/
style?: "kanban" | "office" | "custom";
+ /**
+ * Workflow provenance. `"github"` marks workflows synced from a configured
+ * GitHub repo (see workflow sync); omitted/`"manual"` for user-created
+ * workflows. `source_path` is the repo-relative file the workflow was
+ * synced from and is omitted for manual workflows.
+ */
+ source?: string;
+ source_path?: string;
created_at: string;
updated_at: string;
};
diff --git a/apps/web/lib/types/workflow-sync.ts b/apps/web/lib/types/workflow-sync.ts
new file mode 100644
index 0000000000..d41af7812e
--- /dev/null
+++ b/apps/web/lib/types/workflow-sync.ts
@@ -0,0 +1,59 @@
+/**
+ * Per-workspace workflow sync configuration: a GitHub repo + branch +
+ * directory containing workflow export files (`.yml`/`.yaml`/`.json` in the
+ * `kandev_workflow` format). The backend polls the directory on
+ * `interval_seconds` cadence and syncs workflows; `last_*` fields report the
+ * outcome of the most recent sync attempt (poller or forced).
+ */
+export interface WorkflowSyncConfig {
+ workspace_id: string;
+ repo_owner: string;
+ repo_name: string;
+ branch: string;
+ path: string;
+ interval_seconds: number;
+ /** When false, the workspace only syncs via "Sync now". */
+ poll_enabled: boolean;
+ /** RFC3339 timestamp; absent until the first sync attempt. */
+ last_synced_at?: string;
+ last_ok: boolean;
+ last_error?: string;
+ last_warnings?: string[];
+ created_at: string;
+ updated_at: string;
+}
+
+/**
+ * Payload for creating or updating a workspace's workflow sync config.
+ * `branch`, `path`, and `interval_seconds` fall back to server-side defaults
+ * (`main`, `.kandev/workflows`, 300s / min 60s) when omitted.
+ */
+export interface WorkflowSyncSetConfigRequest {
+ repo_owner: string;
+ repo_name: string;
+ branch?: string;
+ path?: string;
+ interval_seconds?: number;
+ /** Defaults to true server-side when omitted. */
+ poll_enabled?: boolean;
+}
+
+/** Outcome of a single sync run (poller or forced). */
+export interface WorkflowSyncResult {
+ created: string[];
+ updated: string[];
+ deleted: string[];
+ warnings: string[];
+ unchanged: boolean;
+}
+
+/**
+ * Response from a forced sync. A failed sync still responds 200 with `error`
+ * set and `config.last_ok === false` — the request itself only rejects (404)
+ * when no config exists for the workspace.
+ */
+export interface WorkflowSyncForceSyncResponse {
+ config: WorkflowSyncConfig;
+ result?: WorkflowSyncResult;
+ error?: string;
+}
diff --git a/apps/web/lib/utils/github-repo-url.test.ts b/apps/web/lib/utils/github-repo-url.test.ts
new file mode 100644
index 0000000000..d3e308fb81
--- /dev/null
+++ b/apps/web/lib/utils/github-repo-url.test.ts
@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+import { buildGitHubRepoUrl, parseGitHubRepoUrl } from "./github-repo-url";
+
+describe("parseGitHubRepoUrl", () => {
+ it("parses a plain repository URL", () => {
+ expect(parseGitHubRepoUrl("https://github.com/jcfs/kandev-workflows-test")).toEqual({
+ owner: "jcfs",
+ repo: "kandev-workflows-test",
+ });
+ });
+
+ it("tolerates trailing slash, .git suffix, www, and missing scheme", () => {
+ expect(parseGitHubRepoUrl("https://github.com/jcfs/repo/")).toEqual({
+ owner: "jcfs",
+ repo: "repo",
+ });
+ expect(parseGitHubRepoUrl("https://www.github.com/jcfs/repo.git")).toEqual({
+ owner: "jcfs",
+ repo: "repo",
+ });
+ expect(parseGitHubRepoUrl("github.com/jcfs/repo")).toEqual({ owner: "jcfs", repo: "repo" });
+ });
+
+ it("parses an SSH remote", () => {
+ expect(parseGitHubRepoUrl("git@github.com:jcfs/repo.git")).toEqual({
+ owner: "jcfs",
+ repo: "repo",
+ });
+ });
+
+ it("extracts branch and directory from a /tree/ link", () => {
+ expect(
+ parseGitHubRepoUrl(
+ "https://github.com/jcfs/kandev-workflows-test/tree/main/.kandev/workflows",
+ ),
+ ).toEqual({
+ owner: "jcfs",
+ repo: "kandev-workflows-test",
+ branch: "main",
+ path: ".kandev/workflows",
+ });
+ });
+
+ it("extracts branch without path from a branch-root /tree/ link", () => {
+ expect(parseGitHubRepoUrl("https://github.com/jcfs/repo/tree/develop")).toEqual({
+ owner: "jcfs",
+ repo: "repo",
+ branch: "develop",
+ });
+ });
+
+ it("resolves a /blob/ file link to the file's directory", () => {
+ expect(
+ parseGitHubRepoUrl("https://github.com/jcfs/repo/blob/main/.kandev/workflows/dev.yml"),
+ ).toEqual({
+ owner: "jcfs",
+ repo: "repo",
+ branch: "main",
+ path: ".kandev/workflows",
+ });
+ });
+
+ it("ignores unknown path markers beyond owner/repo", () => {
+ expect(parseGitHubRepoUrl("https://github.com/jcfs/repo/pulls")).toEqual({
+ owner: "jcfs",
+ repo: "repo",
+ });
+ });
+
+ it("rejects non-GitHub and malformed input", () => {
+ expect(parseGitHubRepoUrl("https://gitlab.com/jcfs/repo")).toBeNull();
+ expect(parseGitHubRepoUrl("https://github.com/only-owner")).toBeNull();
+ expect(parseGitHubRepoUrl("not a url at all :::")).toBeNull();
+ expect(parseGitHubRepoUrl("")).toBeNull();
+ });
+
+ it("returns null instead of throwing on malformed percent escapes", () => {
+ expect(parseGitHubRepoUrl("https://github.com/org/repo/tree/main/%")).toBeNull();
+ expect(parseGitHubRepoUrl("https://github.com/org/repo/tree/main/%zz")).toBeNull();
+ });
+
+ it("decodes percent-encoded path segments", () => {
+ expect(parseGitHubRepoUrl("https://github.com/jcfs/repo/tree/main/my%20flows")).toEqual({
+ owner: "jcfs",
+ repo: "repo",
+ branch: "main",
+ path: "my flows",
+ });
+ });
+});
+
+describe("buildGitHubRepoUrl", () => {
+ it("renders owner/repo/branch/path back into a tree link", () => {
+ const url = buildGitHubRepoUrl({
+ owner: "jcfs",
+ repo: "kandev-workflows-test",
+ branch: "main",
+ path: ".kandev/workflows",
+ });
+ expect(url).toBe("https://github.com/jcfs/kandev-workflows-test/tree/main/.kandev/workflows");
+ });
+
+ it("round-trips through parseGitHubRepoUrl", () => {
+ const parts = { owner: "jcfs", repo: "repo", branch: "dev", path: "my flows/sub" };
+ expect(parseGitHubRepoUrl(buildGitHubRepoUrl(parts))).toEqual(parts);
+ });
+
+ it("omits the tree suffix without a branch and the path when empty", () => {
+ expect(buildGitHubRepoUrl({ owner: "jcfs", repo: "repo" })).toBe(
+ "https://github.com/jcfs/repo",
+ );
+ expect(buildGitHubRepoUrl({ owner: "jcfs", repo: "repo", branch: "main" })).toBe(
+ "https://github.com/jcfs/repo/tree/main",
+ );
+ });
+});
diff --git a/apps/web/lib/utils/github-repo-url.ts b/apps/web/lib/utils/github-repo-url.ts
new file mode 100644
index 0000000000..b6022753e9
--- /dev/null
+++ b/apps/web/lib/utils/github-repo-url.ts
@@ -0,0 +1,64 @@
+export type ParsedGitHubRepoUrl = {
+ owner: string;
+ repo: string;
+ branch?: string;
+ path?: string;
+};
+
+const GITHUB_HOST = "github.com";
+const SSH_URL_RE = /^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/;
+
+// parseGitHubRepoUrl extracts owner/repo (and branch + directory for
+// /tree/... and /blob/... links) from a pasted GitHub URL. Returns null when
+// the input isn't a recognizable GitHub repository link.
+//
+// Branch names containing "/" cannot be told apart from the leading path
+// segments without asking the GitHub API, so single-segment branch names are
+// assumed. A /blob/ link to a file resolves to the file's directory.
+export function parseGitHubRepoUrl(input: string): ParsedGitHubRepoUrl | null {
+ const raw = input.trim();
+ if (!raw) return null;
+
+ const ssh = raw.match(SSH_URL_RE);
+ if (ssh) return { owner: ssh[1], repo: ssh[2] };
+
+ let url: URL;
+ try {
+ url = new URL(raw.includes("://") ? raw : `https://${raw}`);
+ } catch {
+ return null;
+ }
+ if (url.hostname !== GITHUB_HOST && url.hostname !== `www.${GITHUB_HOST}`) return null;
+
+ let segments: string[];
+ try {
+ segments = url.pathname.split("/").filter(Boolean).map(decodeURIComponent);
+ } catch {
+ // Malformed percent escapes (e.g. a trailing "%") must read as "not a
+ // recognized link", not crash the dialog on every keystroke.
+ return null;
+ }
+ if (segments.length < 2) return null;
+ const [owner, rawRepo, ...rest] = segments;
+ const repo = rawRepo.replace(/\.git$/, "");
+ if (!owner || !repo) return null;
+ return { owner, repo, ...parseBranchAndPath(rest) };
+}
+
+// buildGitHubRepoUrl renders a stored config back into a canonical GitHub
+// link (the inverse of parseGitHubRepoUrl) so the settings form can show one
+// URL instead of separate owner/repo/path fields.
+export function buildGitHubRepoUrl(parts: ParsedGitHubRepoUrl): string {
+ const base = `https://github.com/${parts.owner}/${parts.repo}`;
+ if (!parts.branch) return base;
+ const path = parts.path ? `/${parts.path.split("/").map(encodeURIComponent).join("/")}` : "";
+ return `${base}/tree/${encodeURIComponent(parts.branch)}${path}`;
+}
+
+function parseBranchAndPath(segments: string[]): Pick {
+ const [marker, branch, ...rest] = segments;
+ if ((marker !== "tree" && marker !== "blob") || !branch) return {};
+ const pathSegments = marker === "blob" ? rest.slice(0, -1) : rest;
+ if (pathSegments.length === 0) return { branch };
+ return { branch, path: pathSegments.join("/") };
+}
diff --git a/docs/public/index.md b/docs/public/index.md
index 7953f4a8fb..03d2212ba3 100644
--- a/docs/public/index.md
+++ b/docs/public/index.md
@@ -7,6 +7,7 @@ This page expands the short feature list in the README without turning the READM
- **Parallel task execution:** run and review multiple agent tasks at once.
- **Kanban and pipeline workflows:** define workflow steps, prompts, automations, and agent handoffs per step.
- **Workflow import/export:** export one workflow or every workflow in a workspace as portable YAML, then import it into another workspace or Kandev install. See [workflow-import-export.md](workflow-import-export.md).
+- **Workflow sync from GitHub:** keep a workspace's workflows in sync with definition files in a GitHub repo — Kandev polls the repo on an interval, with a force-sync option and warnings when a change can't be applied. See [workflow-sync.md](workflow-sync.md).
- **Subtasks:** split work into child tasks that inherit the parent task's workspace, workflow, agent profile, executor, and repositories by default.
- **Multi-repository tasks:** attach several repositories to one task. Each repository gets its own worktree and is grouped separately in changes, review, and PR surfaces.
- **Multi-branch tasks:** attach multiple branches from the same repository to one task when the work needs to produce several PRs.
diff --git a/docs/public/workflow-import-export.md b/docs/public/workflow-import-export.md
index 9ae0ac6017..76d3c1e0c2 100644
--- a/docs/public/workflow-import-export.md
+++ b/docs/public/workflow-import-export.md
@@ -14,6 +14,10 @@ Everything below is derived from the source of truth:
> **Looking for the built-in workflows instead?** See [Workflows](workflow-tips.md)
> for the default templates and when to use each.
+> **Want workflows managed from a git repo?** The same file format powers
+> [workflow sync from GitHub](workflow-sync.md), which polls a configured repo
+> and keeps workspace workflows up to date automatically.
+
---
## How import/export is exposed
diff --git a/docs/public/workflow-sync.md b/docs/public/workflow-sync.md
new file mode 100644
index 0000000000..f61b72e17b
--- /dev/null
+++ b/docs/public/workflow-sync.md
@@ -0,0 +1,115 @@
+# 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 → \ → 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//` 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.