Deploy a workflow connector
How a workflow connector is deployed: the connector standard, the checks on submission, Stacksync's review, the build, the statuses, the emails and how to ship updates.
stacksync workflow-connector deploy turns the connector you tested with run into a connector that Stacksync hosts. You run no servers: Stacksync builds, runs and scales it.
The process
Check the connector yourself
Run the same standard check that Stacksync runs, and fix every problem it lists:
.venv/bin/python -m stacksync_cdk.connector_checksThen test every module with stacksync workflow-connector run against a real account.
Submit it
stacksync workflow-connector deployThe CLI packages the source into .stacksync_deployment/source.zip and uploads it. Your virtual environment, Git data, build folders, recorded requests (.logs/) and .env files are left out. List dependencies in requirements.txt: Stacksync installs them.
Stacksync checks it
Before anything is built, Stacksync checks the package, the settings, the connector standard and the icon. If something fails, deploy prints the reason and nothing is submitted. See Why a deployment is refused.
A Stacksync reviewer approves it
The deployment waits for a Stacksync reviewer, who reads the source and sees which modules are new or changed. This can take hours. deploy doesn't wait:
Deployment 3f2a9c0e8b7d4e1fa6c5b4d3e2f1a0b9 submitted for review.
It is built and deployed once a Stacksync reviewer approves it. You will get an email when it ends.Reviewers check what the automatic checks can't: one module per operation, real fields instead of free-text bodies, correct errors, accurate context, no credentials or customer data in the code. If the connector is not approved, you get an email with the reviewer's note. Fix it and deploy again.
Stacksync builds and registers it
After approval, Stacksync builds the connector with Python 3.11, installs requirements.txt and serves the app defined in your main.py. It then reads /app-config and adds the modules to the workflow builder. The modules it finds must be exactly the ones that were reviewed. If any step fails, the version that was live before stays live.
It is live
You get the email Connector <app_type> is live. The modules are available in the workflow builder of every Stacksync workspace. Users add a step, choose your connector, connect their account and run it.
Follow a deployment
stacksync workflow-connector deploy-status <deployment-id>| Status | Meaning |
|---|---|
Waiting for approval by Stacksync... | Waiting for a reviewer. |
Building... | Approved and being built. |
Deploying... | Being started. |
Registering modules... | Its modules are being added to the workflow builder. |
Live | Available in workflows. |
Failed | Not completed. Contact Stacksync support with the deployment id. The command exits with code 1. |
Only the person who submitted the deployment can see its status. Only one deployment of a connector can wait for review or be in progress at a time.
You also get an email when the deployment ends:
| Meaning | |
|---|---|
| Connector <app_type> is live | Approved and deployed. |
| Connector <app_type> was not approved | Rejected, with the reviewer's note. |
| Connector <app_type> could not be deployed | Failed. Contact support with the deployment id. |
The connector standard
The connector standard is the set of rules every deployed connector meets. It is checked from your files only: your code is not run.
.venv/bin/python -m stacksync_cdk.connector_checksstacksync.yml: app_settings.app_icon_svg_url must start with https://
context.md: the "## Objects" section is missing
modules/create_records/v1/context.md: still has TODO items; fill them in
3 problem(s) to fix before this connector can be deployed.It exits with 0 and prints The connector meets the Stacksync standard. when there is nothing to fix. Pass a folder to check another connector: python -m stacksync_cdk.connector_checks path/to/connector. The same problems are logged as warnings when the connector starts.
| Rule | Problem it reports |
|---|---|
stacksync.yml exists and is valid YAML with app_settings | stacksync.yml: the file is missing, the file is not valid YAML, app_settings is missing |
Every app_settings field is filled in: app_type, app_name, app_type_display, app_description, app_icon_svg_url, connection_app_type | app_settings.<field> is required |
| No value is left from the template | app_settings.<field> still has the template value |
The icon is an https:// link | app_settings.app_icon_svg_url must start with https:// |
| The connection type is allowed | app_settings.connection_app_type must be one of generic_api_credentials, stacksync_user_api_key, stacksync_workspace_api_key or the app's own app_type (<app_type>) |
| Only connector files at the root | <entry>: is not part of a connector; move it out of the connector folder |
The connector and every module version have a complete context.md | the file is missing, the "## <Section>" section is missing, is empty, still has TODO items; fill them in, still has the placeholder text; write the context |
| Every module has an example | needs at least one example between "## EXAMPLES start ##" and "## EXAMPLES end ##" |
The allowed root entries are listed in Project layout, and the context sections in Context.
Why a deployment is refused
When deploy is refused, it prints the reason. Nothing is submitted for review.
| Message | Fix |
|---|---|
the connector does not meet the Stacksync standard: followed by a list | Fix each connector standard problem. |
stacksync.yml workspace does not match the authorized workspace | Set deployment_settings.workspace to a workspace you belong to, or log in to the right one. |
not authorized to deploy to workspace <id> | Log in with an account or API key of that workspace. |
app_type ... must be lowercase letters and digits, in words separated by single underscores | Rename app_type, for example acme_crm. |
app_type must be at most 24 characters | Shorten app_type. |
The app type '<app_type>' is already in use. Choose a different app_type. | Another connector already uses that id. Choose another one. |
module folder '<name>' must be lowercase letters and digits... | Rename the module folder, for example create_records. |
the connector has no module versions under modules/<module>/v<N>/ | Add at least one module with stacksync workflow-module create. |
this update removes module versions that are already deployed: <ids> | Restore those version folders. Deployed versions can't be removed. |
a deployment of this connector is already waiting for review or in progress | Wait for the current deployment to end, then deploy again. |
| An icon error | app_icon_svg_url must answer 200 over HTTPS from a public address without a redirect, be at most 512 KiB, start with <svg and contain no script. |
Deployment artifact too large | The package must be under 32 MiB. Remove large files; list dependencies in requirements.txt. |
archive does not contain a stacksync.yml at its root | Run deploy from the connector folder. |
the Stacksync platform is unavailable; try again later | Try again later. |
Update a connector
Deploy again from the same folder. Each update goes through the same checks and review.
- An update replaces the code of every version of every module.
- A new version folder (
v2) adds a new version. Workflows onv1keep usingv1. - Deployed versions can't be removed, so keep their folders.
- A version's name, description, icon and settings are recorded when it is first deployed. To change them, add a new version.
- Never change
app_typeafter the first deployment: it would be a different connector.
To remove a deployed connector, contact Stacksync support with its app_type.
Runtime limits
| Limit | Value |
|---|---|
| Time per call | About 6 minutes, then the call is cut off. Split longer work into smaller steps. |
| State | None between calls. The connector runs as several processes, so keep no caches, mutable globals or files. |
| Python | 3.11. |