Creating Flows¶

Build event-driven automation workflows that execute safely through Preloop's Safety Layer.

Overview¶

Flows are event-driven automation workflows in Preloop. Each flow:

Triggers on events (GitHub PR, GitLab MR, Jira ticket, webhook, schedule)
Executes AI agent tasks using configured tools
Respects approval workflows on prelooped tools
Logs complete audit trail of all actions

Benefits:

No external automation platform required
Safe automation with human oversight
Everything in one system
Real-time monitoring and debugging

Key Concepts:

Flow - The automated workflow definition
Trigger - Event that starts the flow (webhook, tracker event, schedule)
AI Agent - The agent type executing the flow (Codex, Claude Code, Aider, etc.)
AI Model - The LLM powering the agent (GPT-4.5, Claude Sonnet, etc.)
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

📸 Screenshot needed: flows-page-empty.png

Step 2: Choose Creation Method¶

You have two options:

Option A: Use a Preset

Start from a template for common automation scenarios: - Auto-triage GitHub issues - Deploy on PR merge - Create Jira ticket from webhook - Schedule daily reports

Click a preset card to select it.

Option B: Create from Scratch

Build a custom flow from the ground up.

Click Create from Scratch.

📸 Screenshot needed: flow-presets.png

For this guide, we'll create from scratch.

Flow Configuration¶

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

Name: Weekly Report Generator
Description: Sends team productivity report every Monday at 9 AM

📸 Screenshot needed: flow-basic-info.png

Trigger Configuration¶

Flows can be triggered by: 1. Webhooks - HTTP POST from any external service 2. Tracker Events - GitHub, GitLab, Jira events 3. Schedules - Cron-based timing (coming soon)

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 (webhook URL generated after creation)
Use the webhook URL to trigger the flow

Webhook URL format:

https://preloop.ai/api/webhooks/flows/{flow_id}/{secret}

Example payload:

{
  "event": "payment_received",
  "amount": 1500,
  "customer_id": "cust_123",
  "contract_id": "contract_456"
}

Access in prompt template:

Customer: {{trigger_event.payload.customer_id}}
Amount: ${{trigger_event.payload.amount}}

📸 Screenshot needed: flow-webhook-trigger.png

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:

Select Trigger Type: Tracker Event
Select Tracker - Choose from your configured trackers
If no trackers exist, click "+ Add Tracker"
Select Organization - The GitHub org, GitLab group, or Jira project
Select Project - Specific repository or project
Can leave empty to trigger on all projects in organization
Select Event Type - What triggers the flow
GitHub: Issue opened, PR opened, PR merged, push, etc.
GitLab: MR opened, MR merged, issue opened, pipeline, etc.
Jira: Issue created, issue updated, comment created, etc.

GitHub Event Types:

issue_opened - New issue created
issue_updated - Issue edited (title, description, labels, etc.)
issue_closed - Issue closed
issue_reopened - Issue reopened
pull_request_opened - New PR created
pull_request_updated - PR edited or commits pushed
pull_request_closed - PR closed without merge
pull_request_merged - PR merged
pull_request_reopened - PR reopened
comment_created - New comment on issue/PR
comment_updated - Comment edited
push - Code pushed to repository
release - New release published

GitLab Event Types:

issue_opened, issue_updated, issue_closed, issue_reopened
merge_request_opened, merge_request_updated, merge_request_closed
merge_request_merged, merge_request_approved, merge_request_reopened
comment_created, comment_updated
push, tag_push
pipeline - Pipeline event (success, failure, etc.)
release - Release published

Jira Event Types:

issue_opened - New issue created
issue_updated - Issue field changed
issue_deleted - Issue deleted
comment_created, comment_updated, comment_deleted

📸 Screenshot needed: flow-tracker-trigger.png

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

Event: issue_opened
Filters:
  labels: [bug, critical]
  assignee: sre-team

Example: Only Merged to Main

Event: pull_request_merged
Filters:
  merged: true
  target_branch: main  # In trigger_config

📸 Screenshot needed: flow-event-filters.png

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 (Recommended)
Fast, efficient agentic coding
Best for: Code generation, file manipulation, git operations
Models: OpenAI, Google, DeepSeek, Qwen
Gemini CLI
Google's Gemini agent
Best for: Google ecosystem integrations
Models: Google only
Claude Code
Anthropic's official agent
Best for: Complex reasoning, security-critical tasks
Models: Anthropic only
Aider
Code editing focused agent
Best for: Precise code modifications
Models: OpenAI, Anthropic, Google, DeepSeek, Qwen
OpenCode
Lightweight agentic coding CLI
Best for: Quick code tasks, scripting, automation
Models: OpenAI, Anthropic, Google, DeepSeek, Qwen
OpenHands
Full software development agent
Best for: Complex multi-file changes
Models: OpenAI, Anthropic, Google, DeepSeek, Qwen

📸 Screenshot needed: flow-agent-type-select.png

Configure AI Model¶

Each flow needs an AI model (LLM) to power the agent.

If you have no models configured:

Click + Add AI Model
Fill in:
Name: Descriptive name (e.g., "GPT 5.1 Codex")
Provider: OpenAI, Anthropic, Google, DeepSeek, Qwen
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 Create

If you have existing models:

Select from the dropdown (filtered by agent type compatibility)
Or click + Add New 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

Model Compatibility:

Agent Type	Compatible Providers
Codex	OpenAI, Google, DeepSeek, Qwen
Gemini CLI	Google only
Claude Code	Anthropic only
Aider	OpenAI, Anthropic, Google, DeepSeek, Qwen
OpenCode	OpenAI, Anthropic, Google, DeepSeek, Qwen
OpenHands	OpenAI, Anthropic, Google, DeepSeek, Qwen

Recommended models:

GPT-5.1-codex (OpenAI) - Best for Codex agent
Claude Sonnet 4.5 (Anthropic) - Best for Claude Code
Gemini 2.0 Pro (Google) - Best for Gemini CLI

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.

📸 Screenshots needed: add-ai-model-dialog.png, ai-model-select.png

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 create_label tool
4. If it's a bug and mentions "crash" or "error", also add the "urgent" label
5. Post a comment acknowledging 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

📸 Screenshot needed: flow-prompt-template.png

Tool Selection¶

Select which MCP tools the agent can use during execution.

Tool Categories:

Built-in Tools (preloop-mcp server)
create_issue, update_issue, close_issue
create_comment, update_comment
create_pull_request, update_pull_request
get_issue, list_issues
get_file_contents, update_file_contents
request_approval (manual approval requests)
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

📸 Screenshot needed: flow-tool-selection.png

Git Clone Configuration (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 Clone - Toggle Enable Git Clone to ON

2. Git User Info

Git User Name: Preloop
Git User Email: git@preloop.ai

Used for git commits made by the agent.

3. Branch Configuration

Source Branch: main  # Branch to checkout
Target Branch:       # Branch to create for commits (auto-generated if empty)

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

Add one or more repositories to clone:

Per Repository: - Tracker: Select GitHub/GitLab tracker - Repository URL: (optional - leave empty to use trigger project) - Clone Path: Where to clone (e.g., /workspace) - Branch: (optional - leave empty for default branch)

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

📸 Screenshots needed: flow-git-clone-config.png, flow-git-repos.png

Use repository cloning and PR creation when the flow needs to inspect or modify source code during execution.

Custom Commands (Admin Only)¶

⚠️ Enterprise Feature - Admin Permission Required

Run custom shell commands before the agent starts.

Security Warning: - Commands execute with full container privileges - Only use trusted commands - Restricted to administrators

When to use:

Install dependencies (pip install -r requirements.txt)
Run setup scripts
Configure environment
Prepare workspace

Configuration:

Toggle Enable Custom Commands to ON

Enter commands (one per line):

pip install -r requirements.txt
npm install
./setup.sh

Commands execute sequentially
Any failure stops execution

📸 Screenshot needed: flow-custom-commands.png (with admin badge)

Saving and Testing¶

Save the Flow¶

Review all configuration
Optional: Toggle Save as Preset to reuse this flow configuration
Click Create (or Update if editing)

📸 Screenshot needed: flow-create-button.png

Enable the Flow¶

After creation, flows start as Disabled.

On the flow details page, click Enable
Flow is now active and will trigger on matching events

📸 Screenshot needed: flow-details-page.png

Test Run¶

Test your flow before real events trigger it:

Click Test Run button
If prompt has {{trigger_event.*}} variables, you'll see a dialog

Fill in test values for each variable:

trigger_event.payload.recipient: test@example.com
trigger_event.payload.amount: 1500
trigger_event.payload.contract_id: TEST-001

Click Run Test
You'll be redirected to the execution page to watch it run

📸 Screenshots needed: flow-test-run-dialog.png, flow-execution-page.png

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 section 3. Or: Navigate to Flows → Executions for all executions

Execution States: - PENDING - Queued, not started yet - RUNNING - Currently executing - SUCCEEDED - Completed successfully - FAILED - Execution failed (see logs for details) - TIMEOUT - Exceeded max execution time - CANCELLED - Manually cancelled

📸 Screenshot needed: flow-recent-executions.png

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

📸 Screenshots needed: execution-overview.png, execution-logs.png, execution-tool-calls.png

Execution pages update in real-time via WebSocket.

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, create_comment

Result: Issues automatically labeled within seconds

Pattern 2: Deploy on PR Merge¶

Trigger: GitHub pull request merged

Filters:

merged: true
target_branch: main

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, create_comment

Git Clone: 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

Pattern 4: Scheduled Reports¶

Trigger: Schedule (cron: every Monday at 9 AM)

Prompt:

Generate weekly team productivity report:

1. Use get_closed_issues tool to count issues closed this week
2. Use get_merged_prs tool to count PRs merged this week
3. Use list_commits tool to count commits this week
4. Generate summary report
5. Use send_slack_message tool to post to #team-updates

Tools: get_closed_issues, get_merged_prs, list_commits, send_slack_message

Result: Automated weekly reports