Creating Flows¶
Editions: OSS, Cloud, Enterprise. Unless stated otherwise, everything on this page ships in OSS.
Create a flow that runs an AI agent when an event fires (a GitHub PR, a GitLab MR, a Jira ticket, or any HTTP webhook) with approval workflows enforced on every prelooped tool call.
Overview¶
Flows are event-driven automation workflows in Preloop. Each flow:
- Triggers on events (GitHub PR, GitLab MR, Jira ticket, webhook)
- Executes AI agent tasks using configured tools
- Respects approval workflows on prelooped tools
- Logs complete audit trail of all actions
Key Concepts:
- Flow - The automated workflow definition
- Trigger - Event that starts the flow (webhook or tracker event)
- AI Agent - The agent type executing the flow (Codex CLI, Gemini CLI, or OpenCode)
- AI Model - The LLM powering the agent (for example GPT-5.4 or Claude Sonnet 4.7)
- Prompt Template - Instructions for the agent (supports variable interpolation)
- Tools - MCP tools the agent can use (respects approval workflows)
- Execution - Single run of a flow (triggered by an event)
Creating Your First Flow¶
Step 1: Navigate to Flows¶
- Click Flows in the left sidebar
- Click Create flow
Step 2: Choose Creation Method¶
You have two options:
Option A: Use a Preset
Start from a template for common automation scenarios (auto-triage issues, deploy on PR merge, create a ticket from a webhook). Click a preset card to select it.
Flows cloned from a preset track their source: if the preset is later updated, the flow shows a preset update available badge and you can apply or dismiss the update. Applying overwrites the prompt/tools unless you customized them (customizations are flagged as prompt_customized / tools_customized).
For the Pull Request Reviewer, the review delivery gate is off unless the flow
itself sets git_clone_config.review_publication.required: true. The current
preset copies that block into new flows; existing derived flows never inherit
it from the preset or a catalog sync. Opt each existing flow in only after
verifying a consistent API and worker deployment with the API writing review
receipts. During version skew, a successful review tool call for the triggering
PR with no receipt can yield unverified / receipt_unavailable: the run
succeeds with a warning, but publication for the reviewed head is unproven.
See Review delivery check.
The API opt-in example
preserves the full clone configuration and describes the canary check.
Four presets (SBOM Verify, SBOM Exploit Check, Release Security Audit, Component Due Diligence Record) turn a CI-emitted SBOM into a versioned result.json plus a human-readable evidence pack for a human assessor: see Security audit presets (CRA evidence packs).
Option B: Blank flow
Build a custom flow from the ground up. Pick Blank flow at the top of the form.
For this guide, we'll start from a blank flow.
Flow Configuration¶
The name, trigger, agent/model, prompt and tools remain open in the form. Advanced sections summarize model routing, runner/image settings, Git workspace, feedback, notifications and limits. A saved non-default value opens its section automatically. Validation opens the section containing an invalid field and focuses that control.
The sticky action bar keeps Cancel and Save reachable. Leaving a changed form asks whether to discard edits, including Back/sidebar navigation and closing or reloading the browser tab. Successful saves clear the prompt; failed saves keep the draft. Starting GitHub authorization preserves the draft across its redirect.
Basic Information¶
Name (required) - Clear, descriptive name - Shows in flow list and execution logs
Description (optional) - What the flow does - When it should trigger - Any special conditions
Examples:
Name: Auto-triage Critical Issues
Description: Automatically labels GitHub issues as "critical" when created with "urgent" in title
Name: Deploy to Staging on PR Merge
Description: Triggers deployment to staging environment when PR is merged to main branch
Trigger Configuration¶
Flows can be triggered by:
- Webhooks: HTTP POST from any external service
- Tracker events: GitHub, GitLab, Jira events
- Schedules: an interval, daily or weekly time, or cron expression, see Schedule Triggers
Option 1: Webhook Trigger¶
When to use:
- Custom integrations
- Services without native tracker support
- Manual triggers via API
- Testing and development
Configuration:
- Select Trigger type: Webhook
- Save the flow, then click Rotate webhook secret
- Copy the new URL shown once and use it to trigger the flow
Webhook URL format:
Example payload:
{
"event": "payment_received",
"amount": 1500,
"customer_id": "cust_123",
"contract_id": "contract_456"
}
Access in prompt template:
Option 2: Tracker Event Trigger¶
When to use:
- GitHub PR/issue events
- GitLab MR/issue events
- Jira ticket events
- Automated workflows based on development activity
Configuration:
-
Trigger type: Tracker event
-
Tracker: choose from your configured trackers
-
If no trackers exist, add one under Trackers > Add tracker
-
Organization: the GitHub org, GitLab group, or Jira project
-
Projects (optional): specific repository or project
-
Can leave empty to trigger on all projects in organization
-
Events: what triggers the flow
- GitHub: Issue opened, PR opened, PR merged, push, etc.
- GitLab: MR opened, MR merged, issue opened, pipeline, etc.
- Jira: Issue opened, issue updated, comment created, etc.
- A flow can subscribe to multiple event types at once (
trigger_event_typesis an array), for example, trigger on bothissue_openedandissue_updated
GitHub Event Types:
issue_opened- New issue createdissue_updated- Issue edited (title, description, labels, etc.)issue_closed- Issue closedissue_reopened- Issue reopenedpull_request_opened- New PR createdpull_request_updated- PR edited or commits pushedpull_request_closed- PR closed without mergepull_request_merged- PR mergedpull_request_reopened- PR reopenedcomment_created- New comment on issue/PRcomment_updated- Comment editedpush- Code pushed to repositoryrelease- New release published
GitLab Event Types:
issue_opened,issue_updated,issue_closed,issue_reopenedmerge_request_opened,merge_request_updated,merge_request_closedmerge_request_merged,merge_request_approved,merge_request_reopenedcomment_created,comment_updatedpush,tag_pushpipeline- Pipeline event (success, failure, etc.)release- Release published
Jira Event Types:
issue_opened- New issue createdissue_updated- Issue field changedissue_deleted- Issue deletedcomment_created,comment_updated,comment_deleted
Event Filters (Optional)
Narrow when the flow triggers with filters:
- Author/Creator - Username who created the issue/PR
- Assignee - Who it's assigned to
- Reviewer - Requested reviewer (PR/MR only)
- Labels - Must have ALL specified labels
- Milestone - Milestone name (GitHub/GitLab only)
- Priority - Jira priority (Highest, High, Medium, Low, Lowest)
- Issue Type - Jira issue type (Task, Bug, Story, Epic, etc.)
- State - PR/MR state (open, closed, merged)
- Draft - Filter draft PR/MRs
- Merged - Only trigger if PR/MR is merged
- Mergeable State - GitHub: clean, unstable, dirty, blocked
Filter Logic:
- All filters are AND (all must match)
- Labels are OR (any label matches)
- Empty filters match everything
Example: Only Critical Bugs
Example: Only Merged to Main
Access Trigger Event Data in Prompt:
Issue Title: {{trigger_event.payload.object_attributes.title}}
Issue URL: {{trigger_event.payload.object_attributes.url}}
Author: {{trigger_event.payload.user.username}}
Labels: {{trigger_event.payload.labels}}
See Flow Triggers for complete event payload reference.
AI Agent Configuration¶
Flows need an AI agent to execute the automation tasks.
Select Agent Type¶
Available agents:
- Codex CLI (default)
- Fast, non-interactive agentic coding (
codex exec) -
Best for: Code generation, file manipulation, git operations
-
Gemini CLI
- Google's terminal agent
-
Best for: Google ecosystem integrations
-
OpenCode
- Lightweight multi-provider agentic coding CLI
- Best for: Quick code tasks, scripting, automation
Agent CLIs on your own machines. A flow can also run Copilot CLI,
Cursor CLI, Claude Code or Devin CLI on a private runner that reports the
harness as signed in. Turn on Route by harness, pick the model, and
choose what happens when no runner is eligible (harness_fallback:
queue, fallback_server or fail). Those runs use the runner user's own
login and seat; Copilot, Cursor and Devin runs are not gateway metered. See
Your machine as a Preloop runner
and Model routing.
Codex tool profiles¶
Hosted Codex flows can set agent_config.codex_tools to default or lean.
Omitting it is identical to default: existing flows and every shipped preset
keep their current behavior. Unknown values are rejected when saving a flow.
For a flow that needs shell commands and its MCP allow-list, opt in with:
When updating an existing flow through the API, preserve its other
agent_config fields; this object replaces the stored configuration.
lean disables Codex web search, subagents, goals, image viewing, sleep,
interactive user input and the plan tool. It preserves the flow's shell policy
and MCP allow-list. It does not disable MCP tools such as ask_user or
run_flow. This profile is verified for hosted Codex 0.153.4; selecting it
with another codex_cli_version is rejected until that version is supported.
The configuration also applies to resumed sessions and recovery attempts.
It does not configure Codex sessions launched by a private runner.
Codex still includes three MCP resource helpers whenever MCP is attached.
Some models also keep apply_patch and defer MCP definitions behind
tool_search. These have no independent off switch in this CLI version.
Flows with no MCP tools or servers do not attach MCP at all. A native structured
result is an output contract and adds no tool definition. lean never enables
the shell on a flow whose sandbox_type disables it.
Under lean, Preloop omits its additional get_approval_status helper when
the flow has no possible approval path. It retains it for existing approval
results, human-checkpoint tools, applicable tool or sensitive-data policies,
and external tools whose owner or grant policies may require approval.
Incomplete policy metadata retains the helper. The default profile continues
to include it whenever the MCP allow-list is nonempty. This changes discovery
only; approval enforcement and replay authorization remain in force.
Canary a clone before changing a working reviewer: verify repository inspection,
review quality, publication, structured results, and approval park/resume/replay.
Repository instructions may need tools that lean removes. Revert to default
to restore those tools. Smaller definitions recover context space on every
request; monetary savings depend on cached-input pricing and actual cache hits.
They do not make the unchanged Pull Request Reviewer prompt fit an 8K context.
Configure AI Model¶
Each flow needs an AI model (LLM) to power the agent.
If you have no models configured:
- Under AI model, click Add AI model
- Fill in:
- Name: Descriptive name (e.g., "GPT-5.4")
- Provider: OpenAI, Anthropic, Google, Qwen, DeepSeek, or OpenAI-compatible
- Model: Select from dropdown (filtered by agent compatibility)
- Credentials: Configure the upstream provider credential or secret reference when the model needs direct provider access
- Gateway Routing: Enable Preloop gateway routing when you want model traffic to flow through Preloop's OpenAI-compatible or Anthropic-compatible gateway
- Click Save
If you have existing models:
- Select from the dropdown (filtered by agent type compatibility)
- Or click Add AI model to add another
How model routing works:
- Gateway-enabled models send model traffic through Preloop so budget checks, attribution, runtime-session telemetry, and captured gateway events stay centralized
- Direct-provider models can still be used when a gateway path is unavailable or not yet supported for that agent/provider combination
- Secret-backed credentials let Preloop keep provider secrets behind the model record instead of embedding them directly into flow definitions
What the agent receives at runtime:
- The resolved prompt and tool allowlist
- The selected model identity and agent-specific configuration
- Either direct provider access details or Preloop gateway settings such as a managed base URL, model alias, and short-lived bearer token
The model dropdown filters to providers the selected agent supports.
After the flow runs, you can inspect model traffic in execution-scoped gateway events, account usage summaries, runtime session views, and per-model observability screens.
Write the Prompt Template¶
The prompt tells the agent what to do. It supports template variables from the trigger event.
Template Variables:
Access trigger event data using {{trigger_event.*}} syntax:
{{trigger_event.payload.object_attributes.title}}
{{trigger_event.payload.user.username}}
{{trigger_event.payload.labels}}
{{trigger_event.payload.any_field.nested_field}}
Example Prompts:
Auto-triage GitHub Issues:
A new GitHub issue was created:
Title: {{trigger_event.payload.issue.title}}
Body: {{trigger_event.payload.issue.body}}
Author: {{trigger_event.payload.issue.user.login}}
Repository: {{trigger_event.payload.repository.full_name}}
Your task:
1. Analyze the issue content
2. Determine if it's a bug, feature request, or question
3. Add appropriate label using the update_issue tool
4. If it's a bug and mentions "crash" or "error", also add the "urgent" label
5. Use the add_comment tool to acknowledge receipt and estimated triage time
Deploy on PR Merge:
A pull request was merged to main branch:
PR Title: {{trigger_event.payload.pull_request.title}}
PR Number: #{{trigger_event.payload.pull_request.number}}
Author: {{trigger_event.payload.pull_request.user.login}}
Repository: {{trigger_event.payload.repository.full_name}}
Your task:
1. Use the deploy_to_staging tool to deploy this branch to staging environment
2. Run the smoke_tests tool to verify the deployment
3. If tests pass, post a success comment on the PR with the staging URL
4. If tests fail, post a failure comment with logs and rollback the deployment
Process Payment (Webhook):
A payment was received:
Customer ID: {{trigger_event.payload.customer_id}}
Amount: ${{trigger_event.payload.amount}}
Contract ID: {{trigger_event.payload.contract_id}}
Payment Method: {{trigger_event.payload.payment_method}}
Your task:
1. Use the pay tool to process the payment to the contractor
2. The pay tool has approval workflow: amounts > $1000 require CFO approval
3. After payment completes, update the contract status using update_contract tool
4. Send confirmation email to the customer
Prompt Best Practices: - Be specific about what tools to use - Include all relevant context from trigger event - Specify success/failure handling - Mention approval workflows if relevant - Keep it concise but complete
Tool Selection¶
Select which MCP tools the agent can use during execution.
Tool Categories:
- Built-in Tools (Preloop MCP server)
get_issue,create_issue,update_issue,search(available when a tracker is connected)add_comment,update_commentget_pull_request,create_pull_request,update_pull_requestestimate_compliance,improve_compliancerequest_approval,get_approval_status(manual approval requests)-
ask_user(ask a human a question mid-execution) -
External MCP Tools
- Tools from your added MCP servers
- Payment, deployment, database, cloud provider tools
- Custom tools from your own MCP servers
Selection: - By default: No tools are selected - Customize: Check/uncheck specific tools - Disabled tools: Cannot be selected (shown grayed out)
Security Note: - Only selected tools are available to the agent - Agent cannot use tools outside this list - Approval policies still apply to prelooped tools
Best Practice: - Select only tools needed for this flow - Reduces attack surface - Prevents accidental misuse - Clearer agent context
Git Workspace Cloning (Optional)¶
Automatically clone repositories before the agent starts.
When to use:
- Flow needs to read/modify code
- Agent will create commits
- Multi-repository operations
Configuration:
1. Enable Git Workspace Cloning - Toggle Enable Git Workspace Cloning to ON
2. Git User Info
Used for git commits made by the agent.3. Branch Configuration
Source Branch: # optional; blank follows the trigger's branch
Target Branch: # Branch to create for commits (auto-generated if empty)
Source branch is optional, and blank is usually right. Blank means "use
the branch from the trigger payload": for a pull or merge request, its source
branch. The form saves a blank field as null; a flow created through the API
with source_branch omitted gets main, so send null explicitly there. A value pins every run to that branch, whatever branch the trigger
names. Pin a branch only for flows that always work on the same branch, such
as a scheduled sweep of main. A pull request reviewer must leave it blank, or
every review starts from the pinned branch instead of the change under review;
the form warns when a reviewer flow pins a branch.
4. Pull Request / Merge Request - Toggle Create Pull Request to ON - PR/MR Title: (optional, defaults to flow name) - PR/MR Description: (optional)
5. Repositories
In both Create flow and Edit flow, expand Advanced Git workspace, enable workspace cloning, then select Add repository for each checkout. You can edit or remove entries independently. Saving and reopening the flow keeps the full list. Saving with cloning disabled clears the explicit repository list so the executors do not clone it. Re-enabling before saving keeps the entries in the open form. Jira repository bindings and other Git settings are preserved.
The first entry is marked Default and supplies the agent's starting working
directory. Select Make default on another entry to move it first. Each entry
needs a distinct clone path; for example, /workspace/backend and
/workspace/frontend make both repositories available in the same execution.
With no explicit repositories, cloning falls back to the trigger project or Jira repository bindings. Explicit entries take precedence over those bindings; adding or removing entries preserves the saved bindings.
Per Repository:
- Tracker: Select a GitHub, GitLab, or Bitbucket tracker
- Project: (optional) Select a repository project from that tracker
- Repository URL: (optional - leave empty to use trigger project)
- Clone Path: Where to clone (e.g., /workspace)
- Branch: (optional) Pin this repository to a branch. Blank uses the flow
source branch, or the trigger's branch when that is blank too
Example 1: Single Repo (from trigger)
Repository 1:
Tracker: GitHub Production
Repository URL: [empty - auto-detect from trigger]
Clone Path: /workspace
Branch: [empty - use default]
Example 2: Multi-Repo
Repository 1:
Tracker: GitHub Production
Repository URL: https://github.com/acme/backend
Clone Path: /workspace/backend
Branch: main
Repository 2:
Tracker: GitHub Production
Repository URL: https://github.com/acme/frontend
Clone Path: /workspace/frontend
Branch: main
How It Works:
- Flow triggers
- Preloop clones repositories
- Agent starts with repos available
- Agent can read/modify files
- If Create PR enabled, commits are pushed and PR created automatically
Use repository cloning and PR creation when the flow needs to inspect or modify source code during execution.
Custom Commands (Admin Only)¶
Custom initialization commands run inside the container before the agent starts (for example, pip install -r requirements.txt or a setup script). They execute sequentially, and any failure stops the execution.
Commands run with full container privileges, so they are restricted: they are configured by administrators, and in the flow detail view they render read-only. There is no custom-commands editor in the create form.
Saving and Testing¶
Save the Flow¶
- Review all configuration
- Click Create flow (or Save changes if editing)
New blank flows start Enabled and trigger on matching events immediately. Preset copies start Disabled: configure their tracker and project scope, save, then explicitly enable them from Flows. Built-in presets remain disabled templates. Use Pause on the flow details page if you want to stop it from triggering, and Resume to turn it back on.
Changing a flow safely through the API¶
Every flow has a configuration revision. It starts at 1 and goes up by one each time the flow's configuration changes: prompt, model, harness, triggers, clone settings, webhook settings, result schema, custom commands, enable or disable, a preset update being applied, and so on. Runs, run counters and the "a preset update is available" notice do not change it. A write that sends the values already stored does not change it either.
GET /api/v1/flows/{flow_id} returns the revision as revision and as the
ETag response header, which is the revision in quotes ("7"). To change a
flow without overwriting someone else's change:
- Read the flow and keep its
ETag. -
Send the change with that value in
If-Match: -
On
200the change is saved and the response'sETagis the new revision ("8"). Use it for your next change. -
On
412 Precondition Failednothing was saved: another editor (a person in the console or another API client) changed the flow after you read it. The body names the current revision and theETagheader carries it:{"detail": {"code": "flow_revision_mismatch", "message": "The flow changed since it was read. ...", "current_revision": 8}}Read the flow again, decide whether your change still applies to what is there now, and send it again with the new
ETag.
The check and the write happen together under a lock on the flow, so of two
clients that send the same If-Match at the same moment exactly one
succeeds. If-Match: * only requires that the flow exists. A malformed
If-Match is refused with 400. Without If-Match a write is applied
unconditionally, as before, and the response still carries the new ETag.
What a PUT replaces and what it merges: top-level fields you send replace
the stored value and fields you leave out are kept. A nested object you send
(agent_config, git_clone_config, webhook_config, result_schema,
custom_commands, schedule_config, notifications) replaces the stored
object whole, so read it, change it and send all of it. Two exceptions: an
omitted webhook secret is kept, and max_budget / max_iterations sent
without an agent_config are merged into the stored one. Because a nested
object is replaced whole, a read-modify-write of one is exactly where
If-Match matters.
The same If-Match is accepted by the other flow write actions:
POST /api/v1/flows/{flow_id}/webhook-secret/rotate,
POST /api/v1/flows/{flow_id}/apply-preset-update,
POST /api/v1/flows/{flow_id}/dismiss-preset-update (which does not change
the revision) and PUT /api/v1/ci-identities/shared-flows/{flow_id}.
To run only the configuration you reviewed, send If-Match on
POST /api/v1/flows/{flow_id}/trigger as well. If the flow has changed the
trigger is refused with 412 and no execution is created. Every execution
records the revision it was created with as flow_revision.
The console uses the same check: if you save a flow that someone changed after you opened it, nothing is saved, your edits stay in the form, and you can reload the latest version.
Run now¶
Start a run by hand before real events trigger it. The run is a real one and spends like any other:
- Click Run now
- If the prompt has
{{trigger_event.*}}variables, the dialog Values for the trigger event opens - Fill in values for each variable:
- Click Run now
- You'll be redirected to the execution page to watch it run
Flow Execution¶
Monitoring Executions¶
Each time a flow triggers, an execution is created.
View Executions: 1. Go to flow details page 2. Scroll to Recent executions 3. Or: on Flows, click View all next to In flight for all executions
Execution States:
- PENDING - Queued, not started yet
- INITIALIZING - Preparing the execution environment
- STARTING - Container starting up
- RUNNING - Currently executing (stays RUNNING while a tool call waits on approval)
- SUCCEEDED - Completed successfully
- FAILED - Execution failed (see logs for details)
- STOPPED - Stopped by a user
Viewing Execution Details¶
Click an execution to see:
- Overview
- Status, start time, duration
- Trigger event details
-
Agent output
-
Agent Logs
- Real-time streaming logs
- Tool calls made by agent
- Approval requests (if any)
-
Errors and warnings
-
Tool Calls
- List of all tools called
- Arguments passed
- Results returned
-
Approval status
-
Approval Requests
- If agent called prelooped tools
- Shows approval status
- Links to approval details
Execution pages update in real-time via WebSocket. See Flow Execution for retrying executions, gateway-event inspection, and debugging.
Common Flow Patterns¶
Pattern 1: Auto-Triage Issues¶
Trigger: GitHub issue opened
Prompt:
Analyze this issue and apply appropriate labels:
Title: {{trigger_event.payload.issue.title}}
Body: {{trigger_event.payload.issue.body}}
Rules:
- Contains "bug", "error", "crash" → add "bug" label
- Contains "feature", "enhancement", "request" → add "feature" label
- Contains "question", "help", "how to" → add "question" label
- Contains "urgent", "critical", "blocker" → add "priority:high" label
Use the update_issue tool to add labels.
Tools: update_issue, add_comment
Result: Issues automatically labeled within seconds
Pattern 2: Deploy on PR Merge¶
Trigger: GitHub pull request merged
Filters:
Prompt:
Deploy the merged PR to staging:
PR: {{trigger_event.payload.pull_request.title}}
Branch: {{trigger_event.payload.pull_request.head.ref}}
Steps:
1. Use deploy_to_staging tool
2. Run smoke_tests tool
3. If tests pass, post success comment on PR
4. If tests fail, rollback and post failure comment
Tools: deploy_to_staging, smoke_tests, rollback (from your MCP servers), add_comment
Git Workspace Cloning: Enabled (to access code)
Result: Automatic deployment on every merge
Pattern 3: Payment Processing with Approval¶
Trigger: Webhook
Prompt:
Process contract payment:
Amount: ${{trigger_event.payload.amount}}
Recipient: {{trigger_event.payload.recipient}}
Contract: {{trigger_event.payload.contract_id}}
Use the pay tool (requires CFO approval for amounts > $1000).
After payment, update contract status.
Tools: pay (prelooped with amount > 1000 condition), update_contract
Result: Automated payments with approval for large amounts