diff --git a/docs.json b/docs.json index 997df9ddb..f6190c7a8 100644 --- a/docs.json +++ b/docs.json @@ -117,6 +117,7 @@ "workflows/index", "workflows/enable", "workflows/create", + "workflows/app-events", "workflows/manage" ] }, diff --git a/workflows/app-events.mdx b/workflows/app-events.mdx new file mode 100644 index 000000000..a46373c7e --- /dev/null +++ b/workflows/app-events.mdx @@ -0,0 +1,92 @@ +--- +title: "App event triggers" +description: "Run Mintlify workflows in response to events from connected apps like Linear, Notion, and Jira. Connect an app, choose a trigger, and scope the agent's tools." +keywords: ["composio", "app events", "triggers", "linear", "notion", "jira", "integrations"] +--- + + + App event triggers are in early access. Contact support to enable them for your project. + + +App event triggers run a workflow when something happens in a connected third-party app. Use them to react to events outside your repository, like a new Linear issue, an updated Notion page, or a Jira ticket transition. + +When an app event fires, the agent runs with the event payload as context and can call tools from the apps you allowlist on the workflow. + + + Use app event triggers to keep documentation in sync with sources of truth that live outside your repository, such as product specs in Notion or release notes in Linear. + + +## How it works + +1. You connect an app to your deployment. Each deployment authenticates its own integrations. +2. You select a trigger from that app, like **Linear → Issue created**. +3. When the event fires, the app sends a verified webhook to Mintlify. +4. Mintlify queues a workflow run, passes the event payload to the agent, and lets the agent call tools from any apps you allowlist. + +## Prerequisites + +- A Mintlify project with workflows enabled. See [Enable workflows](/workflows/enable). +- An account with the third-party app you want to connect. +- Permission to authorize the app on behalf of your team. + +GitHub and GitLab are not available as app event triggers. Use [push triggers](/workflows/enable#trigger) for repository events instead. + +## Connect an app + +Connect each app once per deployment. Connections are scoped to the deployment, not your organization, so each deployment authenticates separately. + +1. Open the [Workflows](https://dashboard.mintlify.com/products/workflows?tab=workflows) page in your dashboard. +2. Click **Create a custom workflow** or open an existing workflow. +3. Under **Trigger**, select **App event**. +4. Choose an app from the toolkit list. +5. Click **Connect** and complete the OAuth flow in the popup. + +After you connect an app, it stays available to every workflow on that deployment. + +## Configure an app event trigger + +1. With an app connected, select a **Trigger** from that app, like **Issue created** or **Page updated**. +2. Set any trigger-specific options the app requires, such as a project ID or label filter. +3. Save the workflow. + +The dashboard shows a green check next to apps that are connected. If you change the trigger or its configuration, Mintlify re-registers the trigger with the app automatically. + +## Allowlist tools for the agent + +By default, an app event workflow only receives the event payload. To let the agent take actions in connected apps, allowlist their tools on the workflow. + +1. Open the workflow settings. +2. Under **Tools**, select the apps whose tools the agent can call during the run. +3. Save the workflow. + +Only apps you have already connected to the deployment appear in the tools list. The agent can only call tools from apps you explicitly allowlist, even if other apps are connected. + + + Tool calls run as the deployment's connection. Audit logs in the third-party app attribute actions to the connection that authorized them. + + +## Event payload + +When a workflow runs from an app event, the agent receives the raw event payload as a preamble before your workflow instructions. Reference fields from the payload in your prompt to drive the agent's behavior. + +For example, a Linear "Issue created" workflow might use the issue title and description: + +```text Workflow instructions +Read the issue from the event payload. If the issue is labeled "docs", +draft a documentation update that addresses the request and open a pull +request. Use the issue URL in the PR description. +``` + +## Disconnect an app + +Disconnecting an app removes the deployment's authorization for every workflow that uses it. Workflows that depend on the disconnected app stop running until you reconnect. + +1. Open the [Workflows](https://dashboard.mintlify.com/products/workflows?tab=workflows) page in your dashboard. +2. Open the connected apps panel for the deployment. +3. Click **Disconnect** next to the app. + +## Limitations + +- App event triggers are scoped per deployment. Connect each app separately for each deployment that needs it. +- GitHub and GitLab are not available as app event triggers. Use [push triggers](/workflows/enable#trigger) for repository events instead. +- Each workflow has exactly one trigger. You cannot combine an app event trigger with a schedule or push trigger. diff --git a/workflows/index.mdx b/workflows/index.mdx index da9fd38dd..6f304e22d 100644 --- a/workflows/index.mdx +++ b/workflows/index.mdx @@ -20,10 +20,11 @@ Use workflows that run on push events to automate reactive maintenance tasks, li ## Trigger types -Workflows support two trigger types. +Workflows support three trigger types. - **Schedule (cron)** — Run on a recurring daily, weekly, or monthly schedule. Workflows queue within 10 minutes of the scheduled time. - **Push events** — Run when changes push to a specific repository or branch, including pull request merges and direct pushes. +- **App events** — Run in response to events from connected apps like Linear, Notion, or Jira. See [App event triggers](/workflows/app-events). You cannot combine trigger types in a single workflow. Each workflow has exactly one trigger.