---
title: "GitHub Sync — Visual Design Studio 0.1 documentation"
description: "Ed can sync process model files with GitHub when the workspace is configured for it. This allows process authors to keep BPMN diagrams, form files, DMN tables, and supporting files in source control."
source_url: https://spiff.works/docs/ed/github_sync.html
---

☰ Menu

# GitHub Sync[](#github-sync "Link to this heading")

Ed can sync process model files with GitHub when the workspace is configured for it.
This allows process authors to keep BPMN diagrams, form files, DMN tables, and supporting files in source control.

## Configuration Overview[](#configuration-overview "Link to this heading")

The public Ed configuration pattern uses a BPMN file named:

- `ed:config.bpmn`

Recommended placement:

- create a workspace named `Configuration`;
- store `ed:config.bpmn` in that workspace;
- keep it separate from ordinary process model workspaces.

Keeping configuration separate reduces accidental edits and helps prevent configuration from being synced with process model files.

## Required Script Variables[](#required-script-variables "Link to this heading")

The configuration process contains a Script Task that defines:

- `github_token`
- `config`

`github_token` is a GitHub Personal Access Token for the repositories Ed should sync with.
Treat it as a secret.
Do not commit it to a public repository.

`config` describes available repositories, branches, and connector proxy settings.

## Single Repository Example[](#single-repository-example "Link to this heading")

```
github_token = "..."

config = {
    "connectorProxyUrl": "...",
    "connectorProxyApiKey": "...",
    "sync": {
        "github": {
            "repos": [
                {
                    "owner": "your_name_or_company",
                    "repo": "your_process_model_repo",
                    "ref": "main",
                    "token": github_token,
                }
            ]
        }
    },
}
```

`connectorProxyApiKey` is optional.
Only set it when your connector proxy requires an API key.

## Multiple Repository Example[](#multiple-repository-example "Link to this heading")

```
github_token = "..."

config = {
    "sync": {
        "github": {
            "repos": [
                {
                    "owner": "your_org",
                    "repo": "process_models_a",
                    "ref": "main",
                    "token": github_token,
                },
                {
                    "owner": "your_org",
                    "repo": "process_models_b",
                    "ref": "main",
                    "token": github_token,
                },
            ]
        }
    },
}
```

## Field Reference[](#field-reference "Link to this heading")

- `connectorProxyUrl`: connector proxy base URL used for service calls.
- `connectorProxyApiKey`: optional API key sent to the connector proxy.
- `owner`: GitHub user or organization.
- `repo`: GitHub repository containing process model files.
- `ref`: branch or ref to sync against.
- `token`: token Ed uses to access the repository.

## Sync Checklist[](#sync-checklist "Link to this heading")

Before relying on sync:

- Confirm the token has access to the intended repository.
- Confirm the selected branch is correct.
- Confirm process model files are not mixed with `ed:config.bpmn`.
- Run the diagram after pulling changes from GitHub.
- Review diffs before pushing changes from Ed.

For connector proxy setup, see Spiff Arena’s [Configure a Connector Proxy](https://spiff.works/docs/spiff-arena/how_to_guides/deployment/configure_a_connector_proxy.html).