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

Source: https://docs.stacksync.com/developers/getting-started-with-stacksync-cli/deploy-a-workflow-connector

`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

<Steps>
  <Step>
    ### Check the connector yourself

    Run the same standard check that Stacksync runs, and fix every problem it lists:

    ```bash
    .venv/bin/python -m stacksync_cdk.connector_checks
    ```

    Then test every module with `stacksync workflow-connector run` against a real account.
  </Step>

  <Step>
    ### Submit it

    ```bash
    stacksync workflow-connector deploy
    ```

    The 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.
  </Step>

  <Step>
    ### Stacksync checks it

    Before anything is built, Stacksync checks the package, the settings, the [connector standard](#the-connector-standard) and the icon. If something fails, `deploy` prints the reason and nothing is submitted. See [Why a deployment is refused](#why-a-deployment-is-refused).
  </Step>

  <Step>
    ### 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:

    ```text
    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.
  </Step>

  <Step>
    ### 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.
  </Step>

  <Step>
    ### 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.
  </Step>
</Steps>

## Follow a deployment

```bash
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:

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

```bash
.venv/bin/python -m stacksync_cdk.connector_checks
```

```text
stacksync.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](/developers/stacksync-cdk/workflow-connector-development-kit#project-layout), and the context sections in [Context](/developers/stacksync-cdk/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](#the-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 on `v1` keep using `v1`.
* 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_type` after 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.                                                                                                     |

## Next steps

<Cards>
  <Card title="Build modules" href="/developers/stacksync-cdk/modules" />

  <Card title="CLI command reference" href="/developers/getting-started-with-stacksync-cli/cli-command-reference" />
</Cards>