GitHub Sync

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

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

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

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

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

  • 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

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.