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": "...",
    "externalContext": {
        "get_process_initiator_user": {
            "id": 1,
            "username": "bob",
            "email": "bob@example.com",
            "display_name": "Bob Example",
        },
    },
    "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.

  • connectorProxy.url: connector proxy base URL used for service calls. It takes precedence over the legacy top-level connectorProxyUrl when present.

  • connectorProxy["v1/commands"]: optional embedded list of ordinary and rewritten Service Task operators. These supplement commands discovered from the connector proxy; an embedded command takes precedence when it has the same id as a remote command.

  • externalContext: optional mock values for Arena external-context helpers while running BPMN in Ed. When get_process_initiator_user is present, its dictionary completely replaces Ed’s built-in initiator user for that run. Omit it to keep the built-in mock.

  • 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.

Custom Service Task Operators

Use connectorProxy["v1/commands"] to define the Service Task operators shown in Ed. A command can rewrite to an existing connector proxy command, which provides a concise authoring interface without deploying another connector proxy:

import json

config = {
    "connectorProxy": {
        "v1/commands": json.loads("""
[
  {
    "id": "faux/GetPostComments",
    "parameters": [
      {"id": "post_id", "type": "int", "required": true}
    ],
    "alias_for": {
      "http/GetRequest": {
        "url": "https://jsonplaceholder.typicode.com/posts/{post_id}/comments"
      }
    }
  },
  {
    "id": "faux/GetPostComments2",
    "parameters": [
      {"id": "post_id", "type": "int", "required": true}
    ],
    "alias_for": {
      "http/GetRequest": {
        "url": "https://jsonplaceholder.typicode.com/comments",
        "params": {
          "postId": {"$param": "post_id"}
        }
      }
    }
  }
]
"""),
    },
}

Using json.loads keeps the command definitions as valid static JSON, separate from the executable Python in ed:config.bpmn. The first command produces a URL such as https://jsonplaceholder.typicode.com/posts/1/comments. The second uses the alternate https://jsonplaceholder.typicode.com/comments?postId=1 request shape by passing the resolved value through the underlying request’s params object. Use headers in the same way when the target API expects an HTTP header instead of a query parameter.

SpiffWorkflow evaluates each Service Task’s post_id expression before the rewrite. Within alias_for:

  • {post_id} interpolates a resolved scalar into a string;

  • {"$param": "post_id"} inserts the resolved value without changing its type; and

  • constants, nested objects, and arrays are copied into the target request.

Only parameters constructed under alias_for are sent to the target command. Rewrites cannot read other workflow variables, target ed/* commands, or target another rewritten command.

Commands in connectorProxy["v1/commands"] are merged with commands returned by the connector proxy’s /v1/commands endpoint. Commands are matched by id, and the embedded definition wins when both lists contain the same id. This lets a process add a few concise custom operators while retaining the proxy’s ordinary commands. An explicitly empty embedded list still allows remote operator discovery; set connectorProxy.url to null when only embedded and Ed-local commands should be available.

The remote command catalog can also define alias_for mappings. Remote and embedded mappings use the same validation, interpolation, and execution behavior after the catalogs are merged. A rewrite target does not need its own dropdown entry.

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.