Workflows

Workflows let you automate what happens when code is pushed, a pull request is opened, or a deployment completes. Each service comes with pre-configured workflows that you can customize.

Accessing Workflows

1. Navigate to your project
2. Click on a service
3. Select the Workflows tab

The Workflows tab has two sub-tabs:

• Hooks - the built-in automation workflows (build, deploy, review, scan). Everything below describes these.
• Agent workflows - workflows that run your own Custom Agents on service events. See Agent workflows at the end of this page.

---

How Workflows Work

A workflow has two parts:

• Trigger - the event that starts it (push, pull request, deployment, build, or manual)
• Steps - the actions to perform (build, deploy, review, scan, etc.)

When the trigger fires, the steps run automatically. Steps at the same position run in parallel. Steps at a higher position wait for the previous ones to finish.

---

Default Workflows

These workflows are created automatically when a service is created:

Deploy on Push and Manual Deploy start running immediately. The rest are created with the service but start disabled, so switch on the ones you want. Preview Deployments also defaults to the feat/* branch pattern, so widen it if you want previews on every PR.

Changelog is a Custom Agent preset rather than a plain workflow - toggling it on gives you an editable agent, see Agent workflows.

---

Adding a Workflow

1. Click Add Workflow in the top right
2. Choose a template from the gallery
3. Configure the workflow name, trigger settings, and notifications
4. Click Create

Some templates (like Deploy on Push) are singletons - only one instance is allowed per service. These show "Added" in the gallery if already present.

Looking for the Changelog (Custom Agent) template? It moved to the Agent workflows sub-tab. See Agent workflows below.

---

Configuring Triggers

Each trigger type has its own settings:

Push

• Branch - which branch triggers the workflow. Leave empty for the service's default branch. Supports glob patterns (e.g. feat/*, release/*).
• Tag pattern - triggers on tag pushes (e.g. v*, release-*). Supports glob patterns. Branch and tag patterns are mutually exclusive - a workflow triggers on either matching branches or matching tags, never both.

Pull Request

• Source Branch Pattern - glob pattern for the PR's source branch (e.g. * for all, feat/* for feature branches). The Preview Deployments workflow defaults to feat/*.
• Target Branch - optionally override which branch the PR must target (defaults to service's default branch)
• PR Actions - which PR events trigger the workflow:
  • Opened - when a PR is first created
  • Synchronize - when new commits are pushed to the PR
  • Closed / Merged - when the PR is closed or merged

Deployment Success / Failed

• Environment Type - filter by Stable or Preview (leave empty to match any)

Build Success / Failed

• Environment Type - filter by Stable or Preview (leave empty to match any)

Manual

No configuration needed. Triggered from the deploy button in the UI.

---

Editing a Workflow

1. Click the pencil icon on any workflow card
2. Update the name, description, trigger settings, or notifications toggle
3. Click Save

---

Enabling / Disabling

Toggle the switch on any workflow card to enable or disable it. Disabled workflows won't run but keep their configuration.

---

Deleting a Workflow

1. Click the trash icon on the workflow card
2. Confirm deletion

Deleted workflows can be re-added from the template gallery.

---

Notifications

Each workflow has a Notifications toggle. When enabled, the workflow sends notifications through your project's configured notification channels (Slack, webhooks).

---

Understanding the Workflow Card

Each workflow card shows:

• Name and trigger badge (Push, Pull Request, etc.)
• Branch configuration - e.g. feat/* → main for PR workflows, branch: main for push
• Steps - the sequence of actions (e.g. "Build & Deploy → Service Analysis")
• Enable/disable toggle

---

Common Setups

Basic CI/CD

Enable Deploy on Push with your main branch. Every push to main will build and deploy automatically.

Preview Environments

Enable Preview Deployments. Every PR gets its own preview environment that's automatically cleaned up when the PR is closed or merged.

Code Review + Preview

Enable both Preview Deployments and AI Code Review. PRs get a live preview environment and an automated code review with comments posted directly on the PR.

Post-Build Analysis

Nothing to enable. Deploy on Push already carries a Service Analysis step that runs in parallel with the build, producing the project overview and agent instructions described in How deployments work.

---

Agent workflows

The Agent workflows sub-tab runs your own Custom Agents when something happens on the service. A Custom Agent is a reusable AI agent you define once (a prompt plus tools). An agent workflow binds it to a trigger and decides what happens with the result - commit the changes, open a pull request, call a webhook, or send a notification.

Creating an agent workflow

1. Open the Agent workflows sub-tab
2. Click New agent workflow
3. Pick the trigger (manual, push, PR merged, deployment or build outcome), the agent, and the result actions
4. Click Create

Only an organization owner can create, edit, or delete agent workflows. Members can view them and start manual runs with the Run button.

Changelog template

Click Install changelog template to set up an editable AI changelog in one step. It creates a Changelog agent and a workflow that appends a Keep-a-Changelog entry to CHANGELOG.md whenever a pull request is merged. Unlike the built-in Changelog hook, the agent prompt and its result actions are yours to edit after install.

Runs

Expand a workflow row to see its recent runs with status, trigger, and timing. Each run executes a snapshot of the workflow taken when it was admitted. Editing, disabling, or deleting a workflow cancels runs that are still queued, while a run that is already executing finishes on its captured configuration.

Chaining workflows

An agent can hand off work to another workflow in the same project. Enable the Trigger workflow tool on the agent, then tell it in its prompt which workflow to trigger and what to pass along. During its run the agent stages the trigger together with a handoff brief (markdown, up to 64KB). The staged trigger fires only after the run completes successfully. A failed or cancelled run drops it.

This is how one repository can update another. For example a workflow on your API service can summarize a merged pull request and trigger a docs workflow that opens a pull request on the docs repository.

Details:

• The target must be an enabled agent workflow in the same project. When the agent passes an unknown id, the error lists the available workflows.
• Each run can stage one trigger per target workflow and at most 10 in total.
• Chains that would loop back to a workflow already in the chain are refused, as are chains longer than 10 hops.
• The triggered run shows Agent as its trigger, with the source agent, workflow, and service plus a link back to the source run. Staging is also recorded in the audit log.