# Version Control (/docs/plugins/version-control)







The version control plugin syncs flows to Git repositories (GitHub, GitLab, Bitbucket). Push flow definitions as `.flow.ts` files, pull changes back, create PRs on publish, and keep flows in sync via webhooks.

## Installation [#installation]

<Tabs items="['pnpm', 'npm', 'yarn', 'bun']">
  <Tab value="pnpm">
    ```bash
    pnpm add @flowlib/version-control
    ```
  </Tab>

  <Tab value="npm">
    ```bash
    npm install @flowlib/version-control
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @flowlib/version-control
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @flowlib/version-control
    ```
  </Tab>
</Tabs>

## Setup [#setup]

The plugin requires a Git provider and a target repository:

```ts title="flowlib.config.ts"
import { versionControl } from '@flowlib/version-control';
import { githubProvider } from '@flowlib/version-control/providers/github';

export const flowlibConfig = defineConfig({
  // ...
  plugins: [
    versionControl({
      provider: githubProvider({ token: process.env.GITHUB_TOKEN }),
      repo: 'my-org/my-flows',
    }),
  ],
});
```

After adding the plugin, regenerate and apply the schema:

```bash
npx flowlib-cli generate
npx flowlib-cli migrate --push
```

### Options [#options]

| Option          | Type              | Required | Default            | Description                                                                   |
| --------------- | ----------------- | -------- | ------------------ | ----------------------------------------------------------------------------- |
| `provider`      | `GitProvider`     | Yes      | —                  | Git hosting provider (e.g. `githubProvider()`)                                |
| `repo`          | `string`          | Yes      | —                  | Target repository in `owner/name` format                                      |
| `defaultBranch` | `string`          | No       | `'main'`           | Default branch for push/pull operations                                       |
| `path`          | `string`          | No       | `'/'`              | Directory in the repository for flow files                                    |
| `mode`          | `VcSyncMode`      | No       | `'pr-per-publish'` | `'pr-per-publish'` creates a PR per publish, `'direct-push'` commits directly |
| `syncDirection` | `VcSyncDirection` | No       | `'push'`           | `'push'`, `'pull'`, or `'bidirectional'`                                      |
| `webhookSecret` | `string`          | No       | —                  | Secret for verifying Git webhook signatures                                   |

## How it works [#how-it-works]

Once configured, you can sync individual flows or all flows at once:

* **Push** — export a flow from Flowlib to the Git repository
* **Pull** — import a flow from the Git repository into Flowlib
* **Publish** — in `pr-per-publish` mode, creates a pull request for review
* **Force push/pull** — resolve conflicts by choosing one side as the source of truth
* **Webhook** — automatically sync when the repository is updated

## API endpoints [#api-endpoints]

| Endpoint                                               | Method | Description                                      |
| ------------------------------------------------------ | ------ | ------------------------------------------------ |
| `/plugins/version-control/vc/flows`                    | GET    | List all synced flows                            |
| `/plugins/version-control/vc/flows/:flowId/configure`  | POST   | Configure sync for a flow                        |
| `/plugins/version-control/vc/flows/:flowId/status`     | GET    | Get sync status for a flow                       |
| `/plugins/version-control/vc/flows/:flowId/disconnect` | DELETE | Disconnect a flow from sync                      |
| `/plugins/version-control/vc/flows/:flowId/push`       | POST   | Push flow to remote                              |
| `/plugins/version-control/vc/flows/:flowId/pull`       | POST   | Pull flow from remote                            |
| `/plugins/version-control/vc/flows/:flowId/publish`    | POST   | Publish flow (creates PR in pr-per-publish mode) |
| `/plugins/version-control/vc/flows/:flowId/history`    | GET    | Get sync history for a flow                      |
| `/plugins/version-control/vc/push-all`                 | POST   | Push all synced flows                            |
| `/plugins/version-control/vc/pull-all`                 | POST   | Pull all synced flows                            |
| `/plugins/version-control/vc/webhook`                  | POST   | Webhook receiver for Git events (public)         |