# AGENTS Source: https://docs.overcut.ai/AGENTS # AGENTS ## Project Overview This repository hosts the Mintlify documentation site for **Overcut.ai**. Content is written in MDX and organized under `docs/` for product documentation and `blog/` for blog posts. Navigation, theming, and redirects are configured in `docs.json`. ## Repository Structure * `docs/`: main documentation content. Subfolders by group: `get-started/`, `concepts/`, `quick-starts/`, `use-cases/`, `reference/`, `integrations/`, `repositories/`, `how-to/`. * `blog/`: blog landing page and post MDX files. * `snippets/`: reusable JSX/MDX snippets (e.g., blog cards, post metadata list). * `docs.json`: Mintlify configuration (navigation tabs, groups, redirects, theme, SEO). * `.vale.ini` and `styles/`: Vale linting configuration and vocabulary/style rules. * `images/`, `static/`, `logo/`: media and static assets. * `.claude/skills/`: authoring and review skills for this repo. See below. ## Authoring guidance (skills, on demand) Detailed guidance lives in skills under `.claude/skills/`. Invoke the relevant skill when the task matches; do not duplicate this guidance into AGENTS.md. | Skill | Use when | | -------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `doc-style` | Writing or editing prose in any MDX file (voice, tone, punctuation rules, no em dashes, customer-vs-internal balance). | | `doc-page-structure` | Creating a new MDX page or restructuring one (frontmatter, titles, page-length, MDX components, cross-references). | | `doc-navigation` | Adding, moving, or removing pages, or editing `docs.json` (group purposes, redirects, page placement). | | `review-doc-pr` | Reviewing a docs PR for customer value and content quality. | | `review-open-prs` | Triaging the open PR queue. | ## Critical Rules * **Never use em dashes (`—`) in MDX content.** See `doc-style` for replacements. * Verify documented product behavior against the product source at `/Users/yuvalhazaz/projects/overcut-ai.git/overcut` before publishing. Don't paraphrase or invent UI strings. * Do not remove or rename pages referenced in `docs.json` without updating navigation and adding a redirect. * Do not place secrets or credentials in documentation content. * Do not expose internal implementation names (React components, GraphQL fields, file paths from the product source) in customer-facing docs. ## Common Tasks * **Add a new documentation page**: create the MDX file under the right `docs//` folder, add it to the matching group in `docs.json`, fill in frontmatter. See `doc-page-structure` and `doc-navigation`. * **Move or rename a page**: update `docs.json` `pages` and add a `redirects` entry. See `doc-navigation`. * **Fix factually-wrong content**: verify against the product source first, then edit. Prefer minimal targeted fixes to broad rewrites. * **Review a PR**: invoke `review-doc-pr` or `review-open-prs`. ## Reference Examples * `docs/welcome.mdx`: landing page with `` and ``. * `docs/building-blocks.mdx`: multi-section page using ``, ``, ``. * `docs/reference/vault.mdx`: reference page covering one feature surface end-to-end. * `docs/concepts/multi-project-workspaces.mdx`: concept page explaining a cross-cutting idea with links into references. ## Additional Resources * Mintlify `docs.json` reference: [https://mintlify.com/docs.json](https://mintlify.com/docs.json) * Mintlify MDX components: [https://mintlify.com/docs/components](https://mintlify.com/docs/components) * Vale documentation: [https://vale.sh/docs](https://vale.sh/docs) # Agentic SDLC Orchestration vs. Synchronization Source: https://docs.overcut.ai/blog/agentic-sdlc-orchestration-vs-synchronization This article has moved to overcut.ai/blog/agentic-sdlc-orchestration-vs-synchronization. # Build vs Buy Your SDLC Orchestration Layer Source: https://docs.overcut.ai/blog/build-vs-buy-sdlc-orchestration This article has moved to overcut.ai/blog/build-vs-buy-sdlc-orchestration. # How Enterprises Can Adopt AI Developer Tools Successfully Source: https://docs.overcut.ai/blog/enterprise-ai-developer-tools This article has moved to overcut.ai/blog/enterprise-ai-developer-tools. # From Engineering Chaos to Agentic Chaos Source: https://docs.overcut.ai/blog/from-engineering-chaos-to-agentic-chaos This article has moved to overcut.ai/blog/from-engineering-chaos-to-agentic-chaos. # Overcut Blog Source: https://docs.overcut.ai/blog/index The Overcut blog has moved to overcut.ai/blog. # Introducing Overcut Source: https://docs.overcut.ai/blog/introducing-overcut This article has moved to overcut.ai/blog/introducing-overcut. # Overcut vs. n8n for Production-Grade Dev Automation Source: https://docs.overcut.ai/blog/overcut-vs-8n8 This article has moved to overcut.ai/blog/overcut-vs-8n8. # Overcut vs. Copilot, Cursor, and ChatGPT Source: https://docs.overcut.ai/blog/overcut-vs-copilot-cursor-and-chat-gpt This article has moved to overcut.ai/blog/overcut-vs-copilot-cursor-and-chat-gpt. # The Agentic Software Development Lifecycle Source: https://docs.overcut.ai/blog/the-agentic-software-development-lifecycle This article has moved to overcut.ai/blog/the-agentic-software-development-lifecycle. # The Plateau at Level Three Source: https://docs.overcut.ai/blog/the-plateau-at-level-three This article has moved to overcut.ai/blog/the-plateau-at-level-three. # The Real Future of AI Development Source: https://docs.overcut.ai/blog/the-real-future-of-ai-development This article has moved to overcut.ai/blog/the-real-future-of-ai-development. # Workflows That Remember Source: https://docs.overcut.ai/blog/workflows-that-remember This article has moved to overcut.ai/blog/workflows-that-remember. # Changelog Source: https://docs.overcut.ai/changelog/overview New features, improvements, and fixes in Overcut. This release lets you bring your own container images so agents work with your exact toolchain, and build and run your software factory from the coding agent you already use. It also makes single sign-on smoother to use and manage, and verifies what a custom LLM model supports before you rely on it. ## Custom agent images * Register container images from your own registry and select one per repository, so agents clone, build, and test with the exact SDKs, compilers, and internal CLIs your code needs. Images are pinned to a digest, so runs stay reproducible until you choose to pick up a new build. Private registries are supported. Custom images are an Enterprise feature; the system images remain available on every plan. See [Agent Images](/docs/reference/agent-images). ## Build from your coding agent * Connect Claude Code, Cursor, Codex, or any MCP-capable coding agent to Overcut with one command, `npx overcut init`. The agent can then connect your Git provider, register repositories, design and publish workflows, and check on runs, all in conversation and without switching to the web app. Everything it does runs as you, inside your workspace's permissions and audit trail. See [Connect Your Coding Agent](/docs/get-started/connect-your-coding-agent). * Sign in from a terminal, including SSH and headless sessions, and manage API tokens from the CLI for CI and scripts. ## Single sign-on * Improved SSO experience with built-in management: view and control your workspace's SSO settings under **Security > Single sign-on**, including whether the provider is enabled and whether users on your email domains join automatically. SSO still requires initial setup by the Overcut team. ## LLM models * Custom LLM models now discover their own capabilities. Testing a model detects whether it supports tool calling, vision, PDF input, and prompt caching, and runs use those verified results instead of assumptions based on the model name. See [Testing a Model](/docs/reference/llm-models#testing-a-model). * Prompt caching detection is improved for Anthropic models served through custom endpoints, such as Bedrock inference profiles, so caching is used wherever the endpoint supports it. ## Messaging triggers * Choose the emoji Overcut reacts with when it picks up a Slack message, so the acknowledgment matches the conventions your team already uses and does not collide with reactions that mean something else in your channels. You can also turn the reaction off entirely. See [Acknowledgment reactions](/docs/workflows/triggers#acknowledgment-reactions). ## Workspace * The workspace sidebar is regrouped into **Context**, **Agent Runtime**, and **Governance & Admin**, so integrations, model and image settings, and administration are easier to find. ## Fixes * An agent session kept open for comments now completes when its time limit ends, instead of leaving the run in Terminating indefinitely. * The runs list sorted newest first no longer starts with queued or skipped runs. * Orchestration steps for a cancelled or completed instance are no longer re-triggered. This release adds a Workspace Library for sharing agents, tools, secrets, and templates across projects, context parameters for values that differ per project, repository, workflow, orchestration, or agent, an in-app discussion page for orchestration decisions, and project-wide messaging channels for every workflow run. ## Workspace Library * Every workspace now has one **Workspace Library**, opened from the project picker, for the agents, MCP servers, skills, and secrets that several projects share, and for workflow and orchestration templates. See [Workspace Library](/docs/reference/workspace-library). * Projects use Library agents, MCP servers, skills, and secrets by reference, so an edit in the Library reaches every project. Library items carry a **Library** badge in pickers. * **Promote to library** moves a project resource into the Library without breaking existing links. **Install from Library** copies a published template into a project as an independent draft. * Chat can create and list Library resources, promote project resources, and install templates. ## Context parameters * Define a value once and reference it as `{{params.}}` in step instructions and agent instructions. Each project, repository, workflow, orchestration, or agent can set its own value, and the most specific one wins at run time. See [Context Parameters](/docs/reference/context-parameters). * Manage definitions on the new **Context Parameters** workspace page and the **Context Parameters** tab in Project Settings. * Instruction editors offer completion for `{{params.` references. * The Playground previews the value each key resolves to, and the existing **Run Context** panel now lists the resolved parameters under `params`. * Chat can define parameters, set values, and preview resolution. ## Orchestration discussions * Pending orchestration decisions now have a dedicated in-app discussion page. Send the first message to start the discussion; decision details, case-file context, agent activity, and the full conversation history sit alongside the chat. See [Approvals and Discussions](/docs/orchestrations/approvals-and-discussions). * Pending decision cards and tracked-item questions link directly to their discussion. ## Messaging channels * Every workflow run now receives all active channels registered to its project, so agents can post updates to any project channel from a scheduled, manual, Git-triggered, or message-triggered run. * When a project has one registered channel, agents use it automatically. With several channels, agents receive the list of destinations and choose one explicitly. * Replies default to the triggering thread only in the channel where the trigger message arrived. Messages to other channels start at the channel root. * Native Slack slash commands that arrive without a message timestamp now dispatch instead of silently failing. * A project or channel lookup failure, or one invalid channel credential, no longer stops the run or blocks the project's other channels. ## Claude engine * Claude-engine token usage is now counted in [Token Usage Analytics](/docs/workflows/token-usage-analytics) for workflows, runs, steps, models, and agents. Billing and credits are unchanged. ## LLM models * Custom LLM models have a **Supports Vision** setting that controls whether image content is sent to the model. See [LLM Models](/docs/reference/llm-models#vision-support). ## Playground and workflow drafts * A draft missing a trigger or another required field no longer breaks its project's workflow list or detail pages. Open, repair, export, or delete the draft; publishing still validates it. * A malformed trigger on one workflow no longer prevents the project's other workflows from loading or running. * The Playground recovers when its selected workflow has been deleted: it shows a warning, keeps valid run history and current selections, and stops submitting the stale workflow. A failure to load a workflow's parameters no longer replaces the whole page. * A never-published workflow no longer shows preview data in the Playground unless the working draft is explicitly selected. ## Other fixes * Repository selections persist across searches and pages when adding repositories, and the **Add Selected** button shows how many are selected. After a partial bulk-add failure, the failed repositories remain selected for retry. * Saving an LLM model no longer leaves a false unsaved-changes warning or stale configuration values in the form. * Agents without a description can be edited and saved. * Unknown tool names are removed from an agent's tool list consistently, so agents no longer advertise tools that cannot run. This release moves the Claude engine to bring-your-own models: Claude-engine steps now run on the Anthropic or AWS Bedrock models you configure, with a workspace default and per-sub-agent model selection. ## Claude engine models * Claude-engine steps now use the models you configure in the workspace, each with its own credentials, instead of a single workspace-wide Claude API key. Anthropic and AWS Bedrock models are supported. See [Claude Agent SDK](/docs/integrations/claude-agent-sdk). * Set a workspace **Default Claude Engine Model** in Workspace Settings > AI. A step resolves its model in order: the explicit step or agent choice, then the workflow default, then the workspace Claude default, then the main workspace default. * Pin a different model per sub-agent on the Claude engine. Pinning changes only which model answers: credentials, billing, region, and gateway always come from the session's coordinator model, so a sub-agent model must be from the same provider as the session. * Anthropic models accept a **Base URL**, so the Claude engine can route through a gateway that serves the Anthropic wire format (`/v1/messages`). * Existing workspaces were migrated automatically: the legacy workspace "Claude API key" secret became a "Claude (migrated)" Anthropic model, set as the workspace Claude default. No action is needed. The Workspace Secrets tab was removed along with the legacy secret. * Misconfigured models fail at dispatch with a message naming the model and the cause. There is no silent fallback to another key or model. ## AWS Bedrock * Bedrock models can now authenticate with a Bedrock API key as an alternative to an IAM access key pair. When both are set, the API key is used. See [LLM models](/docs/reference/llm-models). * Prompt caching now applies to Claude models routed through OpenRouter and AWS Bedrock, cutting token usage and latency on repeated context. * Bedrock cache tokens are now counted in LLM usage. ## Triggers * Messaging trigger conditions now expose the full message context in the workflow builder's condition selector: channel ID, channel name, channel provider and privacy, workspace ID, message text, and message and thread timestamps. Build conditions such as `context.channel.id` alongside the existing actor fields. ## Orchestrations * Human replies and decisions now resume an orchestration reliably: transient failures are retried automatically, and an instance that cannot recover is shown as stalled instead of failing silently. ## Workflow builder and runs * Run details and logs now show step names instead of step IDs, using the names from the run's workflow snapshot even after the workflow changes. * Model errors during runs are now classified and reported with distinct messages instead of all surfacing as model unavailable. * Fixed parallel tool calls from OpenAI models being misrouted. * Fixed workflow builder steps rendering stacked on top of each other. * Fixed the Space key not registering in instruction editors inside the workflow builder. ## Integrations * Agents can now read ticket comments on Linear and ClickUp. ## On-prem deployments * All services now honor `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`, including spawned agent containers, so Overcut can run behind an egress proxy. ## Other fixes * Removed team members no longer appear in the team member list. This release introduces Orchestrations, a new module for running multi-workflow processes with agents deciding the path and humans deciding at the gates. ## Orchestrations A workflow automates a single job. An orchestration runs the whole process: it carries a work item (a ticket, a task, or an external resource delivered by a custom event) from intake to completion, across as many workflows as the process takes. Real processes rarely follow one path. Instead of authoring every branch up front, you define the outcome and the boundaries: the goal, the workflows the orchestration may use, and the points where a human must decide. Within those bounds, agents choose the next step at runtime based on how the work actually unfolds, so the same orchestration handles the straightforward case and the exceptional one. * **Bounded autonomy**: agents pick the path, but only from the workflows you allowed, within the limits you set, and never past a gate without a human decision. * **Human judgment where it matters**: gates pause the process for approval, and you can discuss a pending decision with the orchestration in chat before you decide. * **Supervised to completion**: a supervisor keeps each instance moving, detects stalls, and judges the result against the goal, not just whether the steps ran. * **Accountable by default**: every routing decision is recorded, and the conversation stays connected to the work item. Comments on the original issue or pull request flow into the process, and replies go back to it. * **Visible in operation**: every in-flight item is tracked in one place, from intake to resolution, and any instance can be inspected or cancelled at any point. Orchestrations are built on a visual canvas and start from the same triggers workflows already use. ## Machine sizes for workflow runs * Choose the machine size a workflow runs on with the new **Machine Size** setting in workflow settings: `standard` (default, 1 credit per run), `large` (2 credits), or `xlarge` (4 credits). Larger sizes provide more CPU and memory for workspace commands such as builds and tests. * The size is frozen when the run starts and shown on run views, and the run log records the machine size used. ## Slack thread reply trigger * Workflows can now trigger on `thread_reply`: when someone replies in a watched Slack thread, the workflow fires with the reply as context. Configure it like any other trigger in the workflow builder. ## File attachments * Attached DOCX, XLSX, and PDF files are now parsed and their content made available to agents. PDFs are passed natively to Anthropic models. * Fixed attachments with non-ASCII filenames (for example Hebrew) arriving garbled. ## Models * The GPT-5.6 family is available as system models: `gpt-5.6-sol` (flagship), `gpt-5.6-terra` (mid), and `gpt-5.6-luna` (small), all with vision enabled. * Seven legacy system models were retired: `o3`, `o3-mini`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4o-mini`, `gpt-5-codex`, and `gpt-5.2-codex`. ## Assistant and chat * The workflow builder assistant now suggests a publish message when you publish workflow changes. * The chat input suggests your next message as ghost text; press Tab to accept. ## Azure DevOps * The agent's completion message is no longer overwritten by later status comments on pull requests. * Fixed `list_tickets` keyword search failing due to invalid WIQL syntax. ## Reliability & fixes * Agent start failures (for example an image that cannot be pulled) now surface a clear error and fail fast instead of hanging. ## Run Script workflow action * New `script.run` action runs an inline bash script as a deterministic workflow step, with no AI agent or model tokens involved. * Scripts receive trigger data and previous step outputs through environment variables, and can return structured JSON to later steps by writing to `$OC_OUTPUT_FILE`. * Secret values are redacted from script results, and a configurable timeout stops the script and every process it spawned. * The script field uses a code editor with syntax highlighting, and the workflow builder assistant can add and configure the step for you. * [Read the docs](/docs/workflows/run-script) ## Run Context panel * Workflow run details now include a **Run Context** panel: select **Context** to see the actual `trigger` data and `outputs` JSON available to the run's steps and templates. Step outputs update while the run executes, so you can verify what template expressions like `{{outputs..}}` resolve to. ## LLM gateway support * Custom LLM models on OpenAI, OpenRouter, and Azure OpenAI (Responses API) can now route through a proxy or API gateway: override the base URL, choose how the credential is sent (bearer Authorization, `api-key` header, or a custom header name), and add static extra headers for gateway routing. Standard Azure OpenAI also supports extra static headers. Existing models keep their current behavior. * Fixed deactivated models becoming unrecoverable: inactive models stay visible on the LLM Models page, where you can review, edit, or reactivate them, while model pickers only offer active models. * [Read the docs](/docs/reference/llm-models#gateway-and-custom-endpoint-settings) ## Azure DevOps * Code review results are now submitted as reviewer votes with comment threads on Azure DevOps pull requests, and retries no longer create duplicate threads. * Fixed automated replies from the integration's service account re-triggering workflows. ## Skills * Add multiple skills at once from the Add Skill page. ## Slack * Channel pickers load faster: channel lists are cached server-side with debounced search, and repeated scans no longer trip Slack rate limits. ## UI refresh * Workflow builder nodes use a new tab-card style with a floating action toolbar on the canvas. * Fixed text overflow on agent cards. ## Reliability & fixes * Fixed agent connections dropping mid-run due to premature socket closes and connection registration races. * Fixed several tool-call handling errors that could stall LLM conversations or break retries. * Agent status reporting now times out safely during transient outages instead of crashing the run. * Repository connections no longer show duplicates across providers, and abandoned connection drafts are cleaned up automatically. * Repository identification tolerates extra text around JSON output instead of failing the workflow. * Fixed ClickUp requests failing on some content-type headers. * The universal dev container image (version 6) now ships Node 22. ## Token usage analytics * New token usage analytics on the dashboard, with charts and metrics that break down LLM consumption over time and per workflow, so you can see where tokens are going. * Workflow run consumption can be filtered at the workspace level, and workflow names in the usage charts link straight to their runs. * Cached input tokens are now tracked and reported as part of usage. ## Audit trail * Full audit trail across every workspace-scoped resource, recording who changed what for security review, compliance, and incident investigation. * Browse and filter the audit log in the UI, defaulting to the last 7 days, with field-level diffs of each change. * [Read the docs](/docs/reference/audit-trail) ## Models * Added support for GPT-5.5 and GPT-5.4-mini. ## Prompt caching * Anthropic prompt caching is now applied to the system prompt, reducing cost and latency on repeated runs. * Prompt-cache tokens are reported consistently across the Anthropic and OpenAI Responses API paths. ## Dev containers * Added a new universal image (version 6) and a .NET 10 variant. * Agent image resolution now spans multiple repositories, with precedence and clear reporting when images conflict. ## Preparation steps * Workflow run details now show preparation steps, such as setting up the workspace and provisioning the environment, as their own distinct steps. You can follow each one as it runs and see exactly where time is spent before your workflow begins. ## Reliability & fixes * Chat sessions are more stable and stay connected through infrastructure disruptions instead of hanging. * Fixed LLM retries failing because trailing system messages violated Anthropic's message ordering requirements. * Custom model configuration errors are now surfaced, and stale configuration no longer lingers after editing a model. * Fixed API tokens expiring prematurely instead of honoring the rolling inactivity window. * Workflow failures now surface git token errors in the run status instead of failing silently. ## Triggers * Issue triggers now expose classification fields - `priority`, `severity`, `components`, `areaPath`, and `iterationPath` - across Jira, Azure DevOps, and Linear, so you can filter and branch workflows on them. * Issue triggers now provide granular `labelsAdded` and `labelsRemoved` arrays, so you can react to exactly which labels changed rather than the full label set. * Linear issues with no priority now map to an undefined priority instead of a "No priority" label, so priority filters behave consistently. ## Azure DevOps * Connecting an Azure DevOps organization now uses a guided, multi-step OAuth flow. * Added support for legacy `visualstudio.com` URL formats. * Azure DevOps comments are now fully converted from HTML to plain text, so comment content reads cleanly in workflow runs. * Clearer error handling when prefetching Azure DevOps data fails during setup. ## Repository connections * Connecting a repository now surfaces webhook creation errors immediately, instead of silently leaving the repository connected with no webhook. * Unhealthy repositories now show their state with a retry option in the integrations UI. * Soft-deleted repositories are excluded from project lookups, preventing stale settings validation errors. ## Reliability & fixes * Fixed agent log scrolling so a tall message no longer hijacks the page scroll until it is focused. * Fixed dropped tool responses when several tool calls run in one batch. Synthetic attachment messages are now deferred until all sibling tool calls complete. * Fixed orphaned tool calls by limiting internal agent delegation to one per turn. ## Custom Events Overcut already comes with built-in integrations for systems like GitHub, Jira, Linear, and GitLab. But every organization has additional systems that matter to their workflow, whether internal platforms, custom services, enterprise tooling, or external vendor systems. With Custom Events, any system that can send an HTTP request can now trigger an Overcut workflow. **What this unlocks for your team** * **Incident response automation across your full stack** - connect Datadog, Grafana, PagerDuty, internal alerting systems, or custom observability pipelines directly into remediation workflows. * **Deployment and CI orchestration beyond built-in integrations** - Jenkins, Buildkite, internal deployment tooling, release scripts, or platform APIs can trigger workflows directly. * **Enterprise-wide workflow automation** - connect internal portals, security systems, vendor platforms, legacy infrastructure, or any custom service into your SDLC automation layer. * **Unified orchestration across all systems** - the entire operational ecosystem around your engineering organization, not just the tools Overcut ships with out of the box. **Built for production** * Flexible authentication (bearer token, custom header, or URL-only) to support different sender capabilities. * Token and secret rotation without downtime. * Concurrency control via `lockKey`, allowing workflows that touch the same resource to execute safely and sequentially. * Project-level scoping to control which teams can consume specific event types. * Structured payload fields that keep workflow runs readable in the UI while remaining fully filterable in workflow logic. Overcut can now orchestrate workflows across the full surface area of your organization, not just predefined integrations. [Read the docs](/docs/integrations/custom-events) ## Meet your new Overcut assistant We've reimagined the assistant as a first-class workspace citizen. * A new home screen welcomes you with a focused chat experience. Start a workflow, ask a question, or kick off a task from a single input. * Persistent header chat stays with you across the app, expanding and collapsing as you work. * Conversation history with renaming, deletion, and auto-generated titles, so you can pick up exactly where you left off. * Real-time updates across the UI. When the assistant creates or edits something like a workflow, permission, or trigger, the UI updates instantly without a refresh. * Smarter and more capable. The assistant can now perform almost anything available in the UI. Ask it to connect an MCP server, inspect logs, manage integrations, or execute workflows. ## Multi-project workspaces Workspaces now support multiple projects with proper isolation and scoping throughout the platform. * Global project picker in the workspace header for fast switching. * Per-project repository access controls. Choose whether a project can access all connected repositories or only a selected subset. * Project-level permissions with team and role assignment for finer-grained access control. * Project colors for quick visual identification. * Project-scoped runs, dashboards, and consumption summaries that automatically respect the active project. * Restructured sidebar with workspace ↔ project mode switching and nested settings. ## Slack integration * Connect Slack to your workspace, manage channels, and send messages directly from workflows and the assistant. * Channel message triggers that kick off workflows when Slack messages arrive, with filtering by channel, user, and message content. * Expanded OAuth scopes for message history and reactions support. ## Workflow builder & orchestration * Syntax-highlighted instruction editor with live preview in a full code editing experience. * New agent tools for linking and unlinking tickets across Jira, Linear, and other ticketing systems, including support for relationship types. ## UI polish * Brand-new icon system for crisper and more consistent visuals across the platform. * Restyled sidebar, menus, and profile areas with refined design tokens. * Centralized breadcrumbs for clearer navigation context across every page. * Automatic selection of your latest execution or default repository when opening the playground. * Smarter workflow run defaults that jump directly to the most relevant log step based on run status. ## Reliability & fixes * Improved handling for large agent outputs with automatic management of oversized tool results. * Cleaner branch checkouts. Cached working trees now discard stray uncommitted changes before switching branches. * Fixed an issue where deleting a comment containing a slash command could accidentally retrigger it. * Fixed PR approvals via `submit_review` failing with "no pending review". This release is focused on giving teams better visibility, more control, and faster ways to scale agent-driven workflows across the organization. ## Orchestration Map Get a clear, real-time view of how your entire system operates. Instead of managing workflows, agents, and integrations in isolation, you can now see how everything connects in one place. This makes it easier to understand dependencies, debug issues faster, and confidently evolve your setup without breaking things. ## Skills Turn your existing knowledge and tools into reusable capabilities for agents. Overcut now lets agents use the same skills your developers already rely on, including skills from repositories and marketplaces. You don't need to rebuild anything, you can plug into what already exists and bring it into your workflows with full control. * Reuse skills from your existing ecosystem and marketplaces. * Apply the same governance and management layer across all skills. * Control which agents can use which skills to keep execution focused and avoid prompt bloat. * Ensure consistency while still allowing flexibility at runtime. The result is a more scalable way to distribute expertise across teams, without losing control. ## Playbook Catalog Make it easier for teams to get started and reuse proven workflows. The new catalog helps teams discover, adopt, and standardize workflows across projects, reducing setup time and ensuring best practices are consistently applied. ## Workflow Visibility Understanding what happened during a workflow run is now much simpler with a redesign of the execution details and logs. Teams can quickly scan executions, identify issues, and drill into details, reducing time spent debugging and improving overall reliability. ## Change Accountability Every workflow version change is now clearly tied to a person, with full visibility on the history page. This improves traceability, governance, and collaboration, especially in larger teams where multiple people are evolving workflows. This release focuses on self-improvement, memory management, and better visibility into agent behavior. ## Automatic Workflow Self-Improvement Workflows are now self-improving through an automated reflection process. After a configurable number of executions (default: 10), Overcut analyzes a sampled set of recent runs and feeds insights back into the workflow. Auto-improvement is enabled by default for all workspaces. **How it works** Each retrospective runs a multi-step pipeline: * **Investigate** - analyzes logs, tool usage, and outcomes across sampled runs. Identifies errors, inefficiencies, and recurring patterns, including whether existing memories helped or hurt. * **Process tentative memories** - validates previously tentative memories. Repeated patterns are promoted to active; contradictions are removed. * **Create memories** - generates new memories from cross-run patterns. Patterns seen in 2 or more runs become active; strong single-run signals stay tentative. * **Update weights** - adjusts memory relevance (0.0-1.0) based on impact. Helpful memories are strengthened; ineffective ones decay. Memories below 0.05 are archived. * **Summarize** - produces a structured report with findings, memory updates, and recommendations. Manual mode is also available - run retrospectives on demand with an optional focus question. Manual runs skip weight updates and tentative memory processing to avoid bias. **New configuration options** * Run threshold - number of runs before triggering a retrospective. * Sample size - percentage of runs analyzed. [Read the docs](/docs/how-to/workflows/workflow-self-improvement) ## Agent Tool Visibility You can now see exactly which tools each agent has access to during a workflow run. * New "Tools Available" message in each agent thread. * Captured for both main agents and sub-agents. * Included in thread summaries for quick reference. * Infrastructure logs excluded from step counts to keep things clean. This makes it much easier to understand why an agent did or didn't use a specific tool. ## Cancel Queued Workflow Runs Runs in On Hold status can now be cancelled directly from the UI. * Cancel button with confirmation dialog. * Transitions the run to Failed with a clear status message. ## GPT-5.3 Codex as Default Model The default agent model is now GPT-5.3 Codex, improving code generation and reasoning out of the box. Workspaces with an existing default model are not affected. ## Workflow Version Tracking Each run now includes the system-managed version of the workflow at dispatch time. This makes it easier to track how changes impact results over time. This update introduces deeper integrations, smarter agents, and better visibility into how your workflows run and improve over time. ## ClickUp Integration Overcut now supports full integration with ClickUp. You can connect your workspace and have workflows automatically sync with your tasks: * Create comments. * Update statuses. * Track attachments. Everything is powered by real-time webhook events, and supports ClickUp markdown formatting for clean, readable updates directly in your tasks. ## Agent Memory Agents can now learn across workflow runs. They build memory of patterns, decisions, and context from your codebase, making workflows more consistent over time. Key capabilities: * Dedicated UI to view, edit, and manage memory. * Memory scoped per workflow step for precision. * Full visibility into which memories are used during execution. * Tentative memory system where agents suggest new memories for approval. This is a big step toward adaptive, improving workflows. ## Retrospective Workflows You can now run retrospectives on past workflow executions. Select previous runs and trigger a retrospective to: * Analyze agent logs and tool usage. * Evaluate outcomes. * Generate a consolidated summary with actionable insights. This lays the groundwork for automatic workflow self-improvement. ## Workflow Dashboard Each workflow now has a dedicated dashboard with: * Recent runs. * Average duration. * Quick access to run details. This gives you a clear view of performance over time without digging into logs. ## GPT-5.4 Model Support Overcut now supports GPT-5.4 as the default model for agent and chat workflows. You get access to improved reasoning and performance out of the box. ## Custom Agents You can now define custom agent types tailored to your workflows. This allows you to go beyond built-in agents and create specialized automation aligned with your development processes. [Read the docs](/docs/reference/base-agents#custom) ## Additional Improvements * Use case organization - cleaner tab-based navigation. * Workflow output display - properly formatted single-message outputs. * Scrollable chat - improved experience for long agent conversations. ## MCP Catalog & One-Click Installation Finding and installing MCP servers is now much easier. You can browse a curated MCP catalog directly in the app, search by name, filter by category, and see which servers are already installed. When installing a server, a guided setup flow walks you through everything from a single page: * Configuring required secrets. * Selecting which tools to expose. * Previewing the final configuration. * Creating the server. You can still create custom MCP servers for any service in your ecosystem. [Read the docs](/docs/quick-starts/mcp-catalog) ## MCP Server Secrets MCP servers can now have project secrets attached directly to them. Secrets can be created, updated, or removed from the MCP server settings page and are securely resolved at runtime when agents execute. [Read the docs](/docs/reference/mcp-servers) ## Scratchpad Tools for Multi-Agent Workflows Agents now have built-in scratchpad tools designed for multi-step workflows. These allow agents to pass structured data between steps and agents, replacing file-based scratchpads that sometimes caused path confusion or accidental overwrites. All scratchpad tools are already available to agents in the playbooks repository, so you can start using them immediately in your workflows. [Read the docs](/docs/reference/scratchpad-tools#scratchpad-tools) ## GPT-5.3-Codex Model Support GPT-5.3-Codex is now available as a model option. Vision support is enabled out of the box, and vision has also been enabled for existing Codex models. Across most playbooks we are seeing major improvements in quality, accuracy, and execution speed. ## New Code Review Playbook + Major Improvements We released a new code review playbook built with: * The new scratchpad tools. * Improved reasoning flow. * Parallel execution. Combined with GPT-5.3-Codex, we are now seeing average review times of \~4 minutes for mid-to-large PRs, with improved accuracy and more consistent feedback. [View the playbook on GitHub](https://github.com/overcut-ai/overcut-playbooks/tree/main/code-review) ## Context Map A new way to manage multiple code and ticket repositories across your workspace. **What it is** A visual, graph-based view of all your repos across GitHub, GitLab, Bitbucket, Jira, Azure DevOps, and Linear, showing how ticket systems connect to code repos. **What you can do with it** * Visually connect ticket repos to code repos with simple drag and drop. * Instantly see which features are enabled per repo (caching, indexing, hints, custom instructions). * Filter by org or configuration. * Focus on a specific repo and highlight only its related connections. * Edit repo configuration inline from the same screen. **Why this matters** Agents need to understand which code repos correspond to which ticket systems. Without clear correlations, scoping gets messy. Context Map becomes the central place to manage that relationship across your entire workspace. Two new capabilities bring your CI pipelines into Overcut workflows. ## CI Triggers & Tools Workflows can now react to CI pipeline events - failed builds, completed runs, timed-out jobs, and more. Six new trigger events (`ci_workflow_failed`, `ci_workflow_completed`, and others) let you kick off workflows automatically when something happens in your pipeline. Agents also get five new CI/CD tools to inspect runs, read logs, and retry workflows, all without leaving the Overcut environment. ## Fix CI Playbook Our first CI-powered playbook is live. Fix CI automatically detects when a CI run fails on a PR, reads the logs to figure out what went wrong, applies a code fix, validates it locally by re-running the failed command, and pushes the fix, all hands-free. It won't take shortcuts either: no `ts-ignore`, no deleting tests, no commenting out code. If the fix requires a bigger change, it leaves a detailed comment for the developer instead. Trigger it automatically on any CI failure, or manually with `/fix-ci` on any PR. ## Build Your Own CI Workflows We also enriched our playbook repo with knowledge about CI events and context, so you can use it to build your own custom CI workflows tailored to your team's needs. ## A note on rollout CI-triggered workflows are a new feature, so we recommend monitoring them for the first few runs before enabling fully autonomous operation. Start with manual triggers (`/fix-ci`), review the fixes they propose, and enable the automatic trigger once you are confident in the results. ## Vault You can now securely store secrets and access tokens inside Overcut. Go to Settings -> Agents -> Vault to get started. Secrets stored there are injected into the agent execution sandbox as environment variables at runtime. This allows you to: * Store API keys and credentials securely. * Control which secrets are available per use case or per agent. * Ask the agent to execute commands that reference secrets via environment variables. No more exposing credentials inside prompts. ## MCP Support (Beta - Controlled Rollout) We've added support for MCP integrations, allowing you to connect external systems and capabilities directly to specific agents. When combined with Vault, you can provide MCP credentials securely at runtime without exposing them in prompts. MCP is currently in controlled beta rollout and is enabled per workspace on request. ## Persistent Agent Memory Agents now retain persistent memory across runs. They carry forward context about your codebase, structure, and project patterns. This reduces repeated exploration and makes execution smarter over time, especially in long-running or iterative workflows. This works automatically. You don't need to configure or enable anything; the agent manages this behavior internally. ## Dedicated Explore Agent We introduced a dedicated Explore Agent for deep codebase understanding. It knows when to explore, when to act, and handles large or unfamiliar repositories much more reliably. This significantly improves accuracy and overall run stability. It is used automatically by other agents when needed. If you want to explicitly instruct an agent to leverage it at a specific step, you can simply say something like "use the explore agent to analyze the repository structure before making changes". ## Parallel Multi-Agent Execution You can now delegate multiple tasks in the same turn within a multi-agent session. For example, you can instruct the system to assign multiple review tasks to different agents simultaneously, enabling true parallel execution instead of sequential work. This reduces total runtime and improves throughput for complex workflows. The coordinator will attempt to parallelize work automatically when it makes sense. If you know that tasks can safely run in parallel and want to improve runtime, you can also instruct it explicitly, for example "run in parallel", "delegate all tasks at the same time", or "execute simultaneously". ## New Skills in overcut-playbooks We've added new skills to the overcut-playbooks repository to help you create higher-quality Overcut use cases. To use them: * Pull the latest version of the repository. * Use your preferred local agent. * Leverage the new skills to generate or refine structured playbooks. These updates should make it easier to build reliable, production-ready workflows. ## Workflow Versioning Workflow versioning is now live. This gives you full control over workflow changes with a git-inspired approach, without risking production. **What's new** * **Draft vs Published** - edits are saved as drafts. Only published versions run, so you can safely work without affecting live workflows. * **Publish with messages** - when you publish, add a short message describing what changed, just like a commit. * **Full history** - see every version of a workflow, who published it, and when. * **Safe rollbacks** - restore any previous version with one click. * **Unpublished changes view** - a new page shows all workflows with pending changes across the project, including visual diffs. * **Discard changes** - reset your draft back to the last published version. **How it works** * Edit your workflow as usual; it auto-saves as a draft. * When ready, click Publish and add a message. * View history anytime from the workflow page. # Core Building Blocks Source: https://docs.overcut.ai/docs/building-blocks The primitives behind every Overcut automation: workspaces and projects, the agent harness, workflows, and the runtime that connects them to your Git, tickets, and chat. Overcut organizes engineering automation into a small set of primitives. Once you know what each one is, where it lives, and which boundary it crosses, you can read any workflow, pick the right scope for new work, and reason about what an agent can or can't do at runtime. This page is the orientation map. Each block links to the detailed reference for the topic. ## The hierarchy Every building block belongs to one of three layers: | Layer | What it holds | Examples | | ------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | **Workspace** | Shared infrastructure and reusable building blocks for the whole organization | Integrations, LLM Models, Teams, Workspace Library, Context Parameters | | **Project** | A bounded agent harness owned by one team | Agent Roles, Skills, MCP Servers, Repositories, Vault, Channels, Workflows, Orchestrations | | **Runtime** | What exists only while work is happening | Executions, Orchestration instances, Interactive Sessions, Memories, Retrospectives | A workspace can contain one project or many. The split exists so each scope of work runs against a narrow harness with its own credentials and audit trail, while integrations, models, and team membership stay shared. The workspace also has one **Workspace Library** for the agents, tools, secrets, and templates that several projects need. For the full breakdown, see [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces). *** ## Workspace The **workspace** is the top-level container. It holds everything that should be configured once for the whole organization. * **Integrations**: OAuth connections to GitHub, GitLab, Azure DevOps, Bitbucket, Jira, Linear, ClickUp, and Slack. See the [Integrations overview](/docs/integrations/overview). * **LLM Models**: which models are available to projects, and the workspace default. See [LLM Models](/docs/reference/llm-models). * **Teams, Roles, Users**: who has access, and at what permission level. * **Workspace Library**: agents, MCP servers, skills, and secrets that projects use by reference, plus workflow and orchestration templates that projects install. See [Workspace Library](/docs/reference/workspace-library). * **Context Parameters**: values referenced as `{{params.}}` that each project, repository, workflow, orchestration, or agent can set for itself. See [Context Parameters](/docs/reference/context-parameters). *** ## Project A **project** is the unit of work and ownership. It bundles the agent harness for one scope (one product, one environment, one customer) and the team that runs it. Each project has its own: * **Repositories** it is allowed to read from and act on * **Project Channels** (the Slack channels it can post to and be triggered from) * **Agent Roles**, **Skills**, and **MCP Servers** that define what its agents can do, including any it attaches from the Workspace Library * **Project Vault** for the project's own secrets * **Context Parameters** defined by the project, plus the values it sets on its own resources * **Workflows** and their **Executions** Projects are isolated by default: vault, repositories, and history from one project are not visible to another. Workspace Library resources are the exception; projects reuse them without copying. Create a new project when the work targets a different codebase, needs different credentials, or should be owned by a different team. Stay in one project when scope, secrets, and people are shared. *** ## The agent harness The harness is the set of resources, owned by the project or attached from the Workspace Library, that an agent can see and call. A narrow harness produces sharper, more predictable runs than a wide one. The harness is composed of six building blocks. ### Repositories Repositories are connected at the workspace level, then granted to each project. A project either uses every workspace repository or a chosen subset (the **Allow access to all repositories** toggle on **Project Settings → Project Repositories**). Beyond raw access, repositories carry three pieces of metadata that make them useful at runtime: * **[Repository Mapping](/docs/repositories/repository-mapping)**: which repositories a given ticket relates to, so the [`repo.identify`](/docs/workflows/repo-identify) action can pick the right code for the work. * **[Repository Caching](/docs/repositories/repository-caching)**: pre-cloned repositories on the runner so workflows start fast. * **[Repository Indexing](/docs/repositories/repository-indexing)**: semantic code search so agents find relevant context without scanning the tree. ### Integrations Integrations are the OAuth connections that let Overcut listen to events and act through provider APIs. They are configured once at the workspace level, then exposed to projects through repositories and channels. | Provider | What it enables | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [GitHub](/docs/integrations/github), [GitLab](/docs/integrations/gitlab), [Azure DevOps](/docs/integrations/azure-devops), [Bitbucket](/docs/integrations/bitbucket) | Read and write code, open PRs, comment, react to PR and issue events. | | [Jira](/docs/integrations/jira), [Linear](/docs/integrations/linear), [ClickUp](/docs/integrations/clickup) | Read and write tickets, comment, react to lifecycle events. | | [Slack](/docs/integrations/slack) | Trigger workflows from `@overcut` mentions, the `/overcut` slash command, channel messages, or thread replies; let agents reply, edit, react, and continue threads. | Agent tools are **provider-agnostic**. An instruction like "open a pull request" or "create a ticket" works across every connected integration without changing the agent. See the [Agent Tools Reference](/docs/reference/tools). The workspace-level Integrations page: connected provider organizations (GitHub, ClickUp, GitLab, Jira, Linear, Azure DevOps, Slack) listed as cards with a Disconnect button, alongside a left-rail of all orgs grouped under the Integrations tree. ### Channels A **channel** is a Slack channel that a specific project is allowed to use. Channels are registered on **Project Settings → Project Channels** and each one has a routing mode: * **Mentions only (default)**: `@overcut` mentions and `/overcut` slash commands start workflows. Replies in a live interactive thread continue that run. * **Watch all messages**: top-level channel messages and thread replies can trigger workflows. A thread reply starts a new workflow only when no live run or session exists on that thread. Once a channel is registered, agents in that project can post, reply in threads, edit, and react inside it, and an [interactive session](/docs/reference/interactive-sessions) can continue in a Slack thread the same way it does on a PR or issue. ### Agent Roles An **agent role** is a reusable AI worker. Each role is built on one of five **base agent types**, which determine its default toolset and built-in role instructions: | Base Type | Default tools | Best for | | -------------------- | ------------- | ----------------------------------------------- | | **Senior Developer** | 30 | Implementation, debugging, full code lifecycle | | **Tech Writer** | 25 | Documentation, spec writing, structured content | | **Code Reviewer** | 24 | PR reviews, code quality, CI monitoring | | **Product Manager** | 18 | Ticket management, planning, triage | | **Custom** | 0 | Hand-pick every tool | You extend a base type with additional instructions, extra tools, MCP servers, and skills to produce specialized agents (for example, a "Backend Developer" and a "Frontend Developer", both built on Senior Developer). See [Base Agent Types](/docs/reference/base-agents). An agent role is owned by one project, or by the Workspace Library, in which case workflows in any project can run it. See [Workspace Library](/docs/reference/workspace-library). The Agent Roles page: a grid of nine project agents (Backend Developer, Code Reviewer, Daily Planning Product Manager, DevOps Engineer, Docs Technical Writer, Frontend Developer, House Keeping Agent, QA Engineer, Security Reviewer) each shown with its color tag, description, model, and a sample of its tools. ### Skills A **skill** is a reusable set of instructions that lives in one of your connected repositories, packaged in the open [Agent Skills](https://github.com/anthropics/skills) format. After a skill is added to a project, you assign it to the agent roles that should follow it. Skills are the right place for guidance that should be authored once and applied consistently: framework conventions, review checklists, escalation rules, naming standards. Keeping them in a repository means they version with the code they describe. See [Skills](/docs/reference/skills). The Skills page: a left rail listing the project's skills (PR Description, Test Plan, Architecture Diagram, Release Notes, Customer Reply, Incident Postmortem) and a right pane showing the selected PR Description skill with its source repo, path, pinned ref, last-synced metadata, and a read-only SKILL.md preview. ### MCP Servers **MCP Servers** give agents access to external tools through the [Model Context Protocol](https://modelcontextprotocol.io/): a database, an internal API, a third-party service, a custom toolset. Install common servers with one click from the [MCP Catalog](/docs/quick-starts/mcp-catalog), or configure a custom server. Each server can be assigned to specific agent roles, and you can restrict which of its tools an agent is allowed to call. See [MCP Servers](/docs/reference/mcp-servers). The MCP Servers page: a left rail of installed servers (Figma, Datadog, Notion, Playwright, Sentry, PagerDuty, Postgres) with the Figma server selected. The right pane shows General (server name), Configuration (a JSON stdio config), and an Allowed Tools list (get_file, get_file_nodes, get_file_images, ...). ### Project Vault The **Project Vault** stores credentials that workflows, agents, and MCP servers need at execution time: API keys, tokens, database passwords. Secrets are encrypted at rest, injected into the execution sandbox as environment variables, and never sent to the LLM. See [Vault](/docs/reference/vault). Secrets that several projects share live in the **Library Vault** of the Workspace Library. LLM provider credentials are not vault secrets; they are configured on each model under [LLM Models](/docs/reference/llm-models). *** ## Workflows A **workflow** is one automation path: a graph that turns an event into an outcome (a reviewed PR, a drafted spec, a triaged ticket, a resolved incident). Workflows live inside a project, and every workflow has one **trigger** and one or more **steps**. For goals that need several workflow runs over time, an [orchestration](/docs/orchestrations/overview) coordinates a single work item across a closed set of approved workflows until the goal is complete. The Workflow Builder canvas for a Ticket Triage workflow: an Issue Opened trigger feeds an Identify Repository step, a Triage Ticket agent.run, and a Post Recommendation step, with workflow-level settings on the right. The trigger says when the workflow runs. It can be a Git event (PR opened, issue labeled, comment added), a ticket event, a CI run result, a [scheduled cron](/docs/workflows/scheduled-workflows), a manual click, or an `@overcut` mention or `/overcut` slash command on any PR, ticket, or Slack channel. Slack channels set to **Watch all messages** can also trigger workflows from top-level channel messages and thread replies when no live run or session exists on the thread. Events are normalized across providers, so one workflow can react to GitHub, GitLab, or Bitbucket without conditional logic. See [Triggers](/docs/workflows/triggers). A step is one operation in the graph. Some steps are deterministic ([`git.clone`](/docs/workflows/git-clone), [`repo.identify`](/docs/workflows/repo-identify), [`script.run`](/docs/workflows/run-script), [`ci.executeWorkflow`](/docs/workflows/ci-execute-workflow)). Use Run Script for repeatable inline bash commands that should run in the workflow execution container without an AI agent. Other steps run an agent: [`agent.run`](/docs/workflows/agent-run) for a focused task, [`agent.session`](/docs/workflows/agent-session) for an interactive conversation. Outputs from one step flow into the next. Every workflow has a published history and an auto-saved draft, so you can compare versions and restore an earlier definition without losing in-progress edits. See [Workflow Version History](/docs/reference/workflow-history). The Workflows page: a project's catalog of workflows (PR Reviewer, Ticket Triage, Root Cause Analyzer, CVE Remediator, Changelog Generator, Daily Planning, ...) with status, priority, trigger event, slash command, agents, and last-updated columns. *** ## Runtime These building blocks only exist while a workflow is running, or once it has finished. ### Executions An **execution** is one run of a workflow: the trigger event, the path through the graph, every step's input and output, and the agent's chain of reasoning. Executions are visible in real time under **Monitor** > **Logs**. Overcut coordinates concurrent runs so they don't fight over the same resource: * **Resource locking**: only one workflow runs against a given issue, PR, or repository at a time. * **Priority queuing**: a 1 to 100 scale (lower runs first) when several workflows target the same resource. * **Event deduplication**: rapid-fire events on the same resource merge while queued. See [Workflow Execution Control](/docs/workflows/workflow-execution-control). The Logs page: a table of recent workflow runs across PR Reviewer, Slack Incident Responder, Ticket Triage, and other workflows, each row showing trigger, duration, and status (Completed, Failed, Timeout, Skipped, Stopped). ### Orchestration instances An [orchestration instance](/docs/orchestrations/monitoring) is the runtime record of one work item moving toward an orchestration goal. It tracks which approved workflows have run, the decisions in between, any human approvals, and whether the goal is complete. ### Interactive sessions An [interactive session](/docs/reference/interactive-sessions) is an ongoing conversation between users and an agent that started with `agent.session`. Comments on the originating PR, issue, or Slack thread route directly into the live session instead of starting a new workflow, so context is preserved. Sessions end on a keyword, a timeout, or a slash command interrupt. Cleanup behavior is covered in [Session Cleanup](/docs/workflows/session-cleanup). ### Memories A **memory** is a piece of knowledge that survives between runs of the same workflow: a coding convention, a recurring issue pattern, a decision made earlier. Agents read and write memories automatically during a run; no extra setup is required. Memories are scoped to one workflow, so each workflow builds its own institutional knowledge. See [Workflow Memory](/docs/how-to/workflows/workflow-memory). ### Self-improvement Workflows get sharper over time through **retrospectives**: automated reviews that look at recent executions, identify patterns, promote tentative findings into active memories, and adjust the weight of existing ones. Retrospectives run when **Auto-Improve Workflows** is enabled at the workspace level and the workflow has retrospectives configured in its **Self-Improvement** panel. See [Workflow Self-Improvement](/docs/how-to/workflows/workflow-self-improvement). ### Monitoring Every step of every execution streams structured logs, inputs, and outputs to **Monitor** > **Logs** and the project **Dashboard**. From there you can replay a step, inspect what an agent saw, and follow links back to the PR, ticket, or Slack message that triggered the run. Orchestrations add their own live view: each one has an **Activity** tab showing where every instance is right now. See [Monitoring Instances](/docs/orchestrations/monitoring). *** ## How the blocks compose Reading these in order, the full path of one automation is the loop the software factory runs on: an event starts the work, agents execute it inside a scoped harness, humans approve at the gates, and the run feeds the next one. 1. A user, a service, or a clock fires an event that matches a **trigger** in a **workflow**. 2. Overcut checks **project** scope (repositories, channels, vault) and queues the **execution**. 3. **Actions** run in order. Some are deterministic (`git.clone`, `repo.identify`, `script.run`, `ci.executeWorkflow`). Some hand off to an **agent role**, which uses its **base type**, **skills**, **MCP servers**, and the project's tools to do the work. 4. The agent reads and writes **memories**, posts back to the originating PR, ticket, or Slack thread, and (optionally) opens an **interactive session** for follow-up comments. 5. The **execution** is recorded, surfaced in monitoring, and made eligible for the next **retrospective**. ## Where to go next * New to the platform: start with the [Quick Starts](/docs/quick-starts) and [Playbooks](/docs/quick-starts/playbooks). * Designing a new workflow: open the [Workflow Builder guide](/docs/how-to/workflow-builder). * Coordinating a work item across workflows: read [Orchestrations](/docs/orchestrations/overview). * Shaping a project's harness: read [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces) and [Base Agent Types](/docs/reference/base-agents). * Sharing agents, tools, or values between projects: read [Reuse Across Projects](/docs/concepts/reuse-across-projects). * Connecting tools: browse the [Integrations overview](/docs/integrations/overview) and the [MCP Catalog](/docs/quick-starts/mcp-catalog). # Execution Engines Source: https://docs.overcut.ai/docs/concepts/execution-engines Understand what changes and what stays the same when an agent step runs on the Overcut engine or the Claude engine, and how to pick one per step. Every agent step in a workflow runs inside the same sandbox with the same repository checkout. The **Execution Engine** decides what drives the agent inside that sandbox: which runtime sends prompts to the model, executes tool calls, and decides when the task is done. Overcut ships two engines. **Overcut** is the default and runs Overcut's own agent runtime. **Claude** runs Anthropic's Claude Agent SDK, the same runtime behind Claude Code. The agent definition is the same on both. What differs is the model providers you can use, the file and shell tools the agent works with, how sub-agents are delegated, and how usage is reported. **Engine or harness?** The industry term for this layer is the **agent harness**: everything in an agent except the model, summarized as "Agent = Model + Harness". Anthropic describes the Claude Agent SDK as "a general-purpose agent harness", and you will see the same word in vendor comparisons and engineering blogs. Overcut's Workflow Builder labels the same choice **Execution Engine**, and this page uses "engine" to match the product. When someone says Overcut runs agents on "the Claude harness" or "Overcut's own harness", they mean the Claude and Overcut engines described here. Overcut also uses "harness" in a second, wider sense: a project's [agent harness](/docs/concepts/multi-project-workspaces) is the set of repositories, Skills, MCP servers, agents, and secrets an agent can reach. These are two layers of the same idea. The project defines what the agent can see and call, and the engine defines the loop that drives it. ## Why engines are chosen per step The engine is a property of a step, not of a workflow, an agent, or a workspace. Both the [Agent Run](/docs/workflows/agent-run) and [Multi-Agent Session](/docs/workflows/agent-session) actions expose it in the Workflow Builder under **Agent → Execution Engine**. Leaving it unset means **Overcut**. Choosing per step lets one workflow mix engines. A triage step can run on an OpenAI model through the Overcut engine while the implementation step that follows runs on the Claude engine. The workflow catalog and the run details view show an engine logo on each step, so you can see which engine a step used without opening its configuration. See [Agent Engine Indicators](/docs/workflows/workflows#agent-engine-indicators). ## What stays the same An agent definition does not depend on the engine. You can switch a step between **Overcut** and **Claude** without changing the agent, and everything in this list carries over: * **Agent definition and instructions**: the role, persona, and step instructions. * **Sub-agents**: the agents a coordinator can delegate to. * **Skills**: assigned [Skills](/docs/reference/skills) load on both engines. * **MCP servers**: assigned [MCP Servers](/docs/reference/mcp-servers) and their allowed-tool lists. * **Agent memory**, **project secrets**, and **context parameters**. * **Repository checkout**: the same cloned repositories in the same sandbox. * **Run logs and streaming**: messages, tool calls, and thread views in run details look the same. * **Overcut integration tools**: tickets, pull requests, code review, CI, memory, scratchpad, orchestration, and semantic code search all behave the same. On the Claude engine they reach the agent through an MCP server that Overcut runs inside the sandbox, but the tool set is the same. ### Repository instruction files are not loaded on either engine Files such as `CLAUDE.md`, `AGENTS.md`, `.claude/settings.json`, `.claude/skills/`, and `.cursor/rules` are present in the checkout, and an agent can read them like any other file. Neither engine puts them in context on its own. This is also true on the Claude engine, which runs with the SDK's isolation defaults rather than loading project settings the way Claude Code does on a developer's machine. This is deliberate. Repository instruction files are written for interactive coding with a person in the loop, and an agent that silently inherited them would behave differently per repository with no visible cause. To apply conventions consistently, put them in the agent's instructions or in a Skill. Both work identically on both engines. To use a file that already lives in the repository, tell the agent to read it in the step instructions, for example "read `CLAUDE.md` before making changes". ## What differs | Dimension | Overcut engine | Claude engine | | -------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Model providers | OpenAI, Azure OpenAI, Anthropic, AWS Bedrock, OpenRouter | Anthropic, AWS Bedrock, or any Anthropic-compatible gateway such as LiteLLM | | Credentials | Your own custom models, or Overcut's system models | A custom Anthropic or AWS Bedrock model in your workspace. No system-model fallback | | Custom LLM gateway | Any provider, with base URL, credential, auth method, and extra headers | Gateways that serve the Anthropic `/v1/messages` API, through the Anthropic model's **Base URL**, with API-key auth | | File and shell tools | Overcut tools such as `read_file`, `edit_file`, and `run_terminal_cmd` | Claude Code's native tools such as `Read`, `Edit`, `Bash`, and `Grep` | | Sub-agent models | Each sub-agent uses its own model and credentials | One provider and one set of credentials per session; a pinned sub-agent model changes only the model name | | Usage reporting | One record per LLM call | One record per model per session result | ### Models and credentials The Overcut engine accepts every provider on the [LLM Models](/docs/reference/llm-models) page, including Overcut's system models, so a step can run with no credentials of your own. The Claude engine speaks the Anthropic wire format, so it accepts Anthropic and AWS Bedrock models, plus any gateway that exposes the Anthropic `/v1/messages` API. LiteLLM, Portkey, and similar proxies qualify: create an **Anthropic** model, set its **Base URL** to the gateway, and authenticate with an API key. The gateway can route to whatever model it serves behind that endpoint. OpenAI, Azure OpenAI, and OpenRouter models cannot serve the Claude engine because they use a different wire format, and this is not a roadmap gap. The model must be an active custom model in your workspace. If the step resolves to a system model, a deactivated model, or a model on another provider, the step fails before it starts with an error naming the model and the cause. A failure on either engine fails the step. Neither engine falls back to the other. The two engines resolve the step's model through different cascades. The Claude engine has its own workspace default, **Default Claude Engine Model**, and does not fall back to a system model. See [Model Cascade](/docs/reference/llm-models#model-cascade) for both orders and [Claude Agent SDK Integration](/docs/integrations/claude-agent-sdk) for setup. ### Tools Both engines give the agent the same Overcut integration tools. The difference is in file and shell access. On the Overcut engine, the agent uses the file system and code utility tools documented in the [Agent Tools Reference](/docs/reference/tools). On the Claude engine, those are replaced by Claude Code's built-in tools, and run logs show their names (`Read`, `Write`, `Edit`, `Bash`, `Grep`) instead of the Overcut names. The Overcut integration tools keep their names on both engines. On the Claude engine, the coordinator's configured tool list restricts Overcut integration tools but not Claude's built-in file and shell tools. Removing `run_terminal_cmd` from an agent does not prevent the coordinator from running shell commands on the Claude engine. Sub-agents on the Claude engine do respect their tool lists. If a step must be read-only or must not run commands, run it on the Overcut engine. ### Sub-agents Delegation works the same way on both engines. The coordinator decides when to hand work to a sub-agent based on the sub-agent's description, can delegate several independent tasks in one turn, and run details show each delegation as its own thread. What differs is which model and credentials each sub-agent runs on. On the Overcut engine, each sub-agent runs with its own model configuration, including its own provider and credentials. On the Claude engine, one session uses one provider and one set of credentials, taken from the coordinator's resolved model. Pinning a model on a sub-agent changes which model answers, and nothing else: the API key, region, gateway, and billing stay the coordinator's. A sub-agent pinned to a model on a different provider than the coordinator fails the step at dispatch. Pin it to a same-provider model, or leave it on the default. On AWS Bedrock, a pinned sub-agent's inference profile must exist in the coordinator model's region and account. A mismatch surfaces as an AWS error during the run, not when you save the workflow. ### Usage reporting Both engines report to the same [Token Usage Analytics](/docs/workflows/token-usage-analytics) views and the same billing records. The grain differs: * The Overcut engine records one row per LLM call, so **LLM Calls** counts API requests. * The Claude engine records one row per model per session result. **LLM Calls** counts results, which is lower than the number of API requests for the same work. Retries and follow-up messages in a session each produce their own result. * On the Claude engine, usage is attributed to a sub-agent only when that sub-agent is pinned to a model no other agent in the step uses. Sub-agents on the default model are counted under the coordinator. * Every call a Claude-engine step makes, including the SDK's own background calls, runs on the model you configured. You will not see a model you never set up in your usage or your provider bill. * Claude-engine usage is reported for visibility. Spend is billed by Anthropic or AWS on your own account, and Overcut does not charge credits for it. ## Choosing an engine Use the **Overcut** engine when the step: * Needs a model from OpenAI, Azure OpenAI, or OpenRouter, or a gateway that only speaks the OpenAI format. * Should run on Overcut's system models without your own provider credentials. * Must enforce a restricted tool list on the coordinator, for example a read-only review step. * Needs per-call usage records for cost analysis. * Needs sub-agents on different providers or with separate credentials. Use the **Claude** engine when the step: * Benefits from Claude Code's native coding behavior and built-in file and shell tools. * Runs on an Anthropic or AWS Bedrock model you already pay for. Mixed workflows are common: planning and review steps on the Overcut engine, implementation steps on the Claude engine. Because the agent definition is engine-independent, you can try a step on the other engine by changing one field and re-running. ## Related * [Claude Agent SDK Integration](/docs/integrations/claude-agent-sdk): set up a Claude-compatible model and select the Claude engine. * [LLM Models](/docs/reference/llm-models): providers, credentials, and the model cascade for each engine. * [Agent Tools Reference](/docs/reference/tools): the Overcut tool set. * [Token Usage Analytics](/docs/workflows/token-usage-analytics): where usage from both engines appears. * [Agent Run vs Multi-Agent Session](/docs/workflows/agent-differences): choosing the step type before choosing the engine. # Multi-Project Workspaces Source: https://docs.overcut.ai/docs/concepts/multi-project-workspaces Use projects to give each scope of work its own bounded agent harness (repositories, MCP servers, skills, agents, and secrets) while sharing models, integrations, team membership, and the Library across the workspace. A workspace can contain one project or many. Each **project** is a bounded scope of work with its own **agent harness**: the set of [Agent Roles](/docs/reference/base-agents), [Skills](/docs/reference/skills), [MCP Servers](/docs/reference/mcp-servers), repositories, and [vault](/docs/reference/vault) secrets that defines what the agents inside this project can do, see, and call. The surrounding **workspace** is what stays shared: billing, integrations, LLM models, teams, the [Workspace Library](/docs/reference/workspace-library), and [context parameter](/docs/reference/context-parameters) definitions. Multi-project workspaces exist so a single team or org can run automation against several distinct codebases, products, or initiatives, each with its own bounded harness, without workflows, credentials, or permissions bleeding into each other. ## Why projects Projects exist to keep agent runs focused on a narrow harness, give each team ownership of its own scope, and isolate work that should not share credentials, repos, or audit trails. ### Bounded scopes produce better agent results An agent that can see ten MCP servers, fifty skills, and every repository in the workspace has to decide which of them are relevant on every call. The wider the harness, the more often it picks the wrong tool, opens the wrong repo, or pulls in irrelevant context. A project deliberately narrows the harness to the MCP servers, skills, agent roles, and repositories that actually apply to one scope of work. Inside that boundary the agent has fewer choices, and the choices it does have are all relevant, which is what makes agent runs sharper, faster, and more predictable. ### Team-owned harnesses Projects are the unit of ownership. The team that does the work in a project is the team that edits its harness (its agents, skills, MCP servers, repositories, and vault) without needing access to anyone else's. Workspace administrators still control the shared substrate (integrations, models, the Workspace Library, team membership), but the day-to-day changes belong to the team that runs that project. ### Isolation by default A project's vault, project-owned skills and MCP servers, and run history are not visible from other projects. Resources in the [Workspace Library](/docs/reference/workspace-library) are the deliberate exception: projects reuse them by reference without making copies. That makes projects the right boundary when work needs separate credentials, separate codebase access, or separate auditability, for different products, different environments, different customers, or different business units sharing one Overcut workspace. ## When to use multiple projects Create a new project, instead of adding more workflows to an existing one, when any of the following are true: * The work targets a **different codebase or product surface** that should not share repositories, workflows, or vault secrets with anything else. * A **different team** should own the project. Each team edits its own project's settings; cross-project edits are blocked by permissions. * It needs a **different set of credentials** (for example, separate API keys, separate database connection strings, separate cloud accounts) that should not be visible to other workflows in the workspace. * You want **separate auditability**: runs, history, and feedback that don't mix with unrelated work. If two areas of work share the same repos, the same secrets, and the same team, one project is usually enough. ## What lives where The boundary between workspace and project is the most important thing to understand. Anything that should be set once for the whole organization lives at the workspace level. Anything tied to a specific scope of work lives in a project. | Area | Workspace-level (shared) | Project-level (the harness) | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | Identity & defaults | Workspace name, timezone, default LLM model, auto-improve toggle | Project name, color, project-specific overrides | | People & access | Users, Teams, Roles | Per-project team assignments and role assignments | | Credentials | Library Vault (secrets shared by reference) and LLM provider credentials on each model | Project Vault (secrets owned by this project) | | Context parameters | Workspace definitions and their defaults, plus repository values, which follow the repository into every project that attaches it | Project definitions, plus values set on the project's workflows, orchestrations, and agents | | Integrations | Git provider connections (GitHub, GitLab, Azure DevOps, Bitbucket, Jira, Linear, ClickUp), Slack workspace connection, LLM Models | Project Channels: which Slack channels this project can use | | Repositories | The pool of all connected repositories | Which subset of repositories this project can use | | Agent harness | Workspace Library agents, skills, and MCP servers, reused by reference | Project-owned Agent Roles, Skills, and MCP Servers, plus whatever the project attaches from the Library | | Workflows and orchestrations | Workspace Library templates, which never run | Runnable workflows and orchestrations, including copies installed from the Library | | Execution | (none) | Playground, Logs, Dashboard | | Visualizations | Context Map (repository correlations across the workspace) | Project Map (orchestration view scoped to this project) | | Billing | Usage & Billing | (none) | The rule of thumb: **shared infrastructure stays at the workspace; each project's harness, and the team that owns it, stays in the project.** ## Workspace-level navigation From the workspace sidebar (no project selected), the navigation is split into **Workspace** and **Account** groups: * **Workspace**: **Integrations**, **LLM Models**, **Context Parameters**, and **Context Map**. These pages manage shared connections, shared values, and workspace-wide visibility. * **Account**: **Settings**, **Projects**, **Security**, and **Usage & Billing**. These pages manage workspace defaults, project administration, access controls, and billing. Within those groups, you have access to: * **Settings**: workspace name, timezone, default LLM model, and the Auto-Improve Workflows toggle. See [Workspace Settings](/docs/reference/workspace-settings). * **Projects**: the list of all projects in this workspace. From here you can create new projects, rename them inline, assign a color, and delete them. * **LLM Models**: manage which LLM models are available to projects in this workspace. * **Integrations**: connect Git providers and ticket trackers. * **Context Parameters**: workspace-level parameter definitions and the values set on any scope. See [Context Parameters](/docs/reference/context-parameters). * **Context Map**: a workspace-wide view of repository correlations. See [Context Map](/docs/repositories/context-map). * **Security**: Users, Teams, Roles, and API Tokens. * **Usage & Billing**: view usage and manage billing details. ## Project-level navigation When you select a project from the sidebar's project picker, the URL becomes project-scoped (`/:workspace/:project/...`) and the sidebar changes to show the work that happens inside that project: * **Dashboard**: project-level overview. * **Playground** and **Logs**: run work and review runs inside this project. * **MCP Servers**, **Skills**, **Agent Roles**: the project-owned part of this project's agent harness. Agents can also attach MCP servers and skills from the Workspace Library, and workflows can run Library agents. * **Workflows**: workflows that orchestrate those agents. * **Orchestrations**: goal-driven coordination of one item across approved workflows. See [Orchestrations](/docs/orchestrations/overview). * **Project Map**: orchestration view scoped to this project's workflows, agents, and resources. Distinct from the workspace Context Map. * **Project Settings**: repositories, channels, vault, context parameters, and permissions for this project. Covered below. ## Switching and managing projects Projects are managed in two places: * **Sidebar project picker**: at the top of the workspace sidebar. Use it to switch between projects, open the **Workspace Library**, jump to a project's settings, or create a new project inline. It also links to the workspace **Projects** page for full management. The Library holds shared resources and templates but does not run workflows or orchestrations. * **Workspace → Projects**: the management page where you create, rename (inline), assign colors, and delete projects. ### Project deletion Deleting a project is destructive. It removes the project's entire harness (agent roles, skills, MCP servers, vault secrets), its workflows, and its run history. To prevent accidents, the delete dialog requires you to **type the project's name** before the action is allowed. ## Project Settings Project Settings are where the team that owns the project shapes its harness: which repositories it can see, which secrets and context parameters it can use, and who's allowed to edit it. Each project has its own settings page at `Project → Project Settings` with six tabs: | Tab | What it controls | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **General** | Project name and color. | | **Project Repositories** | Which workspace repositories this project can use, either all of them or a selected subset. See below. | | **Project Channels** | Which Slack channels this project can use for triggers and agent messaging. See [Slack integration](/docs/integrations/slack). | | **Project Vault** | Secrets owned by this project. See [Vault](/docs/reference/vault). | | **Context Parameters** | The project's own values for context parameters, and definitions that exist only inside this project. See [Context Parameters](/docs/reference/context-parameters). | | **Permissions** | Which workspace teams can access and edit this project, and at what role. | ### Project Repositories Each project either uses every repository connected to the workspace, or only a chosen subset. The toggle is **Allow access to all repositories** on the **Project Repositories** tab. * **Allow all on**: workflows, agents, and triggers in this project can run against any repository connected to the workspace. Use this when projects share the same codebase pool and the project boundary is about workflows and people, not repos. * **Allow all off**: pick specific repositories. Workflows, triggers, and repository-aware steps in this project will only see those repositories. Use this when a project should be hard-isolated from unrelated codebases, common when one workspace serves multiple products or business units. ### Project Vault The Project Vault is where you store credentials that the project's workflows, agents, and MCP servers need at execution time: API keys, tokens, database passwords. Secrets are encrypted at rest and injected as environment variables into the execution sandbox; they are never sent to the LLM. See [Vault](/docs/reference/vault) for the full reference. Secrets that several projects share live in the **Library Vault** of the [Workspace Library](/docs/reference/workspace-library). A project secret with the same name as a Library secret wins in that project's runs. ### Context Parameters The **Context Parameters** tab has two parts. **Project Values** sets this project's values for parameters defined at the workspace level, such as the base branch every workflow in this project should use. **Project Context Parameters** holds definitions that exist only inside this project. See [Context Parameters](/docs/reference/context-parameters) for how values resolve. ### Permissions Each project is owned by the teams granted access to it. Permissions are layered: a user must be a member of the workspace, and that membership must include access to the project. On the **Permissions** tab you assign workspace teams to the project and pick the role each team gets here, typically letting a team edit its own project without touching anyone else's. A project-level team assignment does not automatically grant access to another project. Workspace-level permissions are additive. Teams whose roles already grant a permission at the workspace level (set under **Workspace → Security → Teams** and **Roles**) carry that permission into every project automatically. Per-project assignments on this tab grant access on top of those workspace-wide grants. ## Common patterns * **One product, one project.** Smallest setup. One team, one set of secrets, one set of agents and skills. * **One product, multiple environments.** Use separate projects per environment (e.g. `staging`, `production`) when each environment needs different credentials, different repository scopes, or different teams reviewing runs, even when the setup is otherwise similar. * **Platform team + product teams.** Workspace administrators manage the shared substrate (integrations, models, the Workspace Library). Each product team owns its own project, with its own workflows, repositories, and vault, and attaches shared MCP servers, skills, and agents from the Library. * **Agency / multi-tenant.** One project per client, each isolated: separate repositories, separate vault, separate permissions. Workspace-level integrations and Library tooling stay shared. For choosing between sharing, copying, and scoping, see [Reuse Across Projects](/docs/concepts/reuse-across-projects). ## Related * [Reuse Across Projects](/docs/concepts/reuse-across-projects): sharing, copying, and scoping between projects. * [Workspace Library](/docs/reference/workspace-library): shared resources and templates. * [Context Parameters](/docs/reference/context-parameters): values that differ per scope. * [Workspace Settings](/docs/reference/workspace-settings): workspace-level configuration. * [Vault](/docs/reference/vault): Project Vault and Library Vault reference. * [Context Map](/docs/repositories/context-map): workspace-wide repository correlations. * [Repositories](/docs/get-started/repositories): connect repositories to the workspace. # Reuse Across Projects Source: https://docs.overcut.ai/docs/concepts/reuse-across-projects Pick the right way to share an agent, tool, workflow, or value between projects: Workspace Library, context parameters, Playbooks, or file import. Projects keep each agent harness narrow, and that isolation is what makes runs predictable. It also means the second project that needs the same code reviewer, the same Datadog server, or the same pull request workflow gets a copy. Overcut has several ways to reuse work across projects, and each one answers a different question. This page tells you which one to reach for. ## When copies become a problem Two teams want the same code review workflow, but one of their repositories uses `develop` as its base branch. A platform team maintains a Sentry MCP server and three product teams each keep their own copy with their own API key. An orchestration for the mobile project is identical to the web one except for a branch suffix. A copy diverges the day it is made. Fixes land in one copy and not the others, credentials multiply, and nobody can say which version is current. The mechanisms below exist so that the thing that is actually the same is defined once, and only the thing that differs is set per project, repository, workflow, orchestration, or agent. ## Shared, copied, or scoped Three words describe every mechanism: * **Shared** means one resource that lives in the Workspace Library and is referenced from projects. There is one owner, one place to edit, and a change reaches every project at once. Agents, MCP servers, skills, and secrets are shared. * **Copied** means a project receives its own independent definition. Later edits to the source do not flow to the copy, and edits to the copy do not flow back. Library templates, Playbooks, and imported files are copied. * **Scoped** means one definition with values that differ by where a run happens. A context parameter is defined once and resolved per run from the most specific value on that run's path. Slack channels, runs, history, and anything you create inside a project without promoting it stay project-owned. Repositories belong to the workspace, and each project attaches the subset it uses. See [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces) for the workspace and project boundary. ## The reuse mechanisms | Mechanism | What is reused | How a project gets it | What happens on later edits | Pick it when | | ------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | **Library resource** (agent, MCP server, skill, secret) | The resource itself | Attach it by reference from any project | Edit it once in the Library; every project sees the change | The same tool or role should behave identically everywhere | | **Library template** (workflow, orchestration) | A starting definition | **Install from Library** creates a project-owned copy | Copies are independent | Each team needs its own runnable, editable version | | **Context parameter** | One definition, one value per scope | Reference `{{params.}}` and set values per project, repository, workflow, orchestration, or agent | A value change applies to the next run, with no publish | The definition is identical and only a value differs | | **Playbook** | A curated public template | **Add from Playbook** | Copies are independent | You are starting from a common pattern rather than from your own workflow | | **File export and import** | A JSON snapshot of one workflow | **Import from File** | Copies are independent | You share with one other project or workspace, or keep a backup in version control | | **Repository custom instructions** | Ambient guidance about one codebase | Applied automatically to runs on that repository | Edit it on the repository | The agent should always know it about the repository, and no instruction needs to place it inline | [Workspace Library](/docs/reference/workspace-library) and [Context Parameters](/docs/reference/context-parameters) cover every control for the first three. Playbooks and file import are covered in [Overcut Playbooks](/docs/quick-starts/playbooks) and [Import & Export Workflows](/docs/workflows/workflow-import-export). ## How the mechanisms combine The Library and context parameters are designed to be used together. * **A Library template can reference `{{params.}}`.** Define that key at the workspace level. A project-level definition is not visible to the project that installs the copy, so the installed workflow fails to publish there until the key exists. * **The Library defines no context parameters of its own.** It holds shared resources and templates. Set values on the projects, repositories, workflows, orchestrations, and agents that run, including Library agents. * **Values set on a Library agent travel with it.** An agent-level value applies wherever that agent runs, in every project that uses it. Only workspace parameters can be set on a Library agent; a project parameter cannot. * **A project secret beats a Library secret with the same name.** Use this when a project needs its own credential for a shared MCP server: keep the Library secret for everyone else and add a same-name secret to the Project Vault. * **Playbooks can seed the Library.** Add a Playbook inside the Workspace Library to turn a public template into a private one that your projects install from. ## Common patterns * **Platform team and product teams.** The platform team owns the Workspace Library: shared MCP servers with their secrets, shared skills, and a few reviewed agents. Product teams attach those by reference and keep their own workflows, repositories, and channels. * **One workflow, many repositories.** One published workflow with a `base_branch` context parameter. The workspace default is `main`; two legacy repositories set `develop`. See the quick start [Reuse a Workflow Across Repositories](/docs/quick-starts/reuse-a-workflow-across-repositories). * **One template, many teams.** Author the workflow in the Library, publish it, and let each team install a copy. Put the values that should stay centrally managed into context parameters so the copies do not need to change when a convention changes. * **Two orchestrations, one difference.** Two orchestrations run the same workflows with a different branch suffix or marker comment. Set the value on each orchestration instead of copying the workflows. ## Related * [Workspace Library](/docs/reference/workspace-library): shared resources, promotion, and template installation. * [Context Parameters](/docs/reference/context-parameters): definitions, scoped values, preview, and runtime resolution. * [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces): what lives at the workspace and what lives in a project. * [Overcut Playbooks](/docs/quick-starts/playbooks): the public template catalog. * [Import & Export Workflows](/docs/workflows/workflow-import-export): JSON snapshots of a workflow. # Connect Your Coding Agent Source: https://docs.overcut.ai/docs/get-started/connect-your-coding-agent Build and run your software factory from the coding agent you already use, without leaving your IDE or terminal. Your coding agent is where you already think, plan, and ship. Overcut meets you there. Connect Claude Code, Cursor, Codex, or any MCP-capable agent to your Overcut account, and it becomes the front door to your software factory: the same agent that edits your code can connect your Git provider, register repositories, design and publish workflows, and check on runs, all in conversation and all headless. That changes how the platform fits into your day: * **Stay in your agent.** No context switch to a web app to set things up. Describe what you want automated and let the agent do the configuration, with you approving each meaningful step. * **Build the factory from your IDE.** The agent reads the repository in front of you (stack, test commands, CI, contribution rules) and proposes workflows that fit it, then tailors, dry-runs, and publishes them. * **Monitor without leaving.** Ask the agent why a run failed, what a workflow is waiting on, or what triggered last night, and it queries Overcut for the answer. * **Scale the same way.** Everything the agent does runs as you, inside your workspace's permissions, secrets, approvals, and audit trail. Repeat it across every repository your team owns. One command sets this up. The rest of this page walks through it. You need: * Node.js 20 or newer * An Overcut account, or permission to create one during sign-in * A supported coding agent installed on your machine * A local checkout of the repository you want to set up ## Install and sign in From a terminal, run: ```sh theme={"dark"} npx overcut init ``` The CLI opens your browser to sign in (or sign up) if you have no session, then detects the coding agents installed on your machine and connects them to Overcut. For an SSH or headless session, run `npx overcut login --no-browser` first and follow the printed URL and code. If you belong to more than one workspace, the CLI asks `Which workspace should be the current one?` and confirms `Current workspace: `. If several agents are detected, the CLI asks `Which coding agent should get the Overcut MCP server?` Pick one or **All detected**. It then prints each configured host. ```sh theme={"dark"} npx overcut whoami ``` Shows the signed-in user, current workspace, and server. The web app offers the same command: select **Connect your coding agent** in the sidebar footer, or the **Build with your agent** card, to copy it. ## Set up a repository with your agent Start (or restart) your connected coding agent inside the local repository you want to configure. Ask the agent: > Set up Overcut for this repo. The agent loads Overcut's setup guide and inspects the repository: Git remote, default branch, language, package manager, test and lint commands, CI configuration, and contribution files. The agent uses the single project in a new workspace, asks you to choose when several exist, or offers to create one. If the repository's Git provider is not connected yet, the agent gives you a link to connect it in the web app. Complete the authorization in the browser. Never give credentials or secrets to the agent. The agent finds the matching remote repository, registers it, and activates it. It asks before registering an uncertain match. Code indexing stays off; enable it separately if you want it. See [Repositories](/docs/get-started/repositories). The agent proposes one to three workflows that fit the repository. Pick one. The agent installs and tailors it, runs it as a draft, and summarizes the result. The agent publishes the workflow and activates its triggers only after you agree, then tells you what will trigger it and where to see runs. Review every change the agent proposes. Destructive actions (delete, deactivate, discard) are refused by Overcut until the agent asks for your agreement and retries with confirmation. If the workspace already has repositories and active workflows, the agent summarizes them and asks what you want to add instead of repeating setup. ## Manage the connection Rerun the agent connection at any time, for example after installing a new coding agent: | Goal | Command | | ----------------------------------------------------- | --------------------------------------- | | Reconnect detected agents | `npx overcut mcp` | | Configure a specific agent | `npx overcut mcp --host claude-code` | | Configure every detected agent without a prompt | `npx overcut mcp --all` | | Print the configuration block instead of writing it | `npx overcut mcp --print` | | Configure and launch the agent (Claude Code or Codex) | `npx overcut mcp --host codex --launch` | Supported agents include Claude Code, Cursor, Codex, Windsurf, VS Code, Zed, and Gemini CLI. The CLI writes to the agent's **user-level** configuration only, so the connection works across all your repositories and is never committed with a project. Each connected agent gets its own API token, named for the agent and machine. Rerunning `overcut mcp` rotates it. `overcut logout` ends your terminal session, revokes the tokens created on this machine, and removes the Overcut entry from each agent's configuration. Tokens also appear under **Workspace Settings → Security → API Tokens**, where you can revoke them. The configuration printed by `--print` contains a bearer token with your permissions. Treat it like a password: never paste it into chat, commit it, or save it in a project-level file. ### CI and scripts Create a general-purpose token for automation with `npx overcut token create ` (printed once; manage with `token list` and `token revoke `). Set it as `OVERCUT_API_TOKEN` and no login is needed. Add `--json` to any command for machine-readable output. ### On-premises deployments Pass your server's GraphQL URL with `--url`, or set `OVERCUT_API_URL`: ```sh theme={"dark"} npx overcut init --url https://overcut.example.com/graphql ``` ## Troubleshooting * **No agent detected:** run `npx overcut mcp --host `, or use `--print` and add the block to your agent's user-level MCP configuration. * **The agent cannot see Overcut:** restart the agent after configuration and check `npx overcut whoami`. * **CLI login or the MCP endpoint is unavailable on an on-premises server:** ask your administrator to enable it or upgrade the deployment. For CI, use `OVERCUT_API_TOKEN`. ## Related * [Overcut Skills](/docs/quick-starts/overcut-skills): installable `SKILL.md` guidance for agents, including the direct GraphQL API skill. * [MCP Servers](/docs/reference/mcp-servers): give agents running inside Overcut access to third-party tools. This is different from the connection described here. # Product Overview Source: https://docs.overcut.ai/docs/get-started/product-overview A deeper tour of Overcut, the control plane for your software factory. Overcut is the **control plane for your software factory**: a managed platform for running production-grade engineering automations across your Git, ticketing, and CI tools. It runs the agentic SDLC end to end, from the event that starts the work to the pull request, ticket, or message that closes it. This page is the deeper feature tour. For a one-page orientation to the platform, see [Welcome to Overcut](/welcome). Compose workflows and orchestrations from triggers, agents, code actions, and approvals, and give agents skills, MCP servers, and repository context. Follow every run in real time, inspect inputs and outputs, and track token usage per workflow. Scope what agents can touch, keep secrets in a vault, put humans on the approval gates, and keep a full audit trail. Let retrospectives turn past runs into workflow memories so every workflow gets sharper the longer it runs. ## Visual Workflow Automation *Slash lead-time and minimise human error by turning fragile, hand-rolled scripts into repeatable, governed workflows.* * **Drag-and-drop builder**: compose end-to-end workflows with triggers, AI agents, code actions, and approvals. * **Orchestrations**: coordinate a work item across approved workflows until a goal is complete. See [Orchestrations](/docs/orchestrations/overview). * **Execution monitor**: follow every run in real time, inspect inputs/outputs, and retry failed steps. * **Reusable templates**: start quickly with community and in-house workflow templates. ## AI Agent Platform *Multiply developer productivity without hiring by embedding domain expertise into reusable AI agents that run 24 × 7.* * **Stateful agents** that can plan, reason, and call tools. * **Multi-Model support** with option for "Bring Your Own Model" (BYOM). * **Built-in specialist agents** for code review, technical writing, product planning, and more. * **Reusable skills** that teams can add from connected repositories so they can package guidance once and apply it to the right agents. * **A Workspace Library** of shared agents, MCP servers, skills, secrets, and templates that every project can reuse, plus **context parameters** so one workflow serves many repositories and teams. * **Isolated Agent Clients** for running agents safely and securely. ## Developer-Centric Tooling *Reduce context-switching and onboarding time by connecting the tools your team already uses and extending agents when you need more coverage.* * **Native workspace integrations first**: connect supported providers such as GitHub, GitLab, Bitbucket, Jira, Azure DevOps, Linear, ClickUp, and Slack directly in Overcut so built-in tools work across code, tickets, and chat. * **MCP for external tools**: extend agents with MCP servers when you want to connect third-party systems or custom services that do not have native workspace support. * **Flexible connection strategy**: combine native integrations with MCP when you need extra external capabilities alongside your primary workspace connections. * **Unified developer experience**: single interface for code reviews, ticket management, chat-driven workflows, and external tool access. * **Chat interface**: task Overcut via chat with anything you can do in the UI, from triggering workflows to reading execution logs. See [Chat with Overcut](/docs/how-to/chat-with-overcut). * **Share Feedback**: open the workspace help menu to send product feedback, feature requests, testimonials, or success stories through the [Feedback chat guide](/docs/how-to/feedback-chat). * **Reduced onboarding friction**: new team members can start contributing immediately with pre-configured agent workflows. * **Context-aware automation**: agents understand your project structure and can work across multiple tools intelligently. See the [Integrations overview](/docs/integrations/overview) for connection-path guidance and [MCP Servers](/docs/reference/mcp-servers) for MCP setup details. ## Source-Control & Multi-Repo Automation *Enforce consistent standards across hundreds of repositories without additional headcount or brittle scripting.* * **Unified Git provider registry** supporting GitHub, GitLab, Bitbucket, Azure DevOps, and AWS CodeCommit. * **Enhanced cloning** with shallow, sparse, and cached clones to keep workflows fast. * **Automatic repository mapping** so every workflow knows which repositories should be handled per each ticket. * **Code Indexing**: Enable semantic code search to help agents find relevant context faster. ## Issue & Ticket Workflows *Gain real-time visibility and shorter cycle times by automating ticket flow between product, engineering, and ops.* Kick off workflows from issue events, slash-commands, or manual triggers, and let agents update or create follow-up tickets automatically. ## Containerised Development Environments *Eliminate “works on my machine” delays and cut CI minutes by provisioning identical, cacheable dev environments.* Generate dev-containers and Docker images straight from your repo so every workflow runs in the same repeatable environment. ## Observability & Monitoring *Detect anomalies before they become incidents, reducing downtime and safeguarding customer trust.* * **Real-time run tracking UI**: monitor workflow execution with structured logs for immediate visibility. * **Centralized monitoring dashboard**: unified view of all workflow health, performance metrics, and system status across your organization. *** 💡 **Next steps**\ Check out the [Quick Starts](/docs/quick-starts) to see Overcut in action, or head to the [Get Started with Repositories](/docs/get-started/repositories) guide to connect your first repo. # Repositories Source: https://docs.overcut.ai/docs/get-started/repositories Connect a Git provider, register and activate repositories, and optionally enable code indexing. Repositories define where Overcut receives events and runs automations. Only events from **active** repositories are processed, so connecting a provider is just the first stage. Getting a repository ready takes four steps, in order: 1. **Connect the Git provider** to your workspace. 2. **Grant repository access** in the provider, which decides what Overcut can see. 3. **Register** the repositories you want in Overcut. 4. Make them **Active** so they receive events and are available to projects. Code indexing is a separate, optional step. ## Connect the Git provider In your workspace, open **Integrations**. Select **Add Provider**, choose your Git provider, and complete its authorization flow. The organization or instance then appears under **Integrations**. See [Connect a provider](/docs/integrations/overview#connect-a-provider) and the provider guides for details. ## Grant provider-side repository access Overcut can only offer repositories that the authorized account, app installation, or provider connection can access. For GitHub Cloud, this is the GitHub App's repository access: **All repositories** or **Only select repositories**. You can change it later from the installation's **Configure** page in GitHub. ## Register repositories in Overcut In **Integrations**, select the connected organization or provider instance that contains the repositories you want to add. Select **Add Repositories**. GitLab uses its own terminology, so select **Add Projects** for a GitLab connection. Select one or more repositories. Repositories that are already registered are not listed. Select **Add Selected Repositories**. For GitLab, select **Add Selected Projects**. ## Activate repositories Each registered repository has a separate **Active** or **Inactive** state. Open the repository under its connected provider in **Integrations**, then use the state control beside the repository name. * **Active** repositories receive events and participate in automations. * **Inactive** repositories are ignored until you reactivate them. * Only active repositories can be assigned to a project. A project can further limit which active repositories its workflows and agents may use. Open **Project Settings > Project Repositories** to allow all active workspace repositories or select a subset. See [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces) for the project-scoping model. ## Optionally enable code indexing Code indexing gives agents a semantic search tool so they can find code by meaning rather than keywords. It is off by default. To turn it on, open the repository's settings and turn on **Enable Code Indexing**. Semantic search is optional. Agents work without it using file search, grep, and glob patterns; indexing is an enhancement, not a requirement. See [Repository Code Indexing](/docs/repositories/repository-indexing) for prerequisites and operation details. ## Troubleshoot a repository that does not appear * **Check provider-side access.** Confirm that the authorized account or app installation can access the repository. For GitHub Cloud, review whether the app has access to all repositories or only selected repositories. * **Check the connection.** Confirm that you opened the correct connected organization or provider instance in **Integrations**. * **Check whether it is already registered.** The **Add Repositories** selector excludes registered repositories. Look for the repository under its connected provider instead. * **Check its activation state.** A registered repository can still be **Inactive**. Open its repository page and reactivate it. ## Discover skills from registered repositories Registered repositories can surface reusable skills for your team. This helps you turn repository guidance into shared project skills instead of repeating the same instructions across individual agents. When you open the project-level **Skills** area and choose to add a skill, Overcut lets you scan registered repositories for reusable skills your workspace can access. From there, your team can: * Browse available skills from registered repositories * Preview a skill's `SKILL.md` instructions before adding it to the project * Confirm where a skill comes from so you can choose the right one for the project If a repository is not registered in your workspace, its skills are not available to add. Use registered repositories to centralize reusable guidance for your team. After you add a skill at the project level, you can assign it to the agents that need it. ## Configure a repository for agent runs Once your repository is registered, workspace admins can tailor the agent environment, instructions, and commands for that repository. In **Integrations**, open the connected provider and select the repository. Select the container environment agents use for this repository. The **Default Image** suits most stacks, while **Universal 6** provides a newer toolchain for repositories that need more recent language or runtime versions. Workspaces on an Enterprise plan can also select a custom image registered from their own registry. See [Repository Agent Image](/docs/repositories/agent-image) for the full comparison. Provide any custom workflow steps, environment setup, or compliance requirements in Markdown or YAML. Examples include pre-commit hooks, build steps, environment setup, and compliance checks. Specify repository-specific commands for tasks such as install, lint, test, or build. If your workspace uses ticket repositories, link them to related code repositories from the ticket repository page. See [Repository Mapping](/docs/repositories/repository-mapping) for details. Use the repository's **Context Parameters** panel to set values that runs on this repository should use. See [Context Parameters](/docs/reference/context-parameters). Save your changes to apply the configuration. ## Next steps Learn about [Repository Mapping](/docs/repositories/repository-mapping) to connect ticket repositories to code repositories and help workflows identify relevant repositories. # Why Overcut Source: https://docs.overcut.ai/docs/get-started/why-overcut How Overcut compares as the foundation for a software factory: open on every axis, complete across the delivery loop, and built to be operated by a large engineering organization. Every engineering organization is now building a software factory: agents that pick up tickets, write and review code, keep documentation current, and respond to incidents. The open question is what to build it on. Whatever you choose anchors the workflows, skills, memories, and policies your teams accumulate on top of it, which makes it the hardest decision to undo later. This page lays out the advantages of Overcut for an organization making that choice, grouped under the three questions worth asking of any platform: what it locks you to, whether it runs the whole factory or one station, and whether your organization can operate it. ## The paths most teams are weighing Most evaluations come down to one of three paths, each with a gap. * **Assemble it yourself** from a coding agent, CI jobs, and scripts. You keep full control, and you also own the governance, sandboxing, observability, and memory layers that a factory needs and a coding agent does not provide. * **Adopt your Git host's or model vendor's agent platform.** You start fast, and the factory is tied to that host or that model family for as long as it exists. * **Buy a closed agent product.** You get a strong agent and someone else's opinion of how your delivery process should work, with the model, runtime, and often the hosting fixed by the vendor. Overcut is a fourth path: build your own factory on a platform that does not own your choices. The Git host, ticket system, model, harness, and deployment target are all configuration. The delivery loop is covered end to end. And the whole thing runs inside boundaries your administrators define. Vendor, model, harness, and deployment stay your decision. One platform from trigger to write-back, with agents working as teammates in your tickets and pull requests. Governance, scale, and administration for many teams. ## What does it lock you to? The parts underneath a software factory will change. Models improve every quarter, agent runtimes are consolidating, and Git hosts and hosting requirements shift with acquisitions and compliance reviews. Overcut is designed so that each of these can change without rebuilding what sits on top. ### Vendor agnostic Overcut connects natively to GitHub, GitLab (including self-managed instances), Bitbucket Cloud, Bitbucket Server / Data Center, and Azure DevOps for code, and to Jira (Cloud and Server / Data Center), Linear, ClickUp, and Azure DevOps work items for tickets. Slack brings the factory into team chat. Events from all of them are normalized into the same [trigger types and conditions](/docs/workflows/triggers), so a pull request review workflow behaves the same whether the pull request came from GitHub or Azure DevOps. Organizations that run more than one host, or that expect to migrate, keep one set of workflows. See the [Integrations overview](/docs/integrations/overview). ### Model agnostic Overcut ships with system-managed models so teams can start without credentials, and accepts your own keys for OpenAI, Azure OpenAI, Anthropic, AWS Bedrock, and OpenRouter, which also opens up open-weight models. Models you host yourself, or route through a gateway such as LiteLLM, connect through a custom **Base URL** on an OpenAI-compatible or Anthropic-compatible endpoint. The choice is made per agent, not per platform. A triage step can run on a fast, inexpensive model while the implementation step that follows runs on a stronger one. Defaults cascade from workspace to workflow to agent, so an administrator can pin the workspace to an approved model or region and let workflow owners override only where they need to. **Test Model** confirms the connection and detects tool calling, vision, and other capabilities before a run depends on them. See [LLM Models](/docs/reference/llm-models). ### Harness agnostic The harness is everything in an agent except the model: the loop that sends prompts, executes tools, and decides when the task is done. Overcut ships two, chosen per step in the Workflow Builder under **Execution Engine**. **Overcut** runs Overcut's own agent runtime and accepts every model provider on the LLM Models page. **Claude** runs Anthropic's Claude Agent SDK, the same runtime behind Claude Code, with Anthropic, AWS Bedrock, or any Anthropic-compatible gateway. The agent definition does not depend on the engine. Instructions, sub-agents, Skills, MCP servers, secrets, the repository checkout, and Overcut's integration tools carry over, and one workflow can mix engines across its steps. When a better runtime appears, you change a dropdown instead of rewriting the agent. See [Execution Engines](/docs/concepts/execution-engines). The same openness applies to how your engineers work with Overcut. They can [connect Claude Code, Cursor, Codex, or any MCP-capable coding agent](/docs/get-started/connect-your-coding-agent) and use it to register repositories, publish workflows, and check on runs without leaving their terminal. ### Deploy anywhere Overcut is available as a hosted service and as a customer-managed deployment that installs into your own Kubernetes cluster, in a private cloud or on-premises, with a published [release and vulnerability management lifecycle](/docs/vulnerability-management). The distinction that matters for regulated teams is what stays inside your boundary. Many hosted agent platforms run a sandbox on your side while the agent loop, the model calls, or both stay on the vendor's side. In a customer-managed Overcut deployment, the control plane, the workflow engine, and the execution sandboxes all run in your environment, and models are reached through your own keys and endpoints. Bitbucket Server / Data Center and Jira Server / Data Center connect directly from that deployment. On Overcut Cloud, repositories and tickets are fetched just in time with scoped, time-limited tokens, every execution runs in an isolated sandbox that is torn down afterwards, and the default models run on Overcut-managed Azure OpenAI with no training on your data and regional residency. See [Privacy & Security](/docs/privacy-and-security) and [Network Allowlisting](/docs/network-allowlisting). ## Does it run the whole factory or one station? A factory made of point solutions has a coding tool, a review tool, a documentation tool, and a chat bot, each with its own permissions, logs, and billing, and nothing that carries a work item from one to the next. Overcut is one platform for the loop, and the people in the loop take part from the tools they already have open. ### End-to-end SDLC * **Workflows** start from an event, run agent steps and code actions, and write results back to the ticket, pull request, or channel. You build them three ways: visually in the [Workflow Builder](/docs/how-to/workflow-builder), by describing what you want in [Overcut chat](/docs/how-to/chat-with-overcut), or headless from [your own coding agent](/docs/get-started/connect-your-coding-agent). Either way they are versioned and can be [exported or imported](/docs/workflows/workflow-import-export) as files. * **Orchestrations** coordinate a work item across several approved workflows until a goal is complete, with a person deciding at each gated step. See [Orchestrations](/docs/orchestrations/overview). * **Retrospectives** review completed runs and write [workflow memories](/docs/how-to/workflows/workflow-memory) back to the agents, so a workflow stops repeating the same mistake and picks up the conventions specific to your team. See [Workflow Self-Improvement](/docs/how-to/workflows/workflow-self-improvement). * **Built-in base agents** (Senior Developer, Code Reviewer, Tech Writer, Product Manager) ship with role instructions and toolsets ready to specialize, and every run is visible live with structured logs. See [Base Agents](/docs/reference/base-agents). ### Native SDLC integration Work starts where it already lives, not in a separate console. | Source | What can start a workflow | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Tickets | Issue and work item creation, labels, edits, status changes, and comments | | Pull requests | Creation, updates, review activity, comments, and merges | | CI/CD | CI workflow events (queued, started, completed, failed, cancelled, timed out), and workflows can also run [external pipelines](/docs/workflows/ci-execute-workflow) as a step | | Chat | Slack mentions, slash commands, and messages in watched channels, including alerts posted by monitoring bots | | Anything else | [Custom Events](/docs/integrations/custom-events): a webhook URL any system can call, such as a monitoring tool or an internal script, plus [schedules](/docs/workflows/scheduled-workflows) and manual runs | Results are written back the same way: a comment on the ticket, a pull request with a review, a message in the thread that asked. ### Agents as teammates, not a separate tool Overcut's agents live inside the tickets, pull requests, and channels your team already works in, and they behave like another member of the team. * **Output arrives as comments.** An agent reports its findings as a comment on the ticket, a review on the pull request, or a reply in the Slack thread, in the same place and format a colleague would use. Nobody opens a separate console to see what the agent did. * **Anyone replies natively.** Mention `@overcut`, type a slash command, or reply on the thread, and the agent picks it up. [Interactive sessions](/docs/reference/interactive-sessions) keep the conversation context across comments, so a follow-up question continues the same task instead of starting over. See [Trigger with Slash Command](/docs/workflows/trigger-with-slash-command). * **The whole organization takes part.** Developers, product managers, QA, and management each work with agents from the tool they already use. A product manager can approve an orchestration step by replying on the Jira ticket, and QA can ask for a change on the pull request, without any of them installing anything. * **Agents run in the background.** Work starts from an event or a schedule and runs in an isolated sandbox on Overcut's side. No IDE has to stay open and no laptop has to stay on. You check on a run in monitoring, or ask about it in [Overcut chat](/docs/how-to/chat-with-overcut). ### Fully customizable Overcut supplies the platform. Your organization supplies the process. * **Agent Roles** with hand-picked tools and instructions. See [Base Agents](/docs/reference/base-agents). * **Skills** that package procedures once and are versioned alongside the code they describe. See [Skills](/docs/reference/skills). * **MCP Servers** for any system without a native connection, with an allowed-tool list per server. See [MCP Servers](/docs/reference/mcp-servers). * **Agent Images** for bringing your own container image with the toolchain your repositories need. See [Agent Images](/docs/reference/agent-images). * **Workflows and orchestrations** you build visually, and a [Playbook Catalog](/docs/quick-starts/playbooks) so teams start from a working pattern rather than a blank canvas. * **Custom Events** and [Context Parameters](/docs/reference/context-parameters) so one workflow serves many repositories, teams, and processes. ## Can your organization operate it? A factory that only its builders can run does not scale past one team. Overcut is built to be administered centrally and used by many teams at once. ### Governance and control Every agent action runs inside a permission boundary an administrator defined, and every change to that boundary is recorded. * **Roles and teams.** Roles carry granular permissions and are assigned through teams, at the workspace level and per project. Overcut ships defaults such as **Admins**, **Workflow Builders**, **Integration Managers**, **Repository Managers**, and **Workflow Run Viewers**, and you can define your own. See [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces#permissions). * **Single sign-on.** SAML and OIDC identity providers, with users routed by email domain and optional automatic joining. Request it from the workspace **Security** settings with **Ask to add SSO**. * **Scoped access.** Each project defines which repositories, Agent Roles, Skills, MCP servers, and [Vault](/docs/reference/vault) secrets its agents can reach. Secrets are encrypted at rest and never sent to the model. * **Approval gates.** Orchestrations pause with status **Waiting on human** before a gated workflow runs or a goal is marked complete, and only an explicit reply from a person lets them continue. The reply and the login behind it are recorded. See [Approvals and Discussions](/docs/orchestrations/approvals-and-discussions). * **Audit Trail.** An append-only record of who created, changed, or removed which resource, with a field-level before and after diff and secret values redacted before the event is written. See [Audit Trail](/docs/reference/audit-trail). * **Observability and spend.** Follow every run live with structured logs, and break token usage down by model, workflow, and agent. See [Token Usage Analytics](/docs/workflows/token-usage-analytics). ### Enterprise scale A workspace holds many projects, and each project is a bounded scope with its own agent harness owned by one team. What should be shared stays shared: billing, integrations, LLM models, teams, and the Workspace Library. * **Workspace Library.** Platform teams publish Agent Roles, Skills, MCP Servers, Workflow Templates, Orchestration Templates, and secrets once. Projects attach them by reference, so a fix in the Library reaches every project. See [Workspace Library](/docs/reference/workspace-library) and [Reuse Across Projects](/docs/concepts/reuse-across-projects). * **Central administration.** Projects, security, Audit Trail, and usage and billing are managed in one place, with per-project team assignments layered on top of workspace-wide roles. * **Isolation by default.** Every run gets its own sandbox, and a project's agents see only the repositories and tools that project attached. See [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces). ## What you keep when things change The value of a foundation shows when something underneath it moves. This is what stays intact in Overcut when it does. | When this changes | What stays the same | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | The model you standardize on | Every agent, workflow, skill, and memory. You reassign the model or change the workspace default. | | The agent runtime | The agent definition, its tools, skills, MCP servers, and secrets. You switch the **Execution Engine** on the step. | | Your Git host or ticket system | The workflows and their triggers, because events are normalized across providers. You connect the new provider and map the repositories. | | Where you are allowed to run it | The same product, from Overcut Cloud to a customer-managed cluster in your own network. | | How your teams are organized | Library resources and workspace roles. You add projects and assign teams without duplicating agents or policies. | ## Where to go next * [Product Overview](/docs/get-started/product-overview) for the feature-by-feature tour. * [Building Blocks](/docs/building-blocks) for the vocabulary: workspaces, projects, agents, workflows, orchestrations. * [Quick Starts](/docs/quick-starts) to build your first workflow. # Chat with Overcut Source: https://docs.overcut.ai/docs/how-to/chat-with-overcut Task Overcut via chat: ask questions, trigger and inspect workflows, and manage your project setup conversationally. Overcut includes a chat interface, so you can work with the platform conversationally. Anything you can do in the Overcut UI, you can ask Overcut to do via chat: explain a workflow, trigger a run, read execution logs, or set up agents, skills, and MCP servers. Select **Assistant** in the project sidebar to open the full-page chat. You can also pop the chat out into a floating panel or dock it to the side of the screen and keep the conversation going while you work. Overcut chat acts as you. Everything it does runs with your own user permissions, so it can only see and change what your workspace role allows. ## What you can and cannot do via chat Chat covers the Overcut platform itself: if you can see it or configure it in the UI, you can ask for it in chat. For example, you can ask Overcut to: * Explain, create, and edit workflows, and trigger workflow runs * Read executions and logs, and explain why a run failed * Create and configure agents, and assign skills and MCP servers to them * Register project skills, install MCP servers, and manage project secrets * Configure repositories, channels, custom-event webhooks, and orchestrations * Manage context parameters and the Workspace Library Chat does not work directly on your integrated external systems. Overcut will not open a pull request, push code, update a ticket, or post a chat message from the conversation. That work runs through [workflows](/docs/workflows/workflows), with their guardrails, approvals, and settings. Ask Overcut to build or trigger the right workflow instead. ## Write a message When the full-page chat is empty, the input cycles through example prompts to show the kinds of questions and requests you can start with. They are inspiration, not commands: type your own message in your own words. * Press `Enter` to send your message. * Press `Shift+Enter` to add a new line. * The send button stays disabled until your message contains text, so empty messages cannot be sent. ## Ask questions and inspect context Read-only help is available immediately, with no preparation. For example, you can ask Overcut to: * Explain what a workflow does and how it is triggered * Summarize a workflow execution or read its logs to explain why a run failed * List the agents, skills, MCP servers, or repositories configured in the project * Answer questions about how to use the platform Read-only requests never change your project configuration or workflows. If Overcut cannot access the context you are asking about, it tells you what is missing. ## Task Overcut with changes When your request changes something, such as creating a workflow or installing an MCP server, Overcut may pause to prepare before it acts. During that preparation you may see two status messages: * `Loading skill`: Overcut is loading a built-in task skill that provides the guidance and capabilities for your request. * `Equipping tools`: Overcut is enabling the write tools the action needs. Both states are expected behavior, not errors. There is nothing to install or configure; Overcut continues on its own after a short wait, and the loaded capabilities stay available for the rest of the conversation. Built-in task skills are loaded by Overcut during a conversation. They are separate from the repository-backed [Skills](/docs/reference/skills) your team adds to a project and assigns to agents. ## Suggested next messages After Overcut replies, a suggested next message may appear as ghost text in the input. Press `Tab` to accept it, or start typing to replace it with your own message. Suggestions only appear when there is a clear follow-up, so not every reply produces one. ## Conversation history Recent conversations are saved per project, so you can reopen a thread and continue where you left off. History is stored in your browser, and Overcut automatically removes old conversations and caps how many are kept per project, so the oldest threads eventually disappear. ## Confirmations and permissions Preparing capabilities does not bypass safeguards. For sensitive or destructive actions, Overcut asks for confirmation before it continues, and your workspace permissions and approval requirements still apply. If your permissions do not allow an action, Overcut cannot complete it. ## Troubleshooting If a request does not complete, check for these common causes: * **Missing permissions**: your workspace role may not allow the change you asked for. * **Unavailable context**: Overcut may not be able to read the workflow, execution, or resource you referenced. Ask it to inspect the available context first. * **Confirmation pending**: Overcut may be waiting for you to approve a sensitive action. * **Outside chat's scope**: work on external systems, like opening a pull request, belongs in a workflow. Ask Overcut to build or trigger one instead. ## Related documentation * [Workflows](/docs/workflows/workflows) * [Skills](/docs/reference/skills) * [Context Parameters](/docs/reference/context-parameters) * [Workspace Library](/docs/reference/workspace-library) * [Product Overview](/docs/get-started/product-overview) # Workflow Metadata Source: https://docs.overcut.ai/docs/how-to/workflow-builder Configure workflow settings including name, timeout, priority, machine size, default model, and status update behavior. ## Overview Every workflow has a metadata panel that controls execution behavior and communication preferences. This page explains each setting and when to adjust it. Workflow self-improvement settings (retrospective cadence and sample size) are configured from the workflow dashboard, not here. See [Workflow Self-Improvement](/docs/how-to/workflows/workflow-self-improvement) for the full guide. For action-specific setup, use the matching action reference. For example, see [Run Script Action](/docs/workflows/run-script) for **Run Script** fields, environment variables, and output handling. ## Deleting steps and triggers Steps and triggers include a delete action in their headers so you can remove them without leaving the canvas. Use this when you need to retire a step, replace a trigger, or simplify a workflow draft. Select the step on the canvas, then use the delete action in the step header. Select the trigger card, then choose the delete action in the trigger header. Deletes are only available when the step or trigger is selected, so click the card first if you do not see the action. ## Confirmation prompts Deleting a step, trigger, or connection always shows a confirmation dialog. This prevents accidental removal and gives you a final chance to review the change before it applies. If you confirm a delete, the change is immediate and saved with the rest of your draft edits. ## Deleting connections Connections (edges) can be removed directly from the canvas. This is useful when rerouting workflow logic or cleaning up unused paths. Click the connection line to highlight it. Use the delete control that appears on the connection and confirm the prompt. ## Selected connection styling When you select a connection, it changes appearance so you can see exactly which path you are editing. The highlight includes the line and arrowhead, making it easy to distinguish the active connection from the rest of the graph. ## Starting from a playbook Use **Add from Playbook** when you want to start with a ready-made workflow template instead of building from scratch. Workflow Builder opens the full Playbook Catalog so you can browse a larger set of templates before adding one to your workspace. In Workflow Builder, choose **Add from Playbook** to open the Playbook Catalog. Use search to narrow results by name or description, and use workflow-type filters to focus on playbooks for the kind of automation you want to build. Select a playbook to open its preview. The detail modal shows the playbook title, description, a preview of its instructions, and whether it is already installed in your workspace. Install the playbook to add it to your workspace and continue in Workflow Builder, where you can customize the workflow before publishing it. If Overcut finds a matching workflow that is already installed, the preview offers an option to open that existing workflow instead of creating another copy. Use the catalog preview to compare templates before importing one. This helps you confirm the playbook matches your workflow type and setup needs. ## Accessing workflow metadata The metadata panel appears on the right side of Workflow Builder when no step is selected. To open it: 1. Open a workflow in Workflow Builder 2. Click anywhere on the canvas background (not on a step or trigger) 3. The properties panel displays the workflow metadata form Changes auto-save after a brief delay. ## Context Parameters The **Context Parameters** panel in the workflow metadata sets this workflow's values for `{{params.}}` references. Select **Add override**, pick a parameter, and enter the value. Values save immediately and independently of the draft, so you do not publish the workflow for a new value to apply; the next run picks it up. An orchestration that runs this workflow can set a more specific value. See [Context Parameters](/docs/reference/context-parameters) for resolution order and the Playground preview. *** ## Workflow Name The workflow name appears in lists, logs, execution history, and status comments. Choose a descriptive name that helps teammates understand what the workflow does at a glance. **Examples:** * "PR Code Review" * "Bug Triage - Backend" * "Spec Draft for New Features" *** ## Workflow Timeout The maximum time a workflow can run before Overcut terminates it automatically. This acts as a safety limit to stop execution if something goes wrong. **Default:** 60 minutes **Range:** 1 minute or more ### How timeouts work Each step in a workflow has its own timeout, and the workflow timeout covers the entire execution from start to finish. When setting the workflow timeout: * **Estimate total runtime**: add up the expected duration of all steps in your workflow * **Add buffer time**: include extra time for network delays, retries, and variable workloads * **Set a reasonable limit**: the workflow timeout catches runaway executions when individual step timeouts fail to trigger The workflow timeout is a backstop, not a target. Most workflows should complete well before the timeout. If executions regularly approach the limit, consider breaking the workflow into smaller pieces or optimizing slow steps. When a workflow times out, any in-progress agent sessions are terminated and the execution is marked as failed. Set timeouts generously for complex workflows that involve multiple agent interactions. *** ## Execution Priority Controls the order in which queued workflows execute when multiple workflows target the same resource (issue, PR, or repository). **Default:** 5 **Range:** 1–100 (lower numbers execute first) Think of priority as "position in line": priority 1 is first in line, priority 100 is last. ### Priority guidelines | Priority range | Use for | | -------------- | -------------------------------------------------- | | 1–10 | Critical security scans, urgent incident response | | 11–30 | Code reviews, bug fixes, time-sensitive automation | | 31–50 | Standard workflows, normal automation | | 51–70 | Documentation updates, metrics collection | | 71–100 | Background analytics, cleanup tasks | ### How priority interacts with queuing When multiple workflows queue for the same resource: 1. Workflows are ordered by priority (lowest number first) 2. Within the same priority level, workflows execute in FIFO order 3. Only one workflow runs per resource at a time For a deep dive into queuing, locking, and deduplication, see [Workflow Execution Control](/docs/workflows/workflow-execution-control). *** ## Default LLM Model Set a workflow-level model that agents can inherit when no higher-priority model applies. **Default:** Inherits from workspace settings ### Model selection cascade Steps that use the **Overcut** engine resolve their model in this priority order: 1. **Coordinator override**: the model selected for the coordinator, when configured 2. **Agent model**: the agent's own model selection 3. **Workflow default**: the value set here in workflow metadata 4. **Workspace default**: configured in [Workspace Settings](/docs/reference/workspace-settings) 5. **System default**: Overcut's managed default model The **Claude** engine uses a separate order. Its clearable **Default Claude Engine Model** is separate from **Default LLM Model**, and it cannot use a system model as a fallback. See [Workspace Settings: Model resolution order](/docs/reference/workspace-settings#model-resolution-order) for the canonical Claude resolution and eligibility rules. Use this setting to test workflows with different models without changing workspace defaults. For example, set a faster model for high-volume automation or a more capable model for complex analysis. For an end-to-end walkthrough, see the [Default Model Configuration quick start](/docs/quick-starts/default-model-configuration). *** ## Machine Size Controls the CPU and memory available to the machine that runs this workflow. Find it under **Settings** in the workflow metadata panel. **Default:** Standard Larger machine sizes consume more credits per run. Choose a larger size for workflows that run heavy build or test commands, install large dependencies, analyze large repositories, or use memory-intensive steps. Keep the default for lightweight triage, comment, routing, or status workflows. For the full list of sizes, resources, and credit costs, see [Machine Sizes](/docs/reference/machine-sizes). *** ## Status Update Method Controls how Overcut posts progress comments to pull requests and tickets during workflow execution. ### Options Creates a new comment for each workflow run. Each execution gets its own acknowledgment, progress updates, and final status. Keeps status updates in a single thread. Overcut edits the most recent reusable comment instead of creating new ones. Posts one opening acknowledgment and later edits the same comment with the final summary. No incremental progress updates in between. ### Choosing a method | Workflow pattern | Recommended method | Why | | -------------------------------------------------- | ---------------------- | -------------------------------------------------------- | | High-frequency automation (multiple runs per hour) | Reuse Existing Comment | Prevents notification overload | | Audit trail needed for each run | Comment Per Execution | Each execution has its own linkable comment | | Low-volume workflows | Comment Per Execution | Discrete updates are clearer | | Workflows where mid-run progress is not valuable | Static Comment | Keeps threads tidy while confirming start and completion | When in doubt, start with **Comment Per Execution** during testing. Switch to **Reuse Existing Comment** or **Static Comment** once the workflow stabilizes and you want to reduce notification traffic. ### Provider compatibility | Provider | Reuse support | Static Comment support | | ----------------------------------------------- | ------------------------------------------------------------ | ---------------------- | | [GitHub](/docs/integrations/github) | ✅ Full support | ✅ Full support | | [Bitbucket](/docs/integrations/bitbucket) | ✅ Full support | ✅ Full support | | [GitLab](/docs/integrations/gitlab) | ✅ Full support | ✅ Full support | | [Azure DevOps](/docs/integrations/azure-devops) | ⚠️ PRs supported; tickets fall back to Comment Per Execution | ✅ Full support | | [Jira](/docs/integrations/jira) | ✅ Full support | ✅ Full support | Deleting the managed comment removes the marker. The next run creates a new reusable thread. ### Reducing notification noise Some providers (GitHub, Jira, etc.) send an email or in-app notification every time a comment is posted or edited on a PR or issue. In workflows that produce several progress updates per run, this can flood inboxes and Slack channels. **Static Comment** is the most effective way to limit notifications. The provider only fires two: one when the opening comment is created and one when the final summary edit lands. **Reuse Existing Comment** also helps because edits typically generate fewer notifications than new comments, but behavior varies by provider. If notification volume is a concern, start with **Static Comment** for any workflow where you don't need mid-run visibility. *** ## Draft Indicators When a workflow has unpublished changes, two visual cues help you stay aware: * **Workspace header chip**: appears beside the workspace name when any workflow has a draft. Shows the count of affected workflows and links to the Unpublished Changes review page. See [Workflow Versioning: Finding unpublished changes](/docs/workflows/workflow-versioning#finding-unpublished-changes) for details. * **Builder banner**: inside Workflow Builder, a banner reminds you that you are editing a draft. It includes **Publish** and **Discard** actions so you can commit or revert without leaving the editor. Automated executions (triggers and schedules) always use the latest published version. Manual runs can optionally target the working draft. See Manual executions and drafts. *** ## Related documentation * [Context Parameters](/docs/reference/context-parameters): workflow-level values and how they resolve * [Workflow Versioning](/docs/workflows/workflow-versioning): draft lifecycle, finding unpublished changes, and publish/discard flow * [Workflow Version History](/docs/reference/workflow-history): compare versions side-by-side and restore earlier definitions * [Workflow Execution Control](/docs/workflows/workflow-execution-control): priority queuing, resource locking, and deduplication * [Triggers](/docs/workflows/triggers): when workflows start * [Scheduled Workflows](/docs/workflows/scheduled-workflows): time-based automation * [Default Model Configuration](/docs/quick-starts/default-model-configuration): model selection walkthrough * [Workspace Settings](/docs/reference/workspace-settings): workspace-level defaults * [Workflow Self-Improvement](/docs/how-to/workflows/workflow-self-improvement): configure retrospective cadence and sample size from the workflow dashboard * [Integrations](/docs/integrations/overview): connect to GitHub, GitLab, Jira, and more * [Building Blocks](/docs/building-blocks): core workflow components # Workflow Memory Source: https://docs.overcut.ai/docs/how-to/workflows/workflow-memory Persist knowledge across workflow runs so agents can build on past results. ## Overview Workflow memory lets agents store and recall knowledge between runs, building on past context instead of starting from scratch every time. Common examples: * Coding conventions discovered during reviews * Recurring issues seen across multiple PRs * Decisions made in earlier runs * Insights captured by [retrospective runs](/docs/how-to/workflows/workflow-self-improvement) *** ## How it works Agents automatically have access to workflow memory. No setup or configuration is required. During a run the agent is aware of existing memories and can: 1. **Read** a memory to retrieve its contents 2. **Create** a new memory to save something for future runs 3. **Update** an existing memory to keep it current Agents decide on their own when storing or reading a memory is useful. Memories are scoped to the workflow: each workflow maintains its own independent set. Memories can also be created and refined by retrospectives: automated reviews that analyze past runs and turn findings into reusable guidance. See [Workflow Self-Improvement](/docs/how-to/workflows/workflow-self-improvement) for how retrospectives create memories, promote tentative memories, and adjust weights over time. *** ## Emphasizing memory in prompts Because memory works automatically, most workflows need no special instructions. If you want to steer what the agent remembers or looks up, add a hint in your agent step prompt. **Example prompt snippets:** > Make sure to check your memories for any notes about this repository before starting. > After completing the review, remember any new coding conventions you discovered. Referencing a specific topic in a prompt (for example "check your memories for the deploy checklist") gives the agent a precise lookup target. *** ## Related documentation * [Workflow Self-Improvement](/docs/how-to/workflows/workflow-self-improvement): how retrospectives create and refine memories * [Workflow Builder](/docs/how-to/workflow-builder): configure workflow settings and prompts * [Workflow History](/docs/reference/workflow-history): review drafts and published versions * [Agent Run](/docs/workflows/agent-run): how agents execute within workflows # Workflow Self-Improvement Source: https://docs.overcut.ai/docs/how-to/workflows/workflow-self-improvement How Overcut reviews past workflow runs, creates memories, and refines what agents know over time. ## Overview Workflow self-improvement turns completed workflow runs into reusable knowledge. Overcut periodically reflects on past runs, identifies patterns, and saves findings as [workflow memories](/docs/how-to/workflows/workflow-memory) so agents can apply those lessons in future runs. Workflow-level self-improvement settings appear in the workflow dashboard's **Self-Improvement** panel. Open the panel's **Settings** dialog to control when automatic retrospectives run and how much eligible execution history each retrospective analyzes. These workflow-level settings only apply when **Account → Settings → Auto-Improve Workflows** is enabled. When that workspace setting is off, the workflow dashboard shows a prompt that links you to workspace settings instead of running retrospectives. ## The retrospective process A retrospective reviews one or more completed workflow runs and then: 1. **Investigates recent runs**: reads their steps, agent decisions, tool calls, and outcomes. 2. **Reviews tentative memories** from earlier retrospectives: promotes ones that show up again and discards ones that do not. 3. **Creates new memories** from patterns found in the runs. 4. **Adjusts memory weights** based on how existing memories performed. 5. **Produces a summary** of runs reviewed, findings, and memory changes. Each retrospective creates its own run, so you can open it to read the findings and see exactly what changed. ## How retrospectives create memories Retrospectives are the primary source of workflow memories. They write two kinds: * **Active memories**: guidance Overcut is confident about. These are immediately available to agents in future runs. * **Tentative memories**: single-occurrence observations that look useful but haven't been confirmed yet. A later retrospective promotes a tentative memory to active when it sees the same pattern again. You can review both kinds on the workflow's **Memories** tab, filtered by **Status** (All statuses, Active, Tentative, Archived). The workflow dashboard also shows counts as **Active Memories** and **Pending Memories** (tentative). If a tentative memory looks correct and you don't want to wait for a second occurrence, use the **Confirm** action on the memory card to promote it to active immediately. ## Memory weights and scoring Every memory has a **weight** that reflects how useful it has been. Retrospectives adjust this score based on what they observe: * **Helpful memories**: weight goes up when a memory contributed to a successful run. * **Harmful or misleading memories**: weight goes down when a memory led the agent in the wrong direction. * **Unused memories**: weight decays slowly when a memory is never referenced. When a memory's weight falls below the minimum threshold, Overcut automatically archives it. Archived memories stop influencing agents but remain visible under the **Archived** filter so you can restore them if they become relevant again. Memory cards also show a use count so you can see how often each memory has been referenced. ## Automatic retrospectives When **Auto-Improve Workflows** is enabled, Overcut runs retrospectives on its own after a workflow has accumulated enough completed or failed runs. No manual step is required. The next retrospective starts automatically and its result appears in the **Self-Improvement** panel on the workflow dashboard. Open the **Settings** dialog in the **Self-Improvement** panel to configure two workflow-level values: * **Cadence**: how many new completed or failed runs must accumulate before the next automatic retrospective starts. * **Sample size**: what fraction of that eligible run window is analyzed in each retrospective. For example, a cadence of `10` means Overcut waits for 10 new eligible runs before starting an automatic retrospective. A sample size of `0.5` means Overcut randomly analyzes about half of that window instead of reviewing every eligible run. Because analyzed runs are rounded to a whole number, the exact count is based on the configured window and sample size. Automatic retrospectives run the full process: they investigate runs, create and update memories, adjust weights, and produce a summary. Automatic retrospectives only run when the workspace-level toggle is on. If **Auto-Improve Workflows** is disabled, the workflow dashboard prompts you to enable it in workspace settings before you can use workflow-level self-improvement controls. ### Settings dialog The settings dialog shows two fields: **Run retrospective after N executions** (cadence) and **Sample size (0–1)**. A preview below the fields shows the effective analyzed-run count before you save. Overcut validates settings before saving: cadence must be a whole number from `1` to `1000`, sample size must be between `0.01` and `1`, and the resulting analyzed run count cannot exceed `5` per retrospective. If a combination exceeds the limit, reduce cadence, sample size, or both. ## Manual retrospectives You can start a retrospective yourself at any time. There are two entry points, and they behave differently. ### Run Now: a full manual retrospective Use **Run Now** in the workflow dashboard's **Self-Improvement** panel when you want feedback sooner than the next automatic cycle: for example, after a release, after a major process change, or after a cluster of runs you want to learn from. **Run Now** performs the same full retrospective as the automatic cycle: it investigates unreviewed runs, creates and updates memories, adjusts weights, and summarizes. The only difference is that you triggered it manually instead of waiting. ### Investigate: focused review of a single run Use **Investigate This Run** from a workflow run's detail page when you want to analyze one specific run in depth: for example, to understand why a particular run failed or behaved unexpectedly. Investigate opens a dialog where you can optionally provide a **Focus Question** (e.g., *"Why did this run fail at the deploy step?"*) to guide the analysis. Overcut then creates a retrospective on that single run and navigates you to it. Investigate can create new memories from findings in that run, but it intentionally skips the broader bookkeeping steps. It does not confirm tentative memories from earlier retrospectives and does not adjust weights on existing ones. This keeps Investigate safe to run repeatedly on the same run without compounding effects on existing memories. ## Manual run vs. automatic run | Aspect | Automatic retrospective | Run Now (manual) | Investigate (manual) | | --------------------------- | -------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------- | | Trigger | Automatic, after enough runs accumulate | User clicks **Run Now** in Self-Improvement panel | User clicks **Investigate This Run** on a run's detail page | | Runs analyzed | Unreviewed runs since the last retrospective | Unreviewed runs since the last retrospective | The single run you selected | | Focus Question | Not used | Not used | Optional: you can steer the analysis | | Creates memories | Yes | Yes | Yes (from findings in the selected run) | | Confirms tentative memories | Yes | Yes | No | | Updates memory weights | Yes | Yes | No | | Produces a summary | Yes | Yes | Yes | | When to use | Ongoing, hands-off learning | You want feedback on recent runs immediately | You want to dig into one specific run | **Run Now** and the automatic retrospective are equivalent in what they change: both create memories, confirm tentative ones, and adjust weights. **Investigate** is narrower: it still captures lessons from the run as new memories, but leaves prior tentative memories and existing weights untouched. That makes it safe to run more than once on the same workflow run without repeatedly shifting the broader picture. ## Viewing retrospective results Every retrospective, automatic or manual, creates its own run that you can open and inspect. * The **Self-Improvement** panel on the workflow dashboard always shows the most recent retrospective and updates in real time when one is in progress. * When automatic retrospectives are enabled, the panel also summarizes the configured cadence and sampling percentage. * Click into the retrospective run to see the findings, the memories it created or updated, weight changes, and the final summary. * Open the workflow's **Memories** tab to see the current set of active and tentative memories and their weights. ## Related documentation * [Workflow Memory](/docs/how-to/workflows/workflow-memory): how agents use memories during runs * [Workspace Settings](/docs/reference/workspace-settings): enable Auto-Improve Workflows * [Workflow Version History](/docs/reference/workflow-history): drafts and published workflow versions # Connect to Azure DevOps Source: https://docs.overcut.ai/docs/integrations/azure-devops Connect Overcut to Azure DevOps with the guided setup flow for consent, service principal access, and connection verification. ## What You Can Do With Azure DevOps connected, Overcut agents can: * **Access Repositories**: Clone, read, and modify code in your Azure DevOps repositories * **Manage Work Items**: Create, update, and comment on Azure DevOps work items (bugs, tasks, user stories) * **Link Related Work**: Create, remove, and review linked relationships between Azure DevOps work items when Azure DevOps allows them * **Handle Pull Requests**: Review, comment on, and manage pull requests * **Code Operations**: Clone repositories, create branches, and perform git operations * **Webhook Triggers**: Automatically start workflows based on Azure DevOps events * **Repository Configuration**: Configure agent behavior per repository ## How Overcut Authenticates Overcut authenticates with Azure DevOps using a **service principal**: an application identity registered in Microsoft Entra ID that authenticates using its own credentials rather than a user's personal account. For more details on this pattern, see Microsoft's documentation on [service principal authentication in Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity). **Why a service principal?** * **Short-lived tokens**: Authentication uses tokens that expire after one hour and are automatically refreshed. No long-lived secrets to rotate * **No dependency on individual users**: The integration is tied to an application identity, not a person's account, so it survives team member departures and role changes * **Enterprise security**: Centralized permission management through Microsoft Entra ID, with full audit trail and compliance with enterprise security policies * **Clear attribution**: All automated operations appear under a single, recognizable application identity, making it easy to distinguish automated actions from manual ones ## Before You Start You need: * An Azure DevOps organization that contains the projects you want to connect * Your Azure DevOps organization name * Your Microsoft Entra tenant ID * A **Microsoft Entra administrator** (Global Admin or Privileged Role Admin) who can approve admin consent * An **Azure DevOps administrator** (Project Collection Administrator) who can add the Overcut service principal to your organization and projects The Microsoft Entra administrator and Azure DevOps administrator can be different people. ## Connect Azure DevOps in Overcut Overcut uses a guided setup flow so you can move through consent, Azure DevOps access, and verification in order. In Overcut, open **Integrations**, select **Add Provider**, then select **Azure DevOps**. Overcut opens the **Connect to Azure DevOps** guided setup. Enter: * **Organization Name**: your Azure DevOps organization name * **Tenant ID**: your Microsoft Entra tenant ID The tenant ID is a GUID. You can find it in the Microsoft Entra admin center under **Overview** → **Tenant ID**, or ask your Entra administrator. Both fields are required before you can continue. Under **Step 1 - Grant admin consent**, select **Generate link** to create the Microsoft admin consent URL for your tenant. Overcut shows the full consent link in the setup flow. You can: * Open it yourself if you are the Microsoft Entra administrator * Copy it and send it to the administrator who will approve access The link is generated from the tenant ID you entered, so confirm that the value is correct before sharing it. The Microsoft Entra administrator opens the consent link, reviews the requested access, and approves it for the tenant. After consent is complete, return to the Overcut setup flow and confirm that admin consent was approved. This step unlocks the Azure DevOps access instructions that follow. Under **Step 2 - Add Overcut to Azure DevOps**, Overcut shows the service principal ID to use in Azure DevOps after consent is approved. In Azure DevOps: 1. Open your organization users page at `https://dev.azure.com//_settings/users` 2. Select **Add User** 3. Search for the Overcut service principal using the ID shown in Overcut 4. Set **Access level** to **Basic** 5. Add the service principal to the **Project Administrators** group for each project you want to connect Return to Overcut and confirm that the service principal was added in Azure DevOps. Under **Step 3 - Verify connection**, select **Connect** after confirming admin consent and adding the service principal in Azure DevOps. Overcut verifies that the service principal can access the Azure DevOps organization you entered. If verification succeeds, Overcut confirms the connection and the organization appears under **Integrations**. ## What to Expect During Setup ### Validation * **Generate link** stays unavailable until both **Organization Name** and **Tenant ID** are filled in * **Connect** stays unavailable until you confirm both admin consent and service principal setup ### Verification errors If the final connection check fails, Overcut shows the verification error in the setup dialog so you can correct the issue and try again. Common reasons include: * The service principal was not added in Azure DevOps yet * The service principal was added to a different Azure DevOps organization * The organization name entered in Overcut does not match the organization the service principal can access ## Connect another organization Each Azure DevOps connection uses its own organization name and Microsoft Entra tenant details. To connect another organization, select **Add Provider**, choose **Azure DevOps**, and complete the guided setup with the additional organization's name and tenant ID. ## Compatibility Note Overcut uses the modern `dev.azure.com` format for Azure DevOps. If your team still uses older `*.visualstudio.com` URLs, enter just your organization name (the same slug that appears in both URL formats) when prompted, then continue with the guided steps. ## Why Project Administrator Access Is Required During setup, Overcut instructs you to add the service principal to the **Project Administrators** group for each project you want to connect. Overcut creates **Service Hook subscriptions** (webhooks) in Azure DevOps to listen for events such as pull request creation, work item updates, and CI pipeline state changes. These webhooks are what allow Overcut to automatically trigger workflows in response to activity in your Azure DevOps projects. Azure DevOps **requires Project Administrator permissions** to create and manage Service Hooks. There is no lesser permission level that grants this access. This is an Azure DevOps platform constraint, not an Overcut-specific requirement. If a project is not added during setup, Overcut cannot manage resources or register webhooks in that project until access is granted. ## Linked work item relationships Agents can create, remove, and read linked work item relationships in Azure DevOps. Use the relationship types Azure DevOps defines in your connected environment (agents can inspect the available types before linking). Cross-project linking works when Azure DevOps allows it for the projects your workspace can access. See the [tools reference](/docs/reference/tools) for how linked relationships work across providers. ## Permissions The Azure DevOps integration requires permissions at two levels, granted during different setup steps. ### Entra ID permissions (granted during admin consent) These permissions are approved by the Entra administrator during the admin consent flow: * **Azure DevOps API access** (`user_impersonation`): Allows the service principal to call Azure DevOps APIs on behalf of the organization * **Microsoft Graph access**: Used for tenant validation during the consent process ### Azure DevOps permissions (configured when you add the service principal) These permissions are assigned when the service principal is added to the Azure DevOps organization: * **Repository Operations**: Read and write repository contents, create branches, manage pull requests * **Work Item Management**: Create, read, and update work items (bugs, tasks, user stories, etc.) * **Service Hook Management**: Create and manage webhook subscriptions for event notifications (requires Project Administrator) * **Project Access**: Access to project and organization information ## Triggering on work-item tags Azure DevOps does **not** send a dedicated "tag added" event the way GitHub or Jira send a labeled event. Adding or removing a work-item **tag** is delivered as a generic work-item update, which Overcut normalizes to the **`issue_edited`** event. As a result, an `issue_labeled` trigger never fires on Azure DevOps. To start a workflow when a tag is added, configure the trigger like this: 1. Set the trigger event to **Issue edited**. 2. Add a condition: **Labels Added** (`context.trigger.labelsAdded`) **contains** `` - for example `ready-for-development`. Use **Labels Removed** (`context.trigger.labelsRemoved`) for tag removals. These delta fields are populated only when tags actually change, so the condition won't match unrelated edits. See [Event Context → Label Operations](/docs/reference/event-context#label-operations). ## Next Steps After connecting Azure DevOps: * [Add repositories from the connected organization to your workspace](/docs/get-started/repositories) * Configure workflows that use repositories, pull requests, and work items * Set up triggers that respond to Azure DevOps events * Monitor agent activity through Azure DevOps audit logs # Connect to Bitbucket Source: https://docs.overcut.ai/docs/integrations/bitbucket Connect Overcut to Bitbucket so agents can work with repositories and pull requests directly from your workflows. Connect Overcut to Bitbucket so agents can discover your repositories and work with code directly. Once connected, agents can clone repositories, open and review pull requests, and respond to Bitbucket events as part of your workflows. This page covers the concepts that apply to every Bitbucket connection. **The exact setup steps depend on where Overcut runs and where your Bitbucket lives** - pick your path in [Which setup do I need?](#which-setup-do-i-need) below. ## What You Can Do With Bitbucket connected, Overcut agents can: * **Access Repositories**: Clone, read, and modify code in your Bitbucket repositories * **Manage Pull Requests**: Create, review, comment on, and merge pull requests * **Handle Code Reviews**: Submit approvals, request changes, and add inline comments * **Code Operations**: Clone repositories, create branches, and perform git operations * **Webhook Triggers**: Automatically start workflows based on Bitbucket events * **Repository Configuration**: Configure agent behavior per repository ## Which setup do I need? Two questions decide your path: **where Overcut runs** and **where your Bitbucket lives**. | Where Overcut runs | Where your Bitbucket lives | Follow this guide | | ----------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------ | | Overcut Cloud (managed) | Bitbucket Cloud (`bitbucket.org`) | [Bitbucket Cloud on Overcut Cloud (Forge app)](/docs/integrations/bitbucket/cloud) | | Self-hosted Overcut | Bitbucket Cloud (`bitbucket.org`) | [Bitbucket Cloud from self-hosted Overcut](/docs/integrations/bitbucket/cloud-self-hosted) | | Self-hosted Overcut | Bitbucket Server / Data Center (on-prem) | [Bitbucket Server / Data Center](/docs/integrations/bitbucket/data-center) | Overcut Cloud connects to **Bitbucket Cloud only** (the managed Forge app is Cloud-only). On-prem **Bitbucket Server / Data Center** can only be connected from a **self-hosted Overcut** deployment, using your own OAuth credentials on your instance. Managed Overcut + Bitbucket Cloud. Install the Overcut Forge app. No credentials to manage. Self-hosted Overcut + Bitbucket Cloud. Connect directly with your own OAuth consumer (3LO or 2LO). Webhooks register automatically. Self-hosted Overcut + on-prem Bitbucket. Connect with an OAuth application link on your instance. ## Using Bitbucket in Your Workflows Once connected, Bitbucket repositories appear as available sources when you: * Add a **Source** to a workflow * Configure a **Trigger** that monitors repositories * Set up **Actions** that work with pull requests Agents gain secure, permission-scoped access to clone repositories, create branches, open pull requests, and leave code review comments, without leaving your existing workflows. For workflows that need to automatically identify which code repositories are most relevant to issues, consider using the repo.identify action. This action uses AI-powered analysis and repository correlations to determine the best repositories to work with for each issue. Learn more in our Repository Mapping guide. ## Provider-Specific Behaviors * **Webhooks**: On **Bitbucket Cloud** (self-hosted Overcut), Overcut registers a webhook per repository **automatically** when you add the repo - there is nothing to paste. On **Bitbucket Server / Data Center**, a project admin registers **one project-level webhook** by hand (it is inherited by every repo in the project). See each connection guide for details. * **Ticket links**: Bitbucket does not support typed ticket links through Overcut's native integration. ## Permissions In every setup, Overcut needs read and write access to repositories and pull requests. **The exact scopes you grant differ by path** (Bitbucket Cloud uses granular consumer permissions; Bitbucket Server / Data Center uses repository-level scopes), so they are listed on each connection guide: * [Bitbucket Cloud on Overcut Cloud (Forge app)](/docs/integrations/bitbucket/cloud) * [Bitbucket Cloud from self-hosted Overcut](/docs/integrations/bitbucket/cloud-self-hosted) * [Bitbucket Server / Data Center](/docs/integrations/bitbucket/data-center) In all cases, the **account you authorize with owns every pull request, comment, and merge** Overcut performs, so authorize as a dedicated service account (for example `overcut-bot`), not your personal admin account. ## Troubleshooting Path-specific problems (callback URL mismatches, webhook setup, service-account access) are covered on each connection guide. General checks: * Ensure the connected account is a workspace/project member with write access to the target repositories * Try disconnecting and reconnecting the integration * Confirm your Bitbucket instance is accessible from Overcut # Bitbucket Cloud on Overcut Cloud (Forge app) Source: https://docs.overcut.ai/docs/integrations/bitbucket/cloud Connect Bitbucket Cloud to Overcut's managed service by installing the Overcut Forge app. Use this path when you use **Overcut's managed service** (Overcut Cloud) and your Bitbucket is **Atlassian-hosted Bitbucket Cloud** (`bitbucket.org`). You install the Overcut Forge app; there are no credentials to manage. Not your setup? See [Which setup do I need?](/docs/integrations/bitbucket#which-setup-do-i-need) to choose between Overcut Cloud, self-hosted Overcut, and Bitbucket Server / Data Center. ## Prerequisites * A **Bitbucket Cloud** workspace * Admin permissions in your Bitbucket workspace * An active Overcut Cloud workspace ## Connect In your Overcut workspace, go to **Integrations** and click **Connect Bitbucket**. Click **Install Overcut App** to be redirected to your Bitbucket workspace. Install the app and grant the necessary permissions. If you've already installed the app, click **I've Installed the App** to proceed. After installing the app, you'll be prompted to enter your Bitbucket workspace name (e.g., `my-org`). Enter your workspace name and click **Complete Install** to finalize the connection. The Forge app manages authentication, permissions, and event delivery for you. There is no OAuth consumer to create, no callback URL to configure, and no webhook to register. ## Permissions The Overcut Forge app requests access to your repositories, pull requests, and pipelines, and the ability to manage webhooks. You grant these when you install the app. ## Troubleshooting * **App not installed**: complete the Marketplace install in Bitbucket first, then click **I've Installed the App** in Overcut. * **Wrong workspace name**: make sure the workspace name you enter matches your workspace slug exactly (for example `my-org`). * **Missing repositories**: the integration only shows repositories the app can access. Check the app's grant in your workspace settings. For concepts shared across all Bitbucket setups (pull request operations, webhook behavior, ticket links), see the [Bitbucket overview](/docs/integrations/bitbucket). # Bitbucket Cloud from self-hosted Overcut Source: https://docs.overcut.ai/docs/integrations/bitbucket/cloud-self-hosted Connect Atlassian-hosted Bitbucket Cloud to a self-hosted Overcut deployment using your own OAuth consumer. Use this path when you run **Overcut on your own infrastructure** and your Bitbucket is **Atlassian-hosted Bitbucket Cloud** (`bitbucket.org`). Instead of the managed Forge app, you connect directly with your **own** OAuth consumer. Each deployment brings its own credentials; there is no shared Overcut Cloud client. Not your setup? See [Which setup do I need?](/docs/integrations/bitbucket#which-setup-do-i-need). On **Overcut Cloud**, use the [Forge app](/docs/integrations/bitbucket/cloud) instead. For on-prem Bitbucket, see [Bitbucket Server / Data Center](/docs/integrations/bitbucket/data-center). ## Prerequisites * A **Bitbucket Cloud** workspace, with admin access to **Workspace settings -> OAuth consumers** * A self-hosted Overcut deployment you operate (see [Deployment configuration](#deployment-configuration)) The Bitbucket account you authorize with **owns every pull request, comment, and merge** Overcut performs. Use a dedicated service account (for example `overcut-bot`), not your personal admin account. The service account must be a workspace member with write access to the target repositories. ## Choose an authorization type The connect modal has an **Authorization type** toggle: * **User authorization (3LO)** - the default, covered by the steps below. A browser **Authorize** step runs once, signed in as the service account. Bitbucket issues a refresh token so the connection survives long-running sessions. * **Service account (2LO)** - no browser consent. Recommended for headless setups or when an org policy blocks interactive authorization. See [Use a service account (2LO)](#use-a-service-account-2lo). ## Connect with user authorization (3LO) In Bitbucket, go to **Workspace settings -> OAuth consumers -> Add consumer** and name it (for example `Overcut`). Set the **Callback URL** to your deployment's Overcut callback, exactly: ``` https:///bitbucket-cloud-auth-app/callback ``` This must match the `BITBUCKET_CLOUD_REDIRECT_URI` server setting character for character, and must use **https** (except `http://localhost:` for local development). Leave **"This is a private consumer" unchecked**. This is required so Bitbucket issues a **refresh token**; without it, the connection breaks on long-running sessions. Enable these permissions on the consumer: * **Account:** Read * **Repositories:** Read + Write * **Pull requests:** Read + Write * **Pipelines:** Read * **Webhooks:** Read and write (required so Overcut can register webhooks automatically) Save, then copy the **Key** (Client ID) and **Secret**. In Overcut, open the git providers list and click the **Bitbucket Cloud (self-hosted connect)** tile. Leave the authorization type as **User authorization (3LO)**. Enter your **Workspace** slug (for example `acme`) and the **Key** and **Secret** from the previous step. Make sure your browser session is signed into Bitbucket **as the service account**, then click **Authorize**. Overcut verifies workspace access, captures the bot identity, and stores the connection. Add repositories to Overcut as usual. For each registered repository, Overcut **automatically registers a webhook** on the Bitbucket repo for pull request, push, and commit-status events, signed with a per-repo secret. There is no webhook URL to paste. Removing a repository (or disconnecting the workspace) removes its webhook. ## Use a service account (2LO) Use this when you prefer a headless credential over a browser consent, or when an org policy blocks interactive authorization. 2LO authenticates as the OAuth consumer itself (no consenting user), so there is no callback and no Authorize step. In **Workspace settings -> OAuth consumers -> Add consumer**, create a **private** consumer (check **"This is a private consumer"**). A callback URL is not required for 2LO. Enable the same permissions as the 3LO path - **Repositories** (Read + Write), **Pull requests** (Read + Write), **Pipelines** (Read), and **Webhooks** (Read and write) - then copy the **Key** and **Secret**. The 2LO token authenticates as the **OAuth consumer itself** - a service-account-style principal, not a human user - so there is no account to sign in as and no browser consent. Overcut attributes its actions to the consumer and uses that identity for bot-loop prevention. Create the consumer in the workspace that owns the target repositories. Open the **Bitbucket Cloud (self-hosted connect)** tile and switch the **Authorization type** to **Service account (2LO)**. Enter the **Workspace** slug plus the consumer's **Key** and **Secret**, and click **Connect**. There is **no callback URL and no browser Authorize step**. The token acts as the consumer owner; scopes come from the consumer's configuration. 2LO has no refresh token, so Overcut renews by re-requesting. Webhook registration is identical to the 3LO path - adding a repository automatically registers its webhook. ## Deployment configuration These settings are configured once by whoever operates the self-hosted Overcut deployment. | Setting | Value | Notes | | ------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `INTEGRATION_BITBUCKET_CLOUD_ENABLED` | `true` | Set on both the server and workflow-dispatcher to enable the tile and inbound webhooks. | | `BITBUCKET_CLOUD_REDIRECT_URI` | `https:///bitbucket-cloud-auth-app/callback` | Must equal the consumer Callback URL exactly (3LO only). | | `DISPATCHER_BASE_URL` | `https:///hooks` | External URL used to build the auto-registered webhook URL. | The per-repo webhook secret is derived from the deployment's `JWT_SECRET` (shared by the server that registers the hook and the dispatcher that verifies it), so no separate webhook secret is required. ## Troubleshooting * **`redirect_uri` mismatch at Authorize**: the consumer Callback URL and `BITBUCKET_CLOUD_REDIRECT_URI` are not byte-identical (often a trailing slash or `http` vs `https`). * **"The authorized account cannot access workspace ..." after consent**: the account you authorized with is not a member of the workspace you entered, or the slug is wrong. * **Actions attributed to the wrong person, or bot loops**: you consented as your personal account instead of the service account. Re-authorize in an incognito window signed in as the bot account. * **Auth fails on long sessions ("no refresh token")**: the 3LO consumer was created as a private consumer, so Bitbucket never issued a refresh token. Recreate it with "This is a private consumer" unchecked and reconnect. (A private consumer is correct only for 2LO.) * **Webhook events never fire**: confirm `DISPATCHER_BASE_URL` is the external URL and the dispatcher has `INTEGRATION_BITBUCKET_CLOUD_ENABLED=true`; check the repo's webhooks in Bitbucket for the auto-registered Overcut hook. For concepts shared across all Bitbucket setups (pull request operations, webhook behavior, ticket links), see the [Bitbucket overview](/docs/integrations/bitbucket). # Bitbucket Server / Data Center Source: https://docs.overcut.ai/docs/integrations/bitbucket/data-center Connect an on-prem Bitbucket Server or Data Center instance to a self-hosted Overcut deployment using an OAuth application link. Use this path when you run **Overcut on your own infrastructure** and your Bitbucket is **self-hosted Bitbucket Server or Data Center** (an on-prem instance, not `bitbucket.org`). You connect with an **OAuth 2.0 incoming Application Link** created on your Bitbucket instance. Each deployment uses its own client credentials; there is no shared Overcut Cloud client. Not your setup? See [Which setup do I need?](/docs/integrations/bitbucket#which-setup-do-i-need). For Atlassian-hosted Bitbucket Cloud, use the [Forge app](/docs/integrations/bitbucket/cloud) (Overcut Cloud) or [direct OAuth](/docs/integrations/bitbucket/cloud-self-hosted) (self-hosted Overcut). ## How it differs from Bitbucket Cloud | | Bitbucket Server / Data Center | Bitbucket Cloud | | --------------- | --------------------------------------------------- | ---------------------------------------------------------------------- | | OAuth endpoints | Your instance (`{instance}/rest/oauth2/latest/...`) | Central (`bitbucket.org/site/oauth2/...`) | | Authorization | 3LO only (browser consent) | 3LO or 2LO | | Scopes | `REPO_READ`, `REPO_WRITE` | `account`, `repository`, `pullrequest`, `pipeline`, `webhook` (+write) | | REST API | v1.0 (`/rest/api/1.0`) | v2.0 | | Webhook | Manual, **one project-level** webhook | Automatic, per repository | Bitbucket Data Center requires **DC 7.21 or newer** for the OAuth 2.0 authorization-code provider (any 8.x LTS works). ## Prerequisites * A **Bitbucket Server or Data Center** instance reachable from your Overcut deployment over **HTTPS** * **Administrator** access to that instance (to create the Application Link) and **project admin** on the target project (to create the webhook) * A self-hosted Overcut deployment you operate (see [Deployment configuration](#deployment-configuration)) The Bitbucket account you authorize with **owns every pull request, comment, and merge** Overcut performs. Authorize while signed in as a dedicated service account (for example `overcut-bot`), not your personal admin account. The service account must have write access to the target repositories. ## Connect As a Bitbucket administrator, go to **Administration -> Application links -> Create link**, and select **External application** / **Incoming**. Set the **redirect (callback) URL** to your deployment's Overcut callback, exactly: ``` https:///bitbucket-server-auth-app/callback ``` This must match the `BITBUCKET_SERVER_REDIRECT_URI` server setting character for character, and must use **https**. In the **Application permissions** matrix, tick **Repositories: Write** (this auto-includes Read), which maps to the `REPO_READ` + `REPO_WRITE` scopes Overcut requests. Do **not** tick Admin / Projects / Account / System-admin - webhooks are added manually, so no admin scope is needed. Save, then copy the generated **Client ID** and **Client Secret**. In Overcut, open the git providers list and click the **Bitbucket Server / Data Center** tile. Enter: * **Instance URL**: your Bitbucket base URL (for example `https://bitbucket.your-company.com`) * the **Client ID** and **Client Secret** from the previous step Make sure your browser session is signed into Bitbucket **as the service account**, then click **Authorize**. Overcut captures the service-account identity and stores the connection. Webhooks are configured in Bitbucket, separately from the Application Link. Open the connected org's **settings** page in Overcut (**View settings** on the provider page) to find the webhook **URL** (`https:///webhooks/bitbucket/server/`) and a revealable **secret**. In Bitbucket, go to **Project settings -> Webhooks -> Create webhook** (a project-level webhook is inherited by every repository in the project, so this is one paste per project, not per repo). Paste the **URL**, put the revealed **secret** in the webhook's **Secret** field (it signs the `X-Hub-Signature` HMAC the dispatcher verifies), and enable these events: * `pr:opened`, `pr:from_ref_updated`, `pr:modified`, `pr:merged`, `pr:declined` * `pr:reviewer:approved`, `pr:reviewer:unapproved`, `pr:reviewer:needs_work` * `pr:comment:added` Creating a project webhook requires **project admin** in Bitbucket (a one-time human step); the Overcut OAuth token itself stays write-only. Bitbucket Data Center has no Pipelines product, so there are no CI/build-status webhook events on this path. ## Deployment configuration These settings are configured once by whoever operates the self-hosted Overcut deployment. | Setting | Value | Notes | | -------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | | `INTEGRATION_BITBUCKET_SERVER_ENABLED` | `true` | Set on both the server and workflow-dispatcher to enable the tile and inbound webhooks. | | `BITBUCKET_SERVER_REDIRECT_URI` | `https:///bitbucket-server-auth-app/callback` | Must equal the Application Link redirect URL exactly. | | `DISPATCHER_BASE_URL` | `https:///hooks` | External URL used to build the webhook URL shown in Overcut. | ## Troubleshooting * **`redirect_uri` mismatch at Authorize**: the Application Link redirect URL and `BITBUCKET_SERVER_REDIRECT_URI` are not byte-identical (often a trailing slash or `http` vs `https`). * **Token exchange returns 400 (PKCE)**: some instances require PKCE for the incoming link. Confirm the Application Link is configured to allow the authorization-code grant without mandatory PKCE, or contact Overcut support. * **Authorize fails to reach Bitbucket**: the instance must be reachable from the Overcut deployment over HTTPS with a valid certificate. Confirm network access and TLS. * **Actions attributed to the wrong person, or bot loops**: you consented as your personal account instead of the service account. Re-authorize in an incognito window signed in as the bot account. * **Webhook events never fire**: confirm the webhook secret in Bitbucket matches the one shown in Overcut, the listed PR events are enabled, and `DISPATCHER_BASE_URL` is set to the external URL with `INTEGRATION_BITBUCKET_SERVER_ENABLED=true` on the dispatcher. For concepts shared across all Bitbucket setups (pull request operations, webhook behavior, ticket links), see the [Bitbucket overview](/docs/integrations/bitbucket). # Claude Agent SDK Integration Source: https://docs.overcut.ai/docs/integrations/claude-agent-sdk Use Anthropic's Claude Code Agent SDK as an alternative execution engine for Overcut workflows # Claude Agent SDK Integration Overcut supports using Anthropic's Claude Code Agent SDK as an alternative execution engine to the default Overcut Agent architecture. This integration allows you to leverage Claude's native coding capabilities while maintaining all existing Overcut functionality. ## Overview The Claude Agent SDK integration provides: * **Claude Code Intelligence**: Claude's advanced understanding of code patterns, architecture, and best practices * **Intelligent Task Delegation**: Automatic coordination between specialized agents based on context * **Seamless Tool Integration**: Full access to Overcut's ticketing, pull request, and workflow tools * **Consistent Experience**: Same agent personalities and capabilities across both execution modes * **Enhanced Performance**: Leverage Claude's latest capabilities for complex coding tasks ## Architecture ### Execution Modes Overcut supports two execution modes: 1. **Overcut Agent Mode** (Default): Uses Overcut's Agent architecture 2. **Claude Agent Mode**: Uses Anthropic's Claude Code Agent SDK directly The execution engine is selected when configuring each workflow step. For a side-by-side comparison of the two engines, see [Execution Engines](/docs/concepts/execution-engines). ### Key Benefits * **Advanced AI Capabilities**: Access to Claude's state-of-the-art reasoning and code generation * **Flexible Execution**: Choose the best AI engine for each specific task type * **Seamless Integration**: All Overcut tools work with both engine types * **Intelligent Coordination**: Automatic collaboration between multiple agents in sessions ## Setup and Configuration ### Prerequisites You need permission to manage workspace **LLM Models** and edit the workflow. You also need credentials for one of these providers: * **Anthropic**: An Anthropic API key or a Claude subscription token generated with `claude setup-token`. Choose one authentication method, not both. * **AWS Bedrock**: A Bedrock API key or a complete IAM credential pair, plus the AWS region and model or inference-profile ID. See [LLM Models](/docs/reference/llm-models#provider-configuration) for every provider field, including the optional Anthropic **Base URL** and **Fallback Model** settings. ### LLM Model Setup Open LLM Models, select Add LLM Model, and choose Anthropic or AWS Bedrock. Enter the provider credentials and model settings, then save the model and keep it active. Open Settings. Under AI, choose the model in Default Claude Engine Model. This setting is separate from Default LLM Model and can be cleared. In the Workflow Builder, open the agent step and set Execution Engine to Claude. For an agent session, use Coordinator Model Override to choose another compatible model for the coordinator. A run-agent step uses the selected agent's model, followed by the configured workflow and workspace defaults when needed. ### Model Compatibility The Claude engine accepts only custom Anthropic or AWS Bedrock models that are active, belong to the current workspace, and are not system models. It does not fall back to a system model. If the selected model is not compatible, choose or create a compatible model in **LLM Models**. An Anthropic model configured with only a Claude subscription token works with the **Claude** engine, not the **Overcut** engine. An Anthropic-compatible gateway can be used through **Base URL** only when it supports the Anthropic `/v1/messages` API. For provider configuration fields and model assignment behavior, see [LLM Models](/docs/reference/llm-models). ## Model Selection ### Claude model resolution Claude-engine steps use the first configured model in this order: 1. **Coordinator override** 2. **Agent model** 3. **Workflow default** 4. **Workspace Claude default** set through **Default Claude Engine Model** 5. **Main workspace default** set through **Default LLM Model** **Default Claude Engine Model** is separate from **Default LLM Model** and can be cleared. Clearing it lets resolution continue to the main workspace default. The first model resolved by this order must be active, belong to the current workspace, be a non-system model, and use Anthropic or AWS Bedrock. The Claude engine does not skip an incompatible selection or fall back to a system model. See [LLM Models](/docs/reference/llm-models#claude-engine-cascade) for the canonical model cascade and compatibility rules. ## Getting Started Create a compatible **LLM Model**, select **Claude** as the step's **Execution Engine**, and run the workflow. Set **Default Claude Engine Model** for a workspace-level default. For an agent session, use **Coordinator Model Override** when that session needs a different compatible model. # Connect to ClickUp Source: https://docs.overcut.ai/docs/integrations/clickup Connect Overcut to your ClickUp workspace to manage tasks, automate status updates, and trigger workflows from ClickUp events. ## What You Can Do With ClickUp connected, Overcut agents can: * **Create and Update Tasks**: Open new tasks or modify titles, descriptions, assignees, tags, and statuses * **Comment on Tasks**: Post comments to keep task threads in sync with automated workflows * **Trigger Workflows**: Automatically start workflows when tasks are created, updated, status-changed, or commented on * **Search Tasks**: Find and reference existing tasks across your ClickUp Spaces ## Prerequisites * A **ClickUp workspace** with access to the Spaces you want to connect * An active **Overcut workspace** * A **dedicated ClickUp service account** with **Admin** (or Owner) role for initial setup. Can be downgraded to **Member** after OAuth authorization ## Setup Overview ClickUp authorization is tied to a specific user account and workspace. Because Overcut operations appear under the authorizing user's name, use a **dedicated service account** rather than a personal account. **Service Account Advantages:** * **Consistent Bot Identity**: All automated actions appear under a single, recognizable bot user * **Loop Prevention**: Overcut can reliably filter out its own activity to avoid infinite trigger loops * **Independence**: The integration survives team member departures and role changes * **Clear Attribution**: Team members can distinguish automated changes from manual work ClickUp charges per workspace member. Factor in the additional seat cost when creating a dedicated service account. ## Setup Steps Create a dedicated account to act as the Overcut bot identity. 1. **Create a new ClickUp user** in your workspace: * Name: `Overcut Bot` (or similar) * Email: Use a shared/team-managed email (e.g., `overcut-bot@yourcompany.com`) 2. **Grant access** to the Spaces where you want Overcut to operate 3. Assign the account an **Admin** role in the workspace. This is required for the initial OAuth authorization Using a dedicated service account ensures Overcut's access remains stable even if team members leave, and provides a clear, consistent identity for all bot operations. 1. **Sign in to ClickUp** as the service account. 2. In the same browser, open your Overcut workspace, select **Integrations**, select **Add Provider**, then select **ClickUp**. 3. In **Connect to ClickUp**, confirm you are signed in as the service account and select **I am ready to continue**. ClickUp opens in a browser popup. 4. Approve access for Overcut. Overcut confirms the connection and lists the workspace under **Integrations**. After OAuth authorization is complete, you can reduce the service account's role to **Member**. Member access is sufficient for all ongoing Overcut operations: creating tasks, posting comments, managing webhooks, and receiving events. The account only needs access to the relevant Spaces. ClickUp validates that the webhook creator still has access to the target Space before each webhook fires. As long as the service account remains a Member with access to the connected Spaces, webhooks will continue to work. Register the ClickUp Spaces that you want to use in Overcut. 1. On the **Integrations** page, open the connected ClickUp workspace. 2. Select **Add Spaces**. 3. Choose the accessible Spaces that you want to register, then select **Add Selected Spaces**. 4. Confirm that the Spaces appear in the connected workspace's **Spaces** list. 5. Test the connection by creating a simple workflow with a ClickUp trigger. ## Connect another workspace Each ClickUp connection represents one workspace. To connect another, select **Add Provider**, choose **ClickUp**, and repeat the authorization while signed in as that workspace's service account. Open the new workspace under **Integrations** to add its Spaces separately. For popup and confirmation details shared by all providers, see [Connect a provider](/docs/integrations/overview#connect-a-provider). ## Using ClickUp in Your Workflows Once connected, ClickUp Spaces appear as available ticket repositories when you: * Add a **Source** to a workflow * Configure a **Trigger** that monitors ClickUp events (task creation, updates, status changes, comments) * Set up **Actions** that create, update, or comment on tasks ### Common Operations Generate a new ClickUp task from any trigger: failing CI run, Slack command, or scheduled check. Edit titles, descriptions, tags, assignees, or statuses as your workflow progresses. Post automated comments to keep task threads in sync with workflow progress. Mark tasks as complete or closed when a pipeline finishes or a condition is met. ### Example Workflow ```yaml theme={"dark"} steps: - id: "clone-repo" action: "git.clone" params: repoFullName: "{{outputs.[identify-repos].[0].repoFullName}}" branch: "main" - id: "analyze-task" action: "agent.run" params: instruction: | Analyze ClickUp task #{{trigger.issue.number}}: "{{trigger.issue.title}}" Description: {{trigger.issue.body}} Provide a fix and update the task with your findings. ``` ## Provider-Specific Behaviors * **Workspace connections**: Each ClickUp connection represents one workspace. Add and manage that workspace's Spaces from its entry on the **Integrations** page. * **Space as Repository**: Each ClickUp Space you select is treated as a separate ticket repository in Overcut. You can target specific Spaces in triggers and actions. * **Tags as Labels**: ClickUp tags are mapped to the normalized `labels` field. Use tag names in trigger filters and workflow conditions. * **Custom Statuses**: ClickUp supports custom statuses per Space. Trigger filters for **Status From** and **Status To** use the exact status names configured in your Space (for example, "To Do", "In Progress", or "Complete"). * **Status Transitions**: ClickUp provides both the previous and new status for status change events, so both `trigger.statusFrom` and `trigger.statusTo` are available. * **Task relationships**: Agents can create, remove, and read linked task relationships in ClickUp. ClickUp supports a single link type, `related` (pass that value or omit the type). Linking is scoped to the connected workspace and Space. See the [tools reference](/docs/reference/tools) for how linked relationships work across providers. * **Task Title in Webhooks**: ClickUp webhook payloads for non-creation events may not include the task title. For these events, `trigger.issue.title` may be empty. ## Permissions The ClickUp OAuth integration grants full API access to the authorized workspace. Overcut uses these permissions to: * Read and write tasks across selected Spaces * Create and manage comments * Create webhooks for event notifications * Access Space and workspace information Scope your service account's access to only the relevant Spaces to follow the principle of least privilege. ## Next Steps * Learn about [workflow quick starts](/docs/quick-starts/index) for automation recipes * Set up [repository mapping](/docs/repositories/repository-mapping) to link ClickUp Spaces to code repositories * Explore [triggers](/docs/workflows/triggers) to automate workflows from ClickUp events # Custom Events Source: https://docs.overcut.ai/docs/integrations/custom-events Define your own event types and trigger Overcut workflows from any third-party system via a public webhook URL. Custom Events let your workspace expose webhook URLs that any third-party system can call to trigger workflows. Each event has a unique URL, an optional authentication header, and a free-form JSON payload that your workflows can filter on. Use Custom Events to wire SDLC tools that Overcut does not have a native integration for: CI servers like Jenkins, monitoring platforms like Datadog or Grafana, internal scripts, or any service that can send an HTTP request. If you use GitHub, GitLab, Bitbucket, Azure DevOps, Jira, Linear, ClickUp, or Slack, prefer the [native integrations](/docs/integrations/overview) instead. Native integrations handle authentication, event normalization, and reply-target routing for you. Custom Events are for everything else. The Custom Events page in workspace settings, showing six events with name, description, category, auth mode, scope, and timestamps. ## How it works A workspace admin creates a Custom Event in the workspace, picks an authentication mode, and decides which projects can react to it. Overcut returns a stable URL on the dispatcher (e.g. `https://workflow-dispatcher.overcut.ai/trigger-event/`) and, if you chose Bearer or Custom header auth, a one-time secret. Configure the third-party tool to POST a JSON body to that URL when its event fires. Optional query params let you target a specific project or serialize concurrent calls. Workflows in the allowed projects pick the event from the trigger picker and filter on payload fields. See [Custom Events in workflows](/docs/workflows/custom-events). ## Permissions Custom Events are workspace-scoped. The four permissions are granted to workspace admins by default: | Permission | Allows | | -------------------- | ------------------------------------------------------------------------- | | `customEvent.view` | List events, see webhook URLs | | `customEvent.create` | Create a new event | | `customEvent.edit` | Edit fields, change allowed projects, rotate the URL token or auth secret | | `customEvent.delete` | Delete an event | Granting `customEvent.edit` lets a user add any project in the workspace to an event's allowlist. Project admins cannot add their own project to an event's allowlist on their own. ## Create a Custom Event From the workspace sidebar, click Custom Events. The list shows every event defined in the workspace. Fill in the form: * **Name**: lowercase letters, digits, dashes, underscores. Must be unique in the workspace. Example: `deployment_completed`. This is the slug your workflows reference. * **Description**: optional short note for other admins. * **Category**: required free-form label used to group events in the workflow trigger picker (for example, `Deployments`, `Incidents`). The field autocompletes from categories already in use in this workspace. * **Auth mode**: see [Authentication](#authentication) below. * **Scope**: **All projects** (default) or **Specific projects**. With **Specific projects**, pick which projects can react to this event. If you chose **Bearer token** or **Custom header**, Overcut shows the generated secret in a green New secret panel: Make sure to copy your new secret now. You won't be able to see it again. Click Copy secret and store it in the sending system's configuration. The event detail page shows the **Webhook URL** masked by default. Click Show to reveal it, Copy to copy it to the clipboard, or Example to expand a ready-to-paste curl snippet and use Copy curl. The Custom Event detail page for deployment_completed, with a masked webhook URL, Bearer token authentication, and an All projects scope. The auth secret is hashed before it is stored. If you lose it, the only recovery is to rotate (see [Rotate](#rotate-the-url-token-or-secret) below). The webhook URL itself is always retrievable from the event detail page. ## Authentication Pick one auth mode when you create the event. You can change it later. The sender includes a standard `Authorization: Bearer ` header on every request. ```bash theme={"dark"} curl -X POST 'https://workflow-dispatcher.overcut.ai/trigger-event/' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"environment":"production","status":"success"}' ``` Bearer is the right default for almost every integration: scripts, CI jobs, Datadog, Grafana, Jenkins. The secret can be auto-generated by Overcut or pasted in if the sending system already has one to reuse. The sender includes a header whose name and value you both choose. Use this when the third-party tool forces a specific header (for example, `X-API-Key: `). ```bash theme={"dark"} curl -X POST 'https://workflow-dispatcher.overcut.ai/trigger-event/' \ -H 'X-API-Key: ' \ -H 'Content-Type: application/json' \ -d '{"environment":"production","status":"success"}' ``` The header name lookup is case-insensitive. The value is compared after trimming whitespace. No auth header is required. The URL token alone authenticates the request. Use this only for low-risk events from systems inside your network, or for prototypes. Anyone who has the URL can fire the event. ```bash theme={"dark"} curl -X POST 'https://workflow-dispatcher.overcut.ai/trigger-event/' \ -H 'Content-Type: application/json' \ -d '{"environment":"production","status":"success"}' ``` ## Target a specific project Append `?projectId=` to fire the event in a single project instead of fanning out to every project the event allows: ```bash theme={"dark"} curl -X POST 'https://workflow-dispatcher.overcut.ai/trigger-event/?projectId=abc123' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"environment":"production"}' ``` The project must be in the event's allowlist. If it is not, the dispatcher returns `403 project_not_allowed`. If you omit `projectId`, the event fans out: every project that allows it receives an independent firing evaluated against its own workflows. ## Serialize concurrent calls with lockKey By default, two requests arriving at the same time run two parallel workflow executions. If you want to serialize, pass `?lockKey=`: ```bash theme={"dark"} # Two deploys to the same service: serialize. curl ... '?lockKey=service-api' # Deploys to different services: still parallel. curl ... '?lockKey=service-web' ``` Requests sharing the same `(event, lockKey)` pair run one at a time, and within a short dedupe window collapse into a single queued execution per workflow. Allowed characters: letters, digits, `_`, `.`, `-`, `:`, up to 128 chars. A good `lockKey` is whatever identifies the real-world thing the event is about: the deployment target, the incident ID, the environment name. Calls about the same object serialize, calls about different objects run in parallel. ## Improve how runs appear in Overcut Four optional top-level fields in the payload control how the workflow run looks in Overcut's run list. They are also still readable from `payload.*` in trigger conditions. | Field | What it sets | Default if absent | Example | | -------------- | ------------------------------------ | ----------------- | ------------------------------ | | `objectName` | The run's label in the run list | the event's slug | `"Deploy #1234 to production"` | | `objectNumber` | The run's object number badge | empty | `"1234"`, `"INC-567"` | | `objectUrl` | The click-through link from the run | empty | URL back to the source run | | `actor` | The run's actor (displayed as a Bot) | none | `"deploy-bot"` | Send them like any other payload field: ```bash theme={"dark"} curl -X POST 'https://workflow-dispatcher.overcut.ai/trigger-event/' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "objectName": "Deploy #1234 to production", "objectNumber": "1234", "objectUrl": "https://github.com/acme/api/actions/runs/1234", "actor": "deploy-bot", "environment": "production", "status": "success" }' ``` ## Send events from your tools The four recipes below cover some common SDLC integrations. They all use the canonical `Bearer` token auth. For the complete request and response contract, see the [Custom Events API reference](/docs/reference/custom-events-api). ### curl (universal baseline) Any shell script or service that can run `curl` can fire an event: ```bash theme={"dark"} curl -X POST 'https://workflow-dispatcher.overcut.ai/trigger-event/' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "objectName": "Nightly backup", "status": "success", "duration_seconds": 412 }' ``` If the sender can only do GET requests, all payload data can ride in the query string instead. Query keys merge into the payload as top-level fields. Body values win on conflicts. ```bash theme={"dark"} curl 'https://workflow-dispatcher.overcut.ai/trigger-event/?status=success&duration_seconds=412' ``` ### Jenkins Use the [HTTP Request plugin](https://plugins.jenkins.io/http_request/) in a post-build step or `Jenkinsfile` stage to notify Overcut when a build finishes. **Declarative pipeline:** ```groovy theme={"dark"} post { always { httpRequest( httpMode: 'POST', url: 'https://workflow-dispatcher.overcut.ai/trigger-event/', contentType: 'APPLICATION_JSON', customHeaders: [[name: 'Authorization', value: "Bearer ${env.OVERCUT_SECRET}"]], requestBody: """{ "objectName": "${env.JOB_NAME} #${env.BUILD_NUMBER}", "objectNumber": "${env.BUILD_NUMBER}", "objectUrl": "${env.BUILD_URL}", "status": "${currentBuild.currentResult}" }""" ) } } ``` Store the Overcut secret as a Jenkins credential and inject it via `withCredentials` so it never lands in a build log. ### Datadog monitors Datadog's [Webhooks integration](https://docs.datadoghq.com/integrations/webhooks/) sends a POST when a monitor triggers. Configure one webhook per Overcut event you want to fire, then reference it with `@webhook-` in any monitor's notification message. **Webhook configuration (Datadog → Integrations → Webhooks):** * **URL**: `https://workflow-dispatcher.overcut.ai/trigger-event/` * **Custom Headers** (JSON): ```json theme={"dark"} { "Authorization": "Bearer " } ``` * **Payload**: ```json theme={"dark"} { "objectName": "$EVENT_TITLE", "objectNumber": "$ID", "objectUrl": "$LINK", "actor": "datadog", "status": "$ALERT_STATUS", "priority": "$ALERT_PRIORITY", "query": "$ALERT_QUERY" } ``` A workflow listening on this event can filter on `payload.status == "alert"` and read the full Datadog metadata from `payload.*`. ### Grafana Alerting Configure a Grafana [webhook contact point](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/) and assign it to a notification policy. **Contact point (Alerting → Contact points → New contact point):** * **Integration**: Webhook * **URL**: `https://workflow-dispatcher.overcut.ai/trigger-event/` * **HTTP method**: `POST` * **Authorization Header Scheme**: `Bearer` * **Authorization Header Credentials**: `` Grafana sends an Alertmanager-shaped JSON body. Workflows read individual alerts from `payload.alerts[*]`. For richer run-list display, switch to a **Custom Payload** template and project `objectName`, `objectNumber`, and `objectUrl` into the body. ## Rotate the URL token or secret Both the URL token and the auth secret can be rotated independently from the event detail page. * **Rotate URL token**: invalidates the current webhook URL and generates a new one. Any sender still using the old URL starts getting `404 token_invalid` immediately. * **Rotate secret**: invalidates the current auth secret and shows the new one in the same one-time **New secret** panel. The URL keeps working. When rotating the secret, you can either let Overcut generate a new value or enter one yourself in the **New secret (optional)** field (useful when the sending system already has a secret you want to reuse). Rotation takes effect immediately, with no overlap period. Update the sending system before you rotate, or expect a short window of `401 auth_invalid` responses. ## Change scope or rename * **Change scope** (All projects ↔ Specific projects, or edit the allowed projects list) takes effect immediately. Workflows in newly-excluded projects silently stop firing for the event. * **Rename** the event (change its `name` slug) requires updating the trigger source in any workflow that references the old slug. Trigger picker entries for the old slug stop matching incoming events. ## Delete an event Deleting an event invalidates the URL immediately (the dispatcher returns `404 token_invalid`) and stops every workflow that was triggering on the event. Past workflow runs are preserved and continue to show the event's slug as their trigger; the runs are not retroactively edited. ## Next steps Pick the event in the trigger picker, filter on `payload.*` fields, and access event data in downstream steps. Full request and response contract: every header, query param, error code, and limit. # Connect to GitHub Source: https://docs.overcut.ai/docs/integrations/github Connect Overcut to your GitHub repositories and issues to manage code, pull requests, and project tracking directly from your workflows. Connect Overcut to your GitHub repositories and issues to seamlessly integrate source code management and project tracking into your workflows. Once connected, agents can discover your GitHub repositories, work with code directly, and manage issues and pull requests. This page covers the concepts that apply to every GitHub connection. **The exact setup steps depend on where Overcut runs** - pick your path in [Which setup do I need?](#which-setup-do-i-need) below. ## What You Can Do With GitHub connected, Overcut agents can: * **Access Repositories**: Clone, read, and modify code in your GitHub repositories * **Manage Issues**: Create, update, and comment on GitHub issues * **Handle Pull Requests**: Review, comment on, and manage pull requests * **Code Operations**: Clone repositories, create branches, and perform git operations * **Webhook Triggers**: Automatically start workflows based on GitHub events * **Repository Configuration**: Configure agent behavior per repository ## Which setup do I need? One question decides your path: **where Overcut runs**. | Where Overcut runs | Follow this guide | | ----------------------- | ------------------------------------------------------------------------ | | Overcut Cloud (managed) | [GitHub on Overcut Cloud](/docs/integrations/github/cloud) | | Self-hosted Overcut | [GitHub from self-hosted Overcut](/docs/integrations/github/self-hosted) | Managed Overcut. Install the managed Overcut GitHub App. No credentials to manage. Overcut on your own infrastructure. Create your own GitHub App and configure the deployment with its credentials. ## Using GitHub in Your Workflows Once connected, GitHub repositories will appear as available sources when you: * Add a **Source** to a workflow * Configure a **Trigger** that monitors GitHub events * Set up **Actions** that work with code or issues ### Example Workflows * **Code Review Automation**: Automatically review pull requests and provide feedback * **Issue Triage**: Convert GitHub issues to structured tasks or create follow-up tickets * **Documentation Updates**: Keep documentation in sync with code changes * **Release Management**: Track all issues and PRs related to a specific release * **Bug Investigation**: Clone repositories and analyze code to understand reported issues For workflows that need to automatically identify which code repositories are most relevant to GitHub issues, consider using the repo.identify action. This action uses AI-powered analysis and repository correlations to determine the best repositories to work with for each issue. Learn more in our Repository Mapping guide. ## Working with Repositories ### Trigger GitHub Actions from Overcut Overcut can **directly trigger a GitHub Actions workflow** as part of your automation. Add a `ci.executeWorkflow` step to your workflow and specify the repository, workflow file, ref (branch or tag) and any inputs your Action expects. ```yaml theme={"dark"} steps: - id: "build-and-test" name: "Build & Test (GitHub Actions)" action: "ci.executeWorkflow" params: provider: "github" repoFullName: "owner/repo" workflowId: "ci.yml" # can be the file name or a run-id ref: "main" # branch, tag or SHA waitForCompletion: true # set false for fire-and-forget inputs: node-version: "18" run-tests: "true" ``` When `waitForCompletion` is `true`, the step enters a **Waiting for External** status until GitHub reports the workflow finished. See the dedicated documentation for full parameter list and advanced options: **[Execute CI Workflow](/docs/workflows/ci-execute-workflow)**. ### Cloning Code Agents can clone GitHub repositories using the `git.clone` action: ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "owner/repository-name" branch: "main" cloneOptions: depth: 1 singleBranch: true ``` ### Repository Configuration Each connected repository exposes a **Configuration** panel where workspace admins can override agent behavior: | Setting | Default | Purpose | | ----------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------- | | **Agent image** | *(default image)* | Choose the container environment agents run in. See [Repository Agent Image](/docs/repositories/agent-image). | | **Enable cache** | `false` | Persist build artefacts to speed up subsequent runs | | **Cache dependencies** | `false` | Include dependency directories (e.g., `node_modules`) | | **Tools** | `[]` | Define repo-specific commands like `lint`, `test`, `install` | | **Custom instructions** | `null` | Inject additional workflow steps (YAML/Markdown) | ## Working with Issues and Pull Requests ### GitHub Issues Agents can work with GitHub issues through: * **Issue Creation**: Create new issues with descriptions, assignees, and labels * **Issue Updates**: Modify existing issues and change their status * **Comments**: Leave comments on issues with rich text formatting * **Label Management**: Add, remove, and manage issue labels * **Assignee Management**: Assign and unassign team members ### Pull Requests Agents can handle pull requests by: * **Code Review**: Analyze code changes and provide feedback * **Comment Integration**: Add inline and general comments on PRs * **Status Updates**: Track PR lifecycle from creation to merge * **Automated Checks**: Run tests, linting, and validation ## Webhook Triggers GitHub integration enables automatic workflow triggers based on repository events: ### Issue Events * `issue_opened` - Issue was created * `issue_closed` - Issue was closed * `issue_edited` - Title or body changed * `issue_assigned` - Assignee added * `issue_unassigned` - Assignee removed * `issue_labeled` - Label was added * `issue_unlabeled` - Label was removed * `issue_commented` - New comment was posted ### Pull Request Events * `pull_request_opened` - Pull request was opened * `pull_request_closed` - Pull request was closed without merge * `pull_request_merged` - Pull request was merged into base * `pull_request_edited` - Title or description of PR was changed * `pull_request_reviewed` - A review was submitted * `pull_request_commented` - A comment was posted on the PR ### Slash Commands Trigger workflows manually using slash commands in GitHub comments: * Use `@overcut /command` in issue or PR comments * Commands execute immediately for responsive user experience * Works across all platforms: GitHub, Jira, GitLab, and more ## Permissions In every setup, the GitHub App Overcut connects through needs read and write access to repository contents, issues, pull requests, and Actions, plus read access to metadata and organization members. **Who owns the app differs by path** (on Overcut Cloud it is the managed Overcut app; self-hosted deployments create their own), so the exact configuration is listed on each connection guide: * [GitHub on Overcut Cloud](/docs/integrations/github/cloud) * [GitHub from self-hosted Overcut](/docs/integrations/github/self-hosted) ## Advanced Features ### Sparse Checkout For large repositories, use sparse checkout to focus on specific components: ```yaml theme={"dark"} steps: - id: "clone-large-repo" name: "Clone Large Repository" action: "git.clone" params: repoFullName: "company/monorepo" cloneOptions: sparseCheckout: enabled: true paths: - "src/frontend" - "docs" - "scripts" ``` ### Partial Cloning Optimize cloning performance with partial clone filters: ```yaml theme={"dark"} cloneOptions: depth: 1 # Shallow clone (latest commit only) singleBranch: true # Clone only the specified branch filter: type: "blob:none" # Exclude binary files size: "100M" # Skip files larger than 100MB ``` ## Troubleshooting General issues are covered below. For path-specific problems (app configuration, callback URLs, webhook setup), see the troubleshooting section on your connection guide. ### Connection Issues * Ensure you have admin permissions in your GitHub organization * Try disconnecting and reconnecting the integration * Check that your GitHub account is accessible and not rate-limited ### Permission Errors * Verify the connected GitHub App has the necessary permissions in GitHub * Check that you're trying to access repositories you have access to * Ensure your GitHub user account has appropriate permissions ### Missing Repositories * The integration only shows repositories included in the app installation * Check your GitHub user permissions for specific repositories * Verify the repository names are correctly configured ## Getting Help If you encounter issues with the GitHub integration: 1. Check the troubleshooting section on your connection guide 2. Review your GitHub permissions and repository access 3. Contact Overcut support with specific error messages 4. Ensure your GitHub account is active and accessible 5. Check GitHub's status page for any service issues ## Best Practices ### Repository Organization * Use consistent naming conventions for repositories * Organize repositories by team or project * Set up branch protection rules for important branches ### Workflow Design * Start with simple triggers and gradually add complexity * Use delays for issue/PR creation to allow complete context * Test workflows in development repositories first ### Security Considerations * Regularly review app permissions and repository access * Use organization-level installations for team-wide access * Monitor workflow execution logs for unexpected behavior # GitHub on Overcut Cloud Source: https://docs.overcut.ai/docs/integrations/github/cloud Connect GitHub to Overcut's managed service by installing the Overcut GitHub App. Use this path when you use **Overcut's managed service** (Overcut Cloud). You install the managed **Overcut GitHub App** from within your workspace; there are no credentials to manage, no app to create, and no webhook to register. Not your setup? See [Which setup do I need?](/docs/integrations/github#which-setup-do-i-need) If you run **Overcut on your own infrastructure**, follow [GitHub from self-hosted Overcut](/docs/integrations/github/self-hosted) instead. ## Prerequisites * A **GitHub account** with access to repositories you want to connect * **Admin permissions** to install GitHub Apps in your repositories or organization * An active Overcut Cloud workspace ## Connect In your Overcut workspace, go to **Integrations**, select **Add Provider**, then select **GitHub**. GitHub opens in a popup. Choose the personal account or organization where you want to install the app. You need permission to install GitHub Apps for that account or organization. Choose whether the Overcut GitHub App can access all repositories or only selected repositories. For least-privilege access, select only the repositories you plan to use with Overcut. Complete the installation in GitHub. Overcut confirms the connection and lists the account or organization under **Integrations**. App access determines which repositories Overcut can offer; it does not register them. Follow [Repositories](/docs/get-started/repositories) to register and activate repositories for automations and projects. To connect another organization or account, select **Add Provider** and choose **GitHub** again. Each installation appears separately under **Integrations**. To add or remove repository access for an existing installation, use its **Configure** page on GitHub (**Organization settings -> GitHub Apps -> Overcut -> Configure**); Overcut picks up the change automatically. For popup and confirmation details shared by all providers, see [Connect a provider](/docs/integrations/overview#connect-a-provider). ## Permissions The managed Overcut GitHub App requests the following permissions: ### Repository Access * **Contents**: Read and write access to repository code * **Issues**: Read and write access to issues and comments * **Pull Requests**: Read and write access to pull requests and reviews * **Actions**: Read and write access to trigger and monitor GitHub Actions workflows * **Metadata**: Read access to repository metadata ### Organization Access * **Members**: Read access to organization members (for assignment features) * **Organization**: Read access to organization information These permissions allow Overcut to fully integrate with your GitHub workflow while maintaining security and following GitHub's best practices. ## Troubleshooting ### Connection issues * If the GitHub popup was blocked, allow popups for Overcut and try again * Ensure you have admin permissions in your GitHub organization * Try disconnecting and reconnecting the integration * Check that your GitHub account is accessible and not rate-limited ### Missing repositories * The integration only offers repositories included in the app installation. Review the installation's **Configure** page on GitHub * Check your GitHub user permissions for specific repositories * If the repository is accessible but not yet available to automations or projects, [register and activate it in Overcut](/docs/get-started/repositories) For what agents can do once connected (repositories, issues, pull requests, triggers), see the [GitHub overview](/docs/integrations/github). # GitHub from self-hosted Overcut Source: https://docs.overcut.ai/docs/integrations/github/self-hosted Connect GitHub.com to a self-hosted Overcut deployment by creating your own GitHub App. Use this path when you run **Overcut on your own infrastructure** and your code lives on **GitHub.com**. Instead of the managed Overcut GitHub App, your deployment uses a GitHub App that **you create and own**. All tokens, webhooks, and repository access stay between your GitHub organization and your deployment; nothing goes through Overcut Cloud. Not your setup? See [Which setup do I need?](/docs/integrations/github#which-setup-do-i-need). On **Overcut Cloud**, use the managed [Overcut GitHub App](/docs/integrations/github/cloud) instead - no app creation or environment configuration is needed there. ## Prerequisites * A **GitHub organization** (or personal account) with admin access, so you can create and install GitHub Apps * A running self-hosted Overcut deployment with a public HTTPS domain (`https://`) * **Inbound reachability from GitHub.com**: GitHub must be able to deliver webhooks to `https:///hooks/...` over port 443 * The ability to set environment variables on the deployment and restart it ## How it works Your GitHub App is the identity Overcut uses on GitHub: 1. **API access** - Overcut authenticates as the app installation and gets short-lived installation tokens to clone repositories, open pull requests, and manage issues. No personal access tokens are involved. 2. **Webhooks** - GitHub delivers events (issues, pull requests, comments, CI runs) to your deployment, signed with the webhook secret you configure. The effective access is always the app's permissions intersected with the repositories you select when installing the app. ## Step 1: Create the GitHub App In your GitHub organization, go to **Settings -> Developer settings -> GitHub Apps -> New GitHub App** (for a personal account: **Settings -> Developer settings -> GitHub Apps**). * **GitHub App name**: something identifiable, for example `Overcut (Acme)`. The name determines the app **slug** used in the installation URL. * **Homepage URL**: `https://` Under **Identifying and authorizing users**, set **Callback URL** to: ``` https:///github-auth-app/callback ``` Check **Request user authorization (OAuth) during installation**. This is required: without it, connecting from Overcut fails. Under **Post installation**, the **Setup URL** field is disabled once user authorization is enabled. GitHub redirects to the callback URL instead. Under **Webhook**: * **Active**: checked * **Webhook URL**: ``` https:///hooks/github/webhook ``` * **Webhook secret**: generate a strong random value and keep it - you set it on the deployment as `GITHUB_WEBHOOK_SECRET` in Step 2: ```bash theme={"dark"} openssl rand -hex 32 ``` Under **Permissions**, configure: **Repository permissions** | Permission | Access | Why | | ------------- | --------------------------- | ---------------------------------------------------------------------- | | Contents | Read and write | Clone repositories, create branches, push changes | | Issues | Read and write | Read, create, and comment on issues | | Pull requests | Read and write | Open, review, and comment on pull requests | | Metadata | Read-only | Mandatory baseline (GitHub sets this automatically) | | Actions | Read and write | Receive CI events (`workflow_run`) and manage workflow runs | | Workflows | Read and write *(optional)* | Only if agents should create or modify files under `.github/workflows` | **Organization permissions** | Permission | Access | Why | | ---------- | --------- | ---------------------------------------------------- | | Members | Read-only | Resolve organization members for assignment features | Under **Subscribe to events**, enable exactly these: * **Issues** * **Issue comment** * **Pull request** * **Pull request review** * **Pull request review comment** * **Pull request review thread** * **Workflow run** Other event types are ignored by Overcut. Select **Only on this account** (recommended) unless you need to install the same app into multiple GitHub organizations. Click **Create GitHub App**. From the app's settings page, collect: * **App ID** (shown in the About section) * **Client ID** * **Client secret** - click **Generate a new client secret** * **Private key** - click **Generate a private key**; a `.pem` file downloads * **App slug** - the URL-safe name visible in the app's public link (`https://github.com/apps/`) ## Step 2: Configure the deployment Set these environment variables on your deployment: | Variable | Value | | ----------------------------- | -------------------------------------------------------------------- | | `GITHUB_APP_APP_ID` | The **App ID** | | `GITHUB_APP_CLIENT_ID` | The **Client ID** | | `GITHUB_APP_CLIENT_SECRET` | The generated **client secret** | | `GITHUB_APP_PRIVATE_KEY` | The private key as a **single line** with `\n` escapes (see below) | | `GITHUB_APP_INSTALLATION_URL` | `https://github.com/apps//installations/new?state={state}` | | `GITHUB_WEBHOOK_SECRET` | The **webhook secret** you set on the app | | `INTEGRATION_GITHUB_ENABLED` | `true` | | `DISPATCHER_BASE_URL` | `https:///hooks` | Keep the literal `{state}` placeholder in `GITHUB_APP_INSTALLATION_URL` - do not replace it. Overcut substitutes the workspace identifier at connect time. ### Private key formatting The value must be a single line, so the downloaded PEM must be flattened with literal `\n` sequences in place of newlines (Overcut converts them back at runtime). Generate the value with: ```bash theme={"dark"} awk 'NF {sub(/\r/, ""); printf "%s\\n", $0}' .private-key.pem ``` Paste the output as the value of `GITHUB_APP_PRIVATE_KEY` (no surrounding quotes needed). It should look like: ``` GITHUB_APP_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\nMIIEow...\n-----END RSA PRIVATE KEY-----\n ``` ### Apply the configuration Restart the deployment so the new environment variables take effect. ## Step 3: Connect in Overcut In Overcut, open your workspace's git providers page and click **Connect** on the **GitHub** tile. A popup opens on your GitHub App's installation page. Choose the account or organization to install into, then select **All repositories** or specific repositories. Click **Install & Authorize**. GitHub redirects back to your deployment, the popup closes itself, and the GitHub organization appears as connected in Overcut. In the GitHub App's settings, open **Advanced -> Recent Deliveries**, open any delivery (or comment on a test issue in a connected repository to produce one), and confirm the response code is **200**. To add or remove repositories later, use the installation's **Configure** page on GitHub (**Organization settings -> GitHub Apps -> your app -> Configure**); Overcut picks up the change automatically. ## Troubleshooting * **GitHub tile missing or disabled in Overcut**: `INTEGRATION_GITHUB_ENABLED` is not `true`, or the deployment was not restarted after setting it. * **Connect popup shows a GitHub 404**: the app slug in `GITHUB_APP_INSTALLATION_URL` does not match your app's public URL (`https://github.com/apps/`). * **"Missing GitHub authorization code"**: **Request user authorization (OAuth) during installation** is not enabled on the app. Enable it and connect again. * **"Missing GitHub OAuth client configuration"**: `GITHUB_APP_CLIENT_ID` or `GITHUB_APP_CLIENT_SECRET` is empty on the deployment. * **"GitHub authorization code exchange failed"**: the client ID and secret do not belong to the same app as `GITHUB_APP_APP_ID`, or the connection was retried by reloading the callback page. Start again from the Integrations page. * **"This GitHub installation is not accessible to your GitHub account"**: the GitHub account that finished the install cannot see that installation. Sign in as a member of the organization that owns it. * **Popup stays on "Please wait..." and never closes**: the app's **Callback URL** is missing or wrong. It must be exactly `https:///github-auth-app/callback`. * **"Missing Github configuration" in the deployment logs**: one of `GITHUB_APP_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, or `GITHUB_APP_INSTALLATION_URL` is empty, or the private key was pasted with real line breaks instead of `\n` escapes. * **Webhook deliveries fail with 401**: the app's webhook secret and `GITHUB_WEBHOOK_SECRET` do not match. * **Webhook deliveries time out**: GitHub.com cannot reach `https:///hooks/github/webhook` - check DNS, the TLS certificate, and that port 443 is open to the internet. * **Workflows never trigger even though deliveries return 200**: the relevant event type is not enabled on the app (see the event list above), or the repository is not included in the app installation. * **CI-triggered workflows never fire**: the app is missing the **Actions** permission or the **Workflow run** event subscription. * **Pushes that touch `.github/workflows` are rejected**: grant the app the **Workflows: Read and write** permission, then approve the permission update on the installation. * **After changing app permissions nothing happens**: permission changes must be **approved on the installation** by an organization admin (GitHub sends the org an approval request). For what agents can do once connected (repositories, issues, pull requests, triggers), see the [GitHub overview](/docs/integrations/github). # Connect to GitLab Source: https://docs.overcut.ai/docs/integrations/gitlab Connect Overcut to GitLab.com or a self-hosted GitLab instance so your workspace can work with repositories, issues, merge requests, and GitLab-triggered workflows. ## What You Can Do With GitLab connected, Overcut agents can: * **Access repositories** to clone, read, and update code * **Manage issues** by creating, updating, and commenting on GitLab issues * **Handle merge requests** by reviewing, commenting on, and managing merge requests * **Run code operations** such as cloning repositories and creating branches * **Use webhook triggers** to start workflows from GitLab events * **Configure repositories** for workspace-specific automation ## Prerequisites Before you connect GitLab, make sure you have: * A **GitLab account** on GitLab.com or on your self-hosted GitLab instance * An active Overcut workspace * A **dedicated GitLab service account** with **Maintainer** or **Owner** access to the repositories or groups you want Overcut to use If you plan to connect a self-hosted GitLab instance, also make sure you have: * Your **GitLab instance URL** such as `https://gitlab.example.com`, served over **HTTPS** with a **valid (non self-signed) TLS certificate** * The GitLab instance is **reachable from Overcut** over the public internet so Overcut can complete the OAuth token exchange and call the GitLab API. If the instance sits behind a firewall or VPN, allow Overcut Cloud's [egress IP range](/docs/network-allowlisting) * If you plan to use GitLab **event triggers**, the GitLab instance can also send **outbound webhooks to Overcut** at `https://app.overcut.ai` * An **OAuth Application ID** created in that GitLab instance * An **OAuth Application Secret** created in that GitLab instance * Access to sign in to that GitLab instance as the service account during setup Use a dedicated service account instead of a personal account. This keeps your bot identity consistent, avoids permission changes when teammates leave, and makes automated activity easier to recognize. ## Choose GitLab.com or self-hosted GitLab In Overcut, go to **Integrations**, select **Add Provider**, then select **GitLab**. The **Connect to GitLab** dialog asks which kind of instance you use. Leave **Connect to a self-hosted GitLab instance** turned off. You only need the service account and GitLab.com sign-in. Turn on **Connect to a self-hosted GitLab instance**. Enter the URL and OAuth application credentials for your instance before authorizing access. The self-hosted option displays these fields: * **Instance URL** * **OAuth Application ID** * **OAuth Application Secret** These values are specific to your GitLab instance and are not required for GitLab.com. ## Connect GitLab.com Create or choose a dedicated GitLab user for Overcut. Add the account to the projects or groups you want to connect with **Maintainer** permissions, then sign in to GitLab.com as that account. In **Integrations**, select **Add Provider**, then select **GitLab**. Leave **Connect to a self-hosted GitLab instance** turned off and select **I am ready to continue**. GitLab.com opens in a browser popup. Review the request and approve access for Overcut. ## Connect a self-hosted GitLab instance Create or choose a dedicated GitLab user for Overcut, then add that account to the projects or groups you want to connect. Give the account **Maintainer** or **Owner** access to the repositories and groups you want Overcut to use so it can work with repositories, issues, merge requests, and GitLab-triggered workflows. Overcut connects to self-hosted GitLab using an **instance-wide OAuth application** that a GitLab administrator registers in your GitLab instance. This step gives Overcut the **Application ID** and **Application Secret** it needs, and keeps the integration owned by the organization rather than an individual user or group. An instance administrator must perform this step. If you are not a GitLab administrator, coordinate with the team that manages your GitLab instance. In your self-hosted GitLab instance, go to the **Admin area → Applications** and select **New application**. For full instructions and screenshots, see GitLab's official documentation on [configuring GitLab as an OAuth 2.0 authentication identity provider](https://docs.gitlab.com/integration/oauth_provider/). Use these settings when creating the application: * **Name**: any recognizable label such as `Overcut` * **Redirect URI** (labeled **Callback URL** in GitLab's admin UI): `https://app.overcut.ai/gitlab-auth-app/callback` * **Trusted**: leave disabled * **Confidential**: enabled * **Scopes**: select **`api`** After you save the application, GitLab displays the **Application ID** and **Secret**. Copy both values. You will paste them into Overcut in the next step. GitLab typically shows the Application Secret only once. Store it securely when you first see it; if you lose it, you will need to regenerate the secret in GitLab and update Overcut. In **Integrations**, select **Add Provider**, then select **GitLab**. Turn on **Connect to a self-hosted GitLab instance** and enter: * **Instance URL** * **OAuth Application ID** * **OAuth Application Secret** Select **I am ready to continue**. Your configured GitLab instance opens in a browser popup. Sign in as the dedicated service account if needed, review the request, and approve access to complete the connection. ## Verify the connection Overcut confirms the connection and lists it under **Integrations** (see [Connect a provider](/docs/integrations/overview#connect-a-provider) for the popup and confirmation details). Then confirm it can access what you expect: * Open your repository list in Overcut and confirm the expected GitLab repositories appear * Start creating or editing a workflow and verify you can select the connected GitLab repositories or projects * If you use GitLab event triggers, create a simple test change such as opening an issue, commenting on an issue, updating a merge request, or running a pipeline and confirm the workflow can respond If you manage more than one GitLab environment, confirm that the repositories shown in Overcut belong to the same instance URL you entered during setup. ## Connect another GitLab account or instance Select **Add Provider** and choose **GitLab** again. Leave **Connect to a self-hosted GitLab instance** turned off to authorize another GitLab.com account, or turn it on to connect another self-hosted instance. Each connection appears separately under **Integrations**. ## Troubleshooting If the connection does not work as expected, check the following: * **Wrong instance URL**: Confirm you entered the full URL for the correct GitLab instance * **Wrong OAuth credentials**: Make sure the Application ID and Application Secret come from the same self-hosted GitLab instance you are connecting * **Callback URL mismatch**: If GitLab shows an "invalid redirect URI" error during authorization, edit the OAuth application in GitLab and set the **Callback URL** to exactly `https://app.overcut.ai/gitlab-auth-app/callback`. * **Missing `api` scope**: The OAuth application must have the **`api`** scope selected. If it is missing, edit the application in GitLab, enable the scope, and try connecting again. * **Signed in to the wrong account**: Complete authorization using the dedicated GitLab service account, not a personal account with limited access * **Missing repository or group access**: Verify the service account has **Maintainer** or **Owner** access to the repositories or groups you want to use in Overcut * **Unexpected redirect destination**: For self-hosted connections, authorization should open your own GitLab domain rather than GitLab.com * **Popup blocked or failed**: Allow popups for Overcut in your browser settings, then retry the connection If you still cannot complete setup, repeat the connection flow and re-enter the instance URL and OAuth application credentials carefully. ## GitLab.com vs self-hosted GitLab | Connection type | What you enter in Overcut | Where authorization happens | | ---------------------- | ---------------------------------------------------------------- | --------------------------- | | **GitLab.com** | No instance-specific fields | GitLab.com | | **Self-hosted GitLab** | Instance URL, OAuth Application ID, and OAuth Application Secret | Your GitLab instance | Use GitLab.com when your repositories are hosted on GitLab.com. Use the self-hosted option when your team uses GitLab on a private domain or managed infrastructure. ## What happens after connection Once the connection is complete, Overcut uses the GitLab account and instance you connected for GitLab-related work in your workspace. This means Overcut can use that GitLab instance to: * Access connected repositories * Work with issues and merge requests * Support GitLab-based workflow activity * Respond to supported GitLab events for connected repositories, including issues, issue comments, merge requests, merge request comments, and pipeline activity If you connected a self-hosted GitLab instance, Overcut continues to use that configured instance for repository access and related GitLab activity in your workflows. ## Issue links in GitLab Agents can create, remove, and read GitLab issue links. GitLab supports three link types: `relates_to`, `blocks`, and `is_blocked_by` (agents can inspect the available types before linking). Cross-project linking works when GitLab allows it and the service account can access both projects. See the [tools reference](/docs/reference/tools) for how linked relationships work across providers. ## Using GitLab in Your Workflows Once connected, GitLab repositories will appear as available sources when you: * Add a **Source** to a workflow * Configure a **Trigger** that monitors GitLab events * Set up **Actions** that work with code or issues ## Permissions The GitLab OAuth integration requests the following scope: ### API access * **`api`**: Access needed to work with repositories, issues, merge requests, and related GitLab actions in Overcut # Connect to Jira Source: https://docs.overcut.ai/docs/integrations/jira Connect Overcut to Jira so agents can read, create, and update issues directly from your workflows. Connect Overcut to Jira so agents can discover your projects and work with issues directly. Once connected, agents can read, create, transition, comment on, and link issues as part of your workflows. This page covers the concepts that apply to every Jira connection. **The exact setup steps depend on where Overcut runs and where your Jira lives** - pick your path in [Which setup do I need?](#which-setup-do-i-need) below. ## What You Can Do With Jira connected, Overcut agents can: * **View Projects**: See all Jira projects the connected account has access to * **Create Issues**: Create new tickets with descriptions, assignees, and labels * **Update Issues**: Modify existing tickets and change their status * **Add Comments**: Leave comments on issues with rich text formatting * **Track Changes**: Receive webhook events when issues are created or updated * **Search Issues**: Find specific tickets using JQL queries * **Link Issues**: Create, remove, and read typed relationships between issues ## Which setup do I need? Two questions decide your path: **where Overcut runs** and **where your Jira lives**. | Where Overcut runs | Where your Jira lives | Follow this guide | | ----------------------- | ----------------------------------- | -------------------------------------------------------------------------------- | | Overcut Cloud (managed) | Jira Cloud (`*.atlassian.net`) | [Jira Cloud on Overcut Cloud (Forge app)](/docs/integrations/jira/cloud) | | Self-hosted Overcut | Jira Cloud (`*.atlassian.net`) | [Jira Cloud from self-hosted Overcut](/docs/integrations/jira/cloud-self-hosted) | | Self-hosted Overcut | Jira Server / Data Center (on-prem) | [Jira Server / Data Center](/docs/integrations/jira/data-center) | Overcut Cloud connects to **Jira Cloud only** (the managed Forge app is Cloud-only). On-prem **Jira Server / Data Center** can only be connected from a **self-hosted Overcut** deployment, using your own OAuth credentials on your instance. Managed Overcut + Jira Cloud. Install the Overcut Forge app. No credentials to manage. Self-hosted Overcut + Jira Cloud. Connect directly with your own Atlassian OAuth app (3LO or 2LO). Self-hosted Overcut + on-prem Jira. Connect with an OAuth application link on your instance. ## Using Jira in Your Workflows Once connected, Jira projects appear as available sources when you: * Add a **Source** to a workflow * Configure a **Trigger** that monitors projects * Set up **Actions** that work with tickets ### Example Workflows * **Bug Triage**: Automatically create Jira tickets when bugs are detected in code * **Feature Requests**: Convert GitHub issues to Jira tickets for project tracking * **Status Updates**: Keep Jira tickets updated with latest development progress * **Release Management**: Track all issues related to a specific release For workflows that need to automatically identify which code repositories are most relevant to Jira tickets, consider using the repo.identify action. This action uses AI-powered analysis and repository correlations to determine the best repositories to work with for each ticket. Learn more in our Repository Mapping guide. ## Working with Issues ### Creating Tickets Agents can create new Jira issues with: * Summary and description * Assignee (if specified) * Labels and priority * Project and issue type ### Updating Tickets Agents can modify existing issues by: * Updating fields like summary or description * Changing assignees or labels * Transitioning between statuses (e.g., "In Progress" to "Done") * Adding comments with context ### Finding Issues Search for specific tickets using: * Project key (e.g., "PROJ-123") * JQL queries for complex searches * Status filters (open, closed, in progress) * Assignee or label filters ## Provider-Specific Behaviors * **Status names**: Issue trigger filters (such as **Status From** and **Status To**) use the exact status labels from your Jira project workflow. Use the values shown on the issue or in the project workflow editor, including capitalization and spacing. Jira treats `Done` and `Closed` as distinct statuses even if they share the same status category. * **Linked issues**: Agents can create, remove, and read typed issue links in Jira. Jira uses directional relationship labels such as `blocks` and `is blocked by`, defined in your workspace (agents can inspect the available types before linking). Cross-project linking works when Jira allows it. See the [tools reference](/docs/reference/tools) for how linked relationships work across providers. ## Permissions In every setup, Overcut needs read and write access to projects, issues, and comments. **The exact scopes you grant differ by path** (Jira Cloud uses granular Atlassian scopes; Jira Server / Data Center uses a coarse instance-level scope), so they are listed on each connection guide: * [Jira Cloud on Overcut Cloud (Forge app)](/docs/integrations/jira/cloud) * [Jira Cloud from self-hosted Overcut](/docs/integrations/jira/cloud-self-hosted) * [Jira Server / Data Center](/docs/integrations/jira/data-center) In all cases, the **account you authorize with owns every issue, comment, and transition** Overcut performs, so authorize as a dedicated service account (for example `overcut-bot`), not your personal admin account. ## Troubleshooting General issues are covered below. For path-specific problems (callback URL mismatches, webhook setup, service-account access), see the troubleshooting section on your connection guide. ### Connection Issues * Ensure the connected account has admin permissions in your Jira workspace * Try disconnecting and reconnecting the integration * Check that your Jira instance is accessible ### Permission Errors * Verify the connected app or account has the necessary permissions in Jira * Check that you're trying to access projects the account has access to * Ensure the Jira user account has appropriate project permissions ### Missing Projects * The integration only shows projects the connected account has access to * Check your Jira user permissions for specific projects * Verify the project keys are correctly configured ## Getting Help If you encounter issues with the Jira integration: 1. Check the troubleshooting section on your connection guide 2. Review your Jira permissions and project access 3. Contact Overcut support with specific error messages 4. Ensure your Jira instance is running and accessible # Jira Cloud on Overcut Cloud (Forge app) Source: https://docs.overcut.ai/docs/integrations/jira/cloud Connect Jira Cloud to Overcut's managed service by installing the Overcut Forge app. Use this path when you use **Overcut's managed service** (Overcut Cloud) and your Jira is **Atlassian-hosted Jira Cloud** (`https://.atlassian.net`). You install the Overcut Forge app from the Atlassian Marketplace; there are no credentials to manage. Not your setup? See [Which setup do I need?](/docs/integrations/jira#which-setup-do-i-need) to choose between Overcut Cloud, self-hosted Overcut, and Jira Server / Data Center. ## Prerequisites * An **Atlassian Jira Cloud** workspace (`https://.atlassian.net`) * Admin permissions in your Jira workspace * An active Overcut Cloud workspace ## Connect In your Overcut workspace, go to **Integrations** and click **Connect Jira**. Click **Install Overcut App** to be redirected to your Jira instance. Install the app and grant the necessary permissions. If you've already installed the app, click **I've Installed the App** to proceed. After installing the app, you'll be prompted to enter your Jira site domain (e.g., `my-org.atlassian.net`). Enter your domain and click **Complete Install** to finalize the connection. The Forge app manages authentication, permissions, and event delivery for you. There is no OAuth app to create, no callback URL to configure, and no webhook to register. ## Permissions The Overcut Forge app requests read and write access to projects, issues, and comments, and permission to add comments to existing issues. You grant these when you install the app. ## Troubleshooting * **App not installed**: complete the Marketplace install in Jira first, then click **I've Installed the App** in Overcut. * **Wrong site domain**: make sure the domain you enter matches your site exactly (`my-org.atlassian.net`, no `https://` prefix and no trailing path). * **Missing projects**: the integration only shows projects your Jira account can access. Check your Jira user permissions for the specific projects. For concepts shared across all Jira setups (issue operations, status-name rules, ticket links), see the [Jira overview](/docs/integrations/jira). # Jira Cloud from self-hosted Overcut Source: https://docs.overcut.ai/docs/integrations/jira/cloud-self-hosted Connect Atlassian-hosted Jira Cloud to a self-hosted Overcut deployment using your own OAuth app. Use this path when you run **Overcut on your own infrastructure** and your Jira is **Atlassian-hosted Jira Cloud** (`https://.atlassian.net`). Instead of the managed Forge app, you connect directly with your **own** Atlassian OAuth 2.0 app. Each deployment brings its own credentials; there is no shared Overcut Cloud client. Not your setup? See [Which setup do I need?](/docs/integrations/jira#which-setup-do-i-need). On **Overcut Cloud**, use the [Forge app](/docs/integrations/jira/cloud) instead. For on-prem Jira, see [Jira Server / Data Center](/docs/integrations/jira/data-center). ## Prerequisites * An **Atlassian Jira Cloud** workspace (`https://.atlassian.net`) * Admin access to the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) * A self-hosted Overcut deployment you operate (see [Deployment configuration](#deployment-configuration)) The Atlassian account you authorize with **owns every issue, comment, and transition** Overcut performs. Authorize while signed in as a dedicated service account (for example `overcut-bot`), not your personal admin account. An incognito window is the safe way to avoid consenting as yourself. The service account must be a licensed Jira user with real access to the target projects. ## Choose an authorization type The connect modal has an **Authorization type** toggle: * **User authorization (3LO)** - the default, covered by the steps below. A browser **Authorize** step runs once, and Overcut acts on behalf of the consenting Atlassian service account. Overcut obtains a refresh token so the connection survives long-running sessions. * **Service account (2LO)** - no browser consent. Recommended when your org offers service-account credentials or when an org policy blocks interactive OAuth app authorization. See [Use a service account (2LO)](#use-a-service-account-2lo). The effective permission is always the app's scopes **intersected with** the connected account's actual Jira permissions. ## Connect with user authorization (3LO) Go to the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/), sign in, and select **Create -> OAuth 2.0 integration**. Name it (for example `Overcut`) and accept the terms. Creating the app grants no access by itself, and it does not matter which person creates it. It yields the **Client ID + Secret** that identify the app. In the app's **Permissions** tab, add the **Jira API** and configure **Classic scopes**. Enable exactly these three: * **`read:jira-work`** - view issues, projects, fields, and comments * **`write:jira-work`** - create, update, transition, and link issues and comments * **`read:jira-user`** - resolve the service-account identity (`/myself`) and @mentions **Scopes Used** should read **3**. Do not add the separate **User identity API** or Confluence / Compass scopes. You do not add `offline_access` here - it is a standard OAuth scope, not a Jira API scope. Overcut requests it automatically during authorization to obtain a refresh token. In the **Authorization** tab, add **OAuth 2.0 (3LO)** and set the **Callback URL** to your deployment's Overcut callback, exactly: ``` https:///jira-cloud-auth-app/callback ``` This must match the `JIRA_CLOUD_REDIRECT_URI` server setting character for character (scheme, host, path, no trailing slash), and must use **https** (except `http://localhost:` for local development). In the app's **Settings** tab, copy the **Client ID** and **Secret**. In Overcut, open the git providers list and click the **Jira Cloud (self-hosted connect)** tile. Leave the authorization type as **User authorization (3LO)**. Enter your **Site URL** (`https://.atlassian.net`) and the **Client ID** and **Secret** from the previous step. Make sure your browser session is signed into Atlassian **as the service account**, then click **Authorize**. Overcut resolves your `cloudId` automatically from the site you entered and stores the connection. Webhooks are configured in Jira, separately from the OAuth app. Open the connected org's **settings** page in Overcut (**View settings** on the provider page) to find the webhook **URL** (shaped like `https:///webhooks/jira/cloud/?secret=`). In Jira, go to **Settings (cog) -> System -> WebHooks -> Create a WebHook**, paste the full URL (use **Copy full URL** in Overcut so the real secret is embedded), and under **Events** enable issue **created / updated / deleted** and comment **created / updated / deleted**. Leave the JQL filter empty to receive all projects, or scope it. ## Use a service account (2LO) Use this when you prefer a headless service-account credential over a browser consent, or when an org policy blocks interactive OAuth app authorization. 2LO is available for Jira Cloud only. In **admin.atlassian.com**, create a service account (for example `overcut-bot`). This is the identity every Overcut action will be attributed to. On the service account, click **Grant access** and select your **Jira** app / site. The account must have **product access to the Jira site** and be added to the target project(s) with **Browse Projects** plus the write permissions. Do this **before** creating the credential. Without it, the credential authenticates but every Jira API call returns **403** and Overcut shows "no projects available". On the service account, click **Create credentials**. On the **Choose authentication type** screen, select **OAuth 2.0** (Recommended) and click **Next**. Give the credential a name, then select exactly these three Jira scopes: * **`read:jira-work`** - view issues, projects, fields, and comments * **`write:jira-work`** - create, update, transition, and link issues and comments * **`read:jira-user`** - resolve the service-account identity and @mentions There is **no callback URL** for this credential. Finish, then copy the generated **Client ID** and **Secret**. See Atlassian's [Create an OAuth 2.0 credential for service accounts](https://support.atlassian.com/user-management/docs/create-oauth-2-0-credential-for-service-accounts/) for details. Open the **Jira Cloud (self-hosted connect)** tile and switch the **Authorization type** to **Service account (2LO)**. Enter the **Site URL** plus the credential's **Client ID** and **Secret**, and click **Connect**. There is **no callback URL and no browser Authorize step**. The token *is* the service account; Overcut resolves the `cloudId` from the Site URL and renews by re-requesting (2LO has no refresh token). Webhook setup is identical to the 3LO path - see [Register the webhook in Jira](#connect-with-user-authorization-3lo) above. ## Deployment configuration These settings are configured once by whoever operates the self-hosted Overcut deployment. | Setting | Value | Notes | | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------- | | `INTEGRATION_JIRA_CLOUD_ENABLED` | `true` | Defaults to enabled if unset. Set `false` to hide the tile. | | `JIRA_CLOUD_REDIRECT_URI` | `https:///jira-cloud-auth-app/callback` | Must equal the developer-console Callback URL exactly (3LO only). | | `DISPATCHER_BASE_URL` | `https:///hooks` | External URL used to build the webhook URL shown in Overcut. | ## Troubleshooting * **`redirect_uri` mismatch at Authorize**: the developer-console Callback URL and `JIRA_CLOUD_REDIRECT_URI` are not byte-identical (often a trailing slash or `http` vs `https`). * **"No accessible site matches ..." after consent**: the account you authorized with does not have access to the Site URL you entered, or the Site URL is wrong. The error lists the sites the consent actually granted. * **Actions attributed to the wrong person, or bot loops**: you consented as your personal account instead of the service account. Re-authorize in an incognito window signed in as the bot account. * **Authorize blocked by an org policy**: some organizations restrict external OAuth app authorization (**Admin -> Security -> external app access**). A site admin must allow the app, or use [2LO](#use-a-service-account-2lo) instead. * **2LO connects but every call returns 403 / no projects**: the service account has the OAuth credential but no product access. Grant it Jira product access and **Browse Projects** on the target projects in admin.atlassian.com. * **Webhook events never fire**: confirm the webhook URL still includes `?secret=...`, the issue and comment events are enabled on the Jira webhook, and `DISPATCHER_BASE_URL` is set to the external URL. For concepts shared across all Jira setups (issue operations, status-name rules, ticket links), see the [Jira overview](/docs/integrations/jira). # Jira Server / Data Center Source: https://docs.overcut.ai/docs/integrations/jira/data-center Connect an on-prem Jira Server or Data Center instance to a self-hosted Overcut deployment using an OAuth application link. Use this path when you run **Overcut on your own infrastructure** and your Jira is **self-hosted Jira Server or Data Center** (an on-prem instance, not `*.atlassian.net`). You connect with an **OAuth 2.0 incoming Application Link** created on your Jira instance. Each deployment uses its own client credentials; there is no shared Overcut Cloud client. Not your setup? See [Which setup do I need?](/docs/integrations/jira#which-setup-do-i-need). For Atlassian-hosted Jira Cloud, use the [Forge app](/docs/integrations/jira/cloud) (Overcut Cloud) or [direct OAuth](/docs/integrations/jira/cloud-self-hosted) (self-hosted Overcut). ## How it differs from Jira Cloud | | Jira Server / Data Center | Jira Cloud | | --------------- | --------------------------------------------------- | ----------------------------------------------------- | | OAuth endpoints | Your instance (`{instance}/rest/oauth2/latest/...`) | Atlassian-central (`auth.atlassian.com`) | | Authorization | 3LO only (browser consent) | 3LO or 2LO | | Scope | `WRITE` (coarse, instance-level) | `read:jira-work`, `write:jira-work`, `read:jira-user` | | REST API | v2 (`/rest/api/2`) | v3 + ADF | | Webhook | Manual paste | Manual paste | ## Prerequisites * A **Jira Server or Data Center** instance reachable from your Overcut deployment over **HTTPS** * **Administrator** access to that Jira instance (to create the Application Link and the webhook) * A self-hosted Overcut deployment you operate (see [Deployment configuration](#deployment-configuration)) The Jira account you authorize with **owns every issue, comment, and transition** Overcut performs. Authorize while signed in as a dedicated service account (for example `overcut-bot`), not your personal admin account. An incognito window is the safe way to avoid consenting as yourself. The service account must be a licensed Jira user with real access to the target projects. ## Connect As a Jira administrator, go to **Administration (cog) -> Applications -> Application links** (on some versions this lives under **System -> OAuth**), and create an **incoming** OAuth 2.0 link. Set the **redirect / callback URL** to your deployment's Overcut callback, exactly: ``` https:///jira-server-auth-app/callback ``` This must match the `JIRA_SERVER_REDIRECT_URI` server setting character for character, and must use **https**. Grant the link the **`WRITE`** scope (Jira DC scopes are instance-level: `READ` / `WRITE` / `ADMIN`; `WRITE` covers issue and comment create / update / transition). Save, then copy the generated **Client ID** and **Client Secret**. In Overcut, open the git providers list and click the **Jira Server / Data Center** tile. Enter: * **Instance URL**: your Jira base URL (for example `https://jira.your-company.com`) * the **Client ID** and **Client Secret** from the previous step Make sure your browser session is signed into Jira **as the service account**, then click **Authorize**. Overcut captures the service-account identity and stores the connection. Webhooks are configured in Jira, separately from the Application Link. Open the connected org's **settings** page in Overcut (**View settings** on the provider page) to find the webhook **URL** (shaped like `https:///webhooks/jira/server/?secret=`). In Jira, go to **Settings (cog) -> System -> WebHooks -> Create a WebHook**, paste the full URL (use **Copy full URL** in Overcut so the real secret is embedded), and under **Events** enable issue **created / updated / deleted** and comment **created / updated / deleted**. Leave the webhook configured to **send the issue body** (do not exclude it). Overcut reads the issue description from the webhook payload; if the body is excluded, descriptions arrive empty. Leave the JQL filter empty to receive all projects, or scope it. Save. ## Deployment configuration These settings are configured once by whoever operates the self-hosted Overcut deployment. | Setting | Value | Notes | | --------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `INTEGRATION_JIRA_SERVER_ENABLED` | `true` | Set on both the server and workflow-dispatcher to enable the tile and inbound webhooks. | | `JIRA_SERVER_REDIRECT_URI` | `https:///jira-server-auth-app/callback` | Must equal the Application Link callback URL exactly. | | `DISPATCHER_BASE_URL` | `https:///hooks` | External URL used to build the webhook URL shown in Overcut. | ## Troubleshooting * **`redirect_uri` mismatch at Authorize**: the Application Link callback URL and `JIRA_SERVER_REDIRECT_URI` are not byte-identical (often a trailing slash or `http` vs `https`). * **Authorize fails to reach Jira**: the instance must be reachable from the Overcut deployment over HTTPS with a valid certificate. Confirm network access and TLS. * **Actions attributed to the wrong person, or bot loops**: you consented as your personal account instead of the service account. Re-authorize in an incognito window signed in as the bot account. * **Issue descriptions arrive empty**: the Jira webhook is configured to exclude the issue body. Edit the webhook so it sends the full issue payload. * **Webhook events never fire**: confirm the webhook URL still includes `?secret=...`, the issue and comment events are enabled, and `DISPATCHER_BASE_URL` is set to the external URL with `INTEGRATION_JIRA_SERVER_ENABLED=true` on the dispatcher. For concepts shared across all Jira setups (issue operations, status-name rules, ticket links), see the [Jira overview](/docs/integrations/jira). # Connect to Linear Source: https://docs.overcut.ai/docs/integrations/linear Connect Overcut to your Linear workspace to create, update, and comment on issues directly from your automations. # Linear Integration Overcut connects to Linear so your agents can open, update, and comment on issues without leaving the workflow. After you authorize the connection, Linear teams appear alongside your existing ticket providers, letting you automate planning and status updates across every tool your organisation uses. ## Overview With Linear connected you can: * **Create issues** from detections, check-ins, or any trigger in your workflow * **Update titles, descriptions, labels, and assignees** as work progresses * **Synchronise labels** between Overcut and Linear to ensure workflows can filter and route tickets accurately * **Reference Linear issues** in end-to-end workflow recipes that combine code, data, and planning tasks ## Connecting Linear In Overcut, open **Integrations**, select **Add Provider**, then select **Linear**. Linear opens in a browser popup. Review the request and approve Overcut's access to your Linear workspace. Overcut confirms the connection and lists the workspace under **Integrations**. Open the connected workspace, select **Add Teams**, choose the teams you want to use, then select **Add Selected Teams**. Each selected team becomes a ticket repository you can reference in triggers and actions. To connect another Linear workspace, select **Add Provider** and choose **Linear** again. Adding a workspace is separate from adding more teams from a workspace that is already connected. For popup and confirmation details shared by all providers, see [Connect a provider](/docs/integrations/overview#connect-a-provider). ## Provider-Specific Behaviors * **Team as Repository**: Each Linear team you select is treated as a separate ticket repository. You can target specific teams in triggers and actions just like you would with GitHub or Jira projects. * **Status names**: Issue trigger filters (such as **Status From** and **Status To**) use the exact workflow status names configured for the selected team (for example, Triage, Backlog, In Progress, Done). Names differ by team. Linear provides the destination status but not the previous status, so **Status To** filters work reliably while **Status From** will not match. * **Linked issue relationships**: Agents can create, remove, and read linked issue relationships in Linear. Linear uses its own relationship names (agents can inspect the available types before linking). See the [tools reference](/docs/reference/tools) for how linked relationships work across providers. ## Automations and Agent Workflows Once connected, Linear issues become a first-class citizen inside the Overcut workflow builder. Agents can **create**, **update**, and **comment** on issues the same way they already interact with GitHub or Jira. Generate a new Linear issue from any trigger such as a failing test, Sentry alert, or Slack slash command. Edit titles, descriptions, labels, or assignees as your workflow progresses and new context emerges. Mark issues as Done or Canceled when a pipeline finishes successfully or when a rollback is triggered. ## Next Steps * Learn about [workflow quick starts](/docs/quick-starts) for more automation recipes. # Integration Source: https://docs.overcut.ai/docs/integrations/overview Connect Overcut to your Git repositories, ticket systems, and team chat. Overcut connects to the tools your team already uses. Integrations fall into **three categories**: 1. **Git Integrations**: provide Overcut read and write access to your source code so agents can review, generate, and commit changes directly in your repositories. 2. **Ticket Integrations**: allow Overcut to read, create, and update issues so agents can respond to bugs, feature requests, or tasks in the systems where you plan work. 3. **Chat Integrations**: bring Overcut into team conversations so you can trigger workflows from the channels where work happens. ## Choose the right connection path Use **workspace integrations** when Overcut supports your provider directly. For most teams, this is the best starting point for **GitHub, GitLab, Azure DevOps, Jira, Linear, ClickUp, and Slack** because setup happens inside your workspace and built-in tools work automatically once the connection is in place. Use **MCP servers** when you want to connect a third-party system that does not have a native Overcut integration. You can also use MCP as a supplemental or fallback option for first-class providers when you need external tools or capabilities that are outside the native integration path. * See [MCP Servers](/docs/reference/mcp-servers) for setup and configuration details. * Browse the [MCP Catalog](/docs/quick-starts/mcp-catalog) to install common third-party servers faster. More integrations are on the roadmap. Let us know which systems you'd like to see next. ## Connect a provider You can start a native connection from two places: * During onboarding, on the **Connect your tools** step, select a provider card. * Later, open **Integrations** and select **Add Provider**. The **Add Integration** dialog lists the providers enabled for your deployment. Some providers ask for details first, such as a site, workspace, organization, instance URL, or credentials. The provider then opens in a browser popup. Sign in to the intended account, approve the requested access, and keep the Overcut page open until the popup closes. If you see **Authentication popup was blocked or failed. Please check your browser settings.**, allow popups for your Overcut site in the browser, then start the connection again. When the connection completes, onboarding lists it under **Successfully connected to:**. On the **Integrations** page, a **Connected successfully** dialog appears; select **OK** and the connected provider appears in the list. To connect another organization, account, workspace, or instance for the same provider, select **Add Provider** again and repeat the flow. Connecting a Git provider does not register any repositories by itself. Follow [Repositories](/docs/get-started/repositories) to register and activate the repositories you want Overcut to work with. ## Git Integrations Use native workspace integrations for supported Git providers so agents can work with your repositories through Overcut's built-in tools. Overcut can connect to the following Git providers: * **[GitHub](/docs/integrations/github)** - Connect to GitHub repositories and issues * **[GitLab](/docs/integrations/gitlab)** - Connect to GitLab.com or self-hosted GitLab repositories and issues. * **[Azure DevOps](/docs/integrations/azure-devops)** - Connect to Azure DevOps repositories and work items * **[Bitbucket](/docs/integrations/bitbucket)** - Connect to Bitbucket Cloud repositories and pull requests from Overcut Cloud or a self-hosted Overcut deployment Once connected, agents gain secure, permission-scoped access to clone repositories, create branches, open pull requests, and leave code review comments, without leaving your existing workflows. Learn more about our security architecture, data handling, and privacy practices in our [Privacy and Security](/docs/privacy-and-security) documentation. ### Repository Configuration Each connected repository now exposes a **Configuration** panel where workspace admins can override agent behaviour for that specific codebase. | # | Setting | Default | Purpose | | - | ----------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------- | | ① | **Agent image** | *(default image)* | Choose the container environment agents run in. See [Repository Agent Image](/docs/repositories/agent-image). | | ② | **Enable cache** | `false` | Persist build artefacts to speed up subsequent runs. | | ③ | **Cache dependencies** | `false` | Include dependency directories (e.g., `node_modules`). | | ④ | **Tools** | `[]` | Define repo-specific commands like `lint`, `test`, `install`. | | ⑤ | **Custom instructions** | `null` | Inject additional workflow steps (YAML/Markdown). | Changes are applied immediately and reflected in the audit logs of subsequent automation runs. ## Ticket Integrations Use native workspace integrations for supported ticketing systems so agents can read and update work where your team already plans and tracks delivery. To keep your planning and tracking in sync, Overcut also integrates with popular issue-tracking systems: * **[GitHub Issues](/docs/integrations/github)** - Integrated with GitHub repositories * **[Jira](/docs/integrations/jira)** - Connect to Jira Cloud workspaces from Overcut Cloud or a self-hosted Overcut deployment * **[GitLab Issues](/docs/integrations/gitlab)** - Integrated with GitLab repositories * **[Azure DevOps Work Items](/docs/integrations/azure-devops)** - Integrated with Azure DevOps repositories * **[Linear](/docs/integrations/linear)** - Connect to Linear workspaces and teams * **[ClickUp](/docs/integrations/clickup)** - Connect to ClickUp workspaces and Spaces for task operations Agents can automatically open or update tickets, generate specs, and post status updates, all while maintaining a single source of truth in your ticketing tool. ### Ticket links depend on your provider Some ticket integrations also let agents work with linked relationships between tickets. When a provider supports ticket links, agents can create links, remove links, and read existing relationships to understand how related work connects across your backlog. Available relationship types are defined by the connected provider rather than by one shared Overcut list. Before creating a link, agents can inspect the relationship types that provider makes available and choose from the supported options. Cross-project linking also depends on the connected provider. Some providers allow links across projects or teams, while others limit links to work that lives in the same project, workspace, or repository. For provider-specific ticket link behavior, see [Jira](/docs/integrations/jira), [Linear](/docs/integrations/linear), [ClickUp](/docs/integrations/clickup), [GitLab](/docs/integrations/gitlab), [Azure DevOps](/docs/integrations/azure-devops), [GitHub](/docs/integrations/github), and [Bitbucket](/docs/integrations/bitbucket). ### What agents can do with linked tickets When ticket links are supported by your provider, agents can: * Create linked relationships between tickets * Remove linked relationships that are no longer needed * Read existing links and use them as context when reasoning about related work * Inspect the relationship types your provider supports before creating a link For agents to work with ticket links, make sure the relevant ticket tools (`link_tickets`, `unlink_tickets`, and `get_ticket_metadata`) are selected for the agent in **Agent Roles** → agent settings. See the [tools reference](/docs/reference/tools) for the full list. GitHub and Bitbucket do not support typed ticket links through Overcut's native ticketing integrations. Use the provider pages to confirm what link behavior is available in each system. ## Chat Integrations Use native workspace integrations for supported chat providers so teams can trigger workflows directly from their existing conversations. Chat integrations let your team start workflows from the conversations where work already happens. * **[Slack](/docs/integrations/slack)**: connect Slack at the workspace level, register channels inside each project, and trigger workflows from registered channels. See the [Slack guide](/docs/integrations/slack) for how workspace connections, project channel registration, and channel routing modes work together. ## Custom Events (generic webhooks) For any third-party system Overcut does not have a native integration for, **Custom Events** let a workspace admin define an event type, get a public webhook URL, and pick an authentication mode. Any tool that can send an HTTP request (CI servers like Jenkins, monitoring tools like Datadog or Grafana, internal scripts, low-code platforms) can then fire workflows in the projects you authorize. * **[Custom Events](/docs/integrations/custom-events)**: setup, authentication, project scoping, and ready-to-paste recipes for curl, Jenkins, Datadog, and Grafana. *** ### What’s next? We’re continually expanding our integration surface area. Expect support for additional Git, ticket, and chat systems in future releases. For CI/CD and observability platforms today, see [Custom Events](/docs/integrations/custom-events). # Connect to Slack Source: https://docs.overcut.ai/docs/integrations/slack Connect a Slack workspace to Overcut, register channels per project, and trigger workflows from team conversations. Slack lets your team start and continue Overcut workflows from the channels where work already happens. You connect Slack once at the workspace level, then register the channels each project can use. Once a channel is registered, project workflows can be triggered by `@overcut` mentions, the `/overcut` slash command, or, in **Watch all messages** mode, regular channel messages and thread replies. ## What you can do * Trigger workflows from a registered Slack channel using `@overcut` mentions and the `/overcut` command, or use top-level messages and thread replies when the channel is set to **Watch all messages**. * Configure **Trigger Event** as **thread reply** when you want replies in completed alert, incident, handoff, or triage threads to start a workflow. * Optionally treat every top-level channel message and eligible thread reply as a workflow event (for incident channels, alert channels, or routing on bot posts). * Give agents Slack messaging capabilities so they can post, edit, read, and react in any active Slack channel registered to the current project. * Continue an [interactive session](/docs/reference/interactive-sessions) inside a Slack thread the same way it works on a PR or issue. ## Setup overview Slack works at two levels in Overcut. Each level is configured separately. | Level | Where | What you configure | | --------- | --------------------------------------- | -------------------------------------------------------------------------------- | | Workspace | **Workspace → Integrations** | The OAuth connection to your Slack workspace. Done once per Overcut workspace. | | Project | **Project Settings → Project Channels** | Which Slack channels this project can use, and how each channel routes messages. | See [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces) for the broader workspace-vs-project boundary. ## Connect Slack to your workspace **Self-hosted Overcut?** The managed Overcut Slack app only works on Overcut Cloud. On your own deployment, first create your own Slack app - see [Slack from self-hosted Overcut](/docs/integrations/slack/self-hosted) - then return here for channels and routing. From the workspace sidebar (no project selected), go to **Integrations**. In the providers list, find **Slack** and click connect. You'll be redirected to Slack to authorize the Overcut app for your Slack workspace. Approve the requested scopes in Slack. After approval you return to Overcut and the Slack workspace appears in the connected providers list. You can connect more than one Slack workspace if your team uses several. When you register channels later, you pick which Slack workspace each channel belongs to. ## Register channels in a project Channel registration is per project. A channel must be registered in a project before that project's workflows can be triggered from it or post into it. Inside a project, go to **Project Settings → Project Channels**. Click **Add Channel**, pick the Slack workspace under **Messaging workspace**, then select one or more channels from the list. Click **Add Selected Channels** to register them. Registered channels show in the Project Channels list with the default routing mode, **Mentions only (default)**. Newly created Slack channels may take up to 10 minutes to appear in the channel picker. If a public channel does not appear immediately, wait a few minutes and reopen **Add Channel**. Public channels are joined automatically when you add them. For **private channels**, invite the Overcut bot first by running `/invite @overcut` in the channel. Private channels the bot has not been invited to do not appear in the picker. ### Project-scoped channel behavior * A channel registered in one project is only available to that project's workflows. * The same Slack channel can be registered in more than one project when teams share a channel across workflows. * Removing or deactivating a channel registration stops that project's workflows from receiving `@overcut` mentions, `/overcut` commands, top-level messages, and thread replies from the channel. The Slack workspace connection and any registrations in other projects stay in place. ## Channel routing modes Each registered channel has a **routing mode** that controls which messages reach your workflows. Open the channel row in **Project Channels** to change it. In **Routing for #...**, choose **Mentions only (default)** for passive routing or **Watch all messages** for active routing. Choose **Watch all messages** when you want top-level messages and eligible thread replies to be evaluated as workflow triggers. | Mode | When workflows can fire | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Mentions only (default)** | Passive mode. `@overcut` mentions, `/overcut` slash commands, and thread replies that continue an active session can reach workflows. Thread replies do not create `thread_reply` trigger events in this mode. All other channel chatter is ignored. | | **Watch all messages** | Active mode. Every new top-level message in the channel becomes a `channel_message` event, and every thread reply without a live run or session becomes a `thread_reply` event. Mentions and slash commands still work. | Most channels should stay on **Mentions only (default)**. Switch to **Watch all messages** when you want the channel itself to be the event source: for example, incident channels where every alert from PagerDuty or Datadog should be evaluated, product channels where new top-level posts should be triaged, or handoff threads where later replies should be evaluated after the original run has finished. When you switch to **Watch all messages**, confirm **Watch every message in this channel?** with **Yes, watch all messages**. **Watch all messages** routes every top-level message and eligible thread reply through trigger evaluation, including replies from other services such as alerting or incident bots. Overcut ignores its own Slack messages to prevent loops. Pair this mode with actor, message content, and channel conditions so high-traffic channels don't flood agents with runs. Switching a channel into this mode requires a second confirmation. ## Trigger workflows from Slack Once a channel is registered, the same trigger types you use for repository and ticket events apply. `thread_reply` triggers are evaluated only for registered channels set to **Watch all messages**. They are not evaluated for channels that stay on **Mentions only (default)**. If a run or interactive session is already live on a Slack thread, new replies continue that live work instead of starting another workflow. | Surface | Event type | What it matches | | -------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `@overcut ` mention | `mention` | A workflow whose trigger event type is **mention** and whose channel filters match this channel. Use this for conversational requests. | | `/overcut [args]` slash command | `slash_command` | Slack apps register only their own slash command, so the bot prefix is always `/overcut`. The next token (``) is matched against the **Slash Command** field on a workflow's Manual trigger. See the [Slash Command Guide](/docs/workflows/trigger-with-slash-command). | | Top-level channel message (Watch all messages mode only) | `channel_message` | A workflow with a `channel_message` trigger on this channel. Use trigger conditions to filter by actor, message content, or channel. | | Thread reply (Watch all messages mode only) | `thread_reply` | A workflow with **Trigger Event** set to **thread reply** can match a reply in a registered channel when no run or interactive session is live on that thread. Replies from people and other services can match this event, so filter busy channels by actor, message content, and channel. Overcut's own messages are ignored. Replies to a live run continue that run instead of starting a duplicate workflow. | A plain `@overcut` mention and `/overcut ` are **different trigger types**. A mention-trigger workflow won't fire on a slash command, and a slash-command workflow won't fire on a plain mention. An `@overcut` mention inside a thread is also a `mention` event, not a `thread_reply` event. Configure each surface with the matching trigger event type. See [Triggers](/docs/workflows/triggers) for the full trigger model and [Trigger with Slash Command](/docs/workflows/trigger-with-slash-command) for a step-by-step slash command setup. Use `/overcut` when you want an explicit command in a busy channel. Use `@overcut` when the request fits naturally into an ongoing discussion. ## What agents can do in a Slack channel You can give agents Slack messaging capabilities in **Agent Roles**. During Slack message-triggered, scheduled, manual, and Git-triggered runs, these agents can use any active Slack channel registered to the current project. | Action | What the agent can do | | -------------------- | -------------------------------------------------------------------------------------------------- | | **Post message** | Post at a registered channel's root or in a thread to share updates, answers, or workflow results. | | **Read messages** | Read recent channel messages to understand the discussion before responding. | | **Edit message** | Update a message the agent posted earlier to keep responses accurate. | | **Manage reactions** | Add or remove emoji reactions on messages in the channel. | A Slack workspace connection alone does not make its channels available to an agent. The channel must have an active registration for the current project in **Project Settings → Project Channels**. Inactive registrations and channels registered only to another project are unavailable. See [Chat Channels in the Agent Tools Reference](/docs/reference/tools#chat-channels) for the messaging tools you can assign. ### Choose a destination | Run context | Default destination | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Slack message-triggered run | The channel that triggered the run. The agent can also post to any other active channel registered to the project. | | Scheduled, manual, or Git-triggered run, one registered channel | That channel is used automatically. | | Scheduled, manual, or Git-triggered run, multiple registered channels | The agent must pick one of the registered channels. | To steer the agent, name the channel in your workflow or agent instructions, for example "post the summary to #eng-updates". ### Choose a thread When the agent posts without naming a thread: * In the channel that triggered the run, the message continues the triggering thread. * In any other channel, the message posts at the channel root. The triggering thread is never reused across channels. The agent can also reply in a specific thread by naming it. ## Interactive sessions in Slack The same [comment routing rules](/docs/reference/interactive-sessions#comment-routing-rules) that apply to PR and issue threads apply to Slack threads in registered channels. While a run or interactive session is live for a thread, new replies in that thread route to the live work instead of starting a new workflow. When no run or session is live on the thread, eligible replies in **Watch all messages** channels can be evaluated by workflows with **Trigger Event** set to **thread reply**. Use `/done` to end the session gracefully, or `/quit` to terminate the workflow. ## Related * [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces): how workspace integrations and project settings fit together. * [Triggers](/docs/workflows/triggers): the full trigger model. * [Trigger with Slash Command](/docs/workflows/trigger-with-slash-command): step-by-step slash command setup. * [Agent Tools Reference](/docs/reference/tools): the Slack messaging actions you can give an agent. * [Interactive Sessions](/docs/reference/interactive-sessions): how routing into active sessions works. # Slack from self-hosted Overcut Source: https://docs.overcut.ai/docs/integrations/slack/self-hosted Connect Slack to a self-hosted Overcut deployment by creating your own Slack app. Use this path when you run **Overcut on your own infrastructure**. A Slack app has a single, fixed set of URLs - its OAuth redirect, event delivery, and slash-command endpoints are registered on the app itself - and the managed Overcut Cloud Slack app points at Overcut Cloud. Your deployment therefore uses a Slack app that **you create and own**, pointing at your own domain. All tokens and events stay between your Slack workspace and your deployment; nothing goes through Overcut Cloud. On **Overcut Cloud**, use the managed Overcut Slack app instead - see [Connect to Slack](/docs/integrations/slack). No app creation or environment configuration is needed there. ## Prerequisites * Permission to **create apps** in your Slack workspace (and, if your workspace requires it, admin approval to install them) * A running self-hosted Overcut deployment with a public HTTPS domain (`https://`) and a **browser-trusted TLS certificate** * **Inbound reachability from Slack**: Slack's servers must be able to reach `https:///hooks/...` over port 443 * The ability to set environment variables on the deployment and restart it Slack verifies your event endpoint with a live HTTPS request and delivers all events from Slack's cloud. A deployment behind a firewall that blocks inbound internet traffic, or one serving a self-signed certificate, **cannot complete Slack setup**. This is a Slack platform requirement, not an Overcut limitation. ## How it works Your Slack app is the identity Overcut uses in Slack: 1. **OAuth connection** - connecting a Slack workspace in Overcut runs the OAuth flow against *your* app; the granted bot token is stored by your deployment and used to read and post messages. 2. **Events and commands** - Slack delivers channel messages, mentions, and slash commands to your deployment, signed with your app's **signing secret**, which Overcut verifies on every request. ## Step 1: Create the Slack app Go to [api.slack.com/apps](https://api.slack.com/apps), click **Create New App -> From a manifest**, pick the Slack workspace, and paste the manifest below - replacing `` (three occurrences) with your deployment's domain: ```yaml theme={"dark"} display_information: name: Overcut description: Run Overcut workflows from Slack via mentions and slash commands. background_color: "#191919" features: bot_user: display_name: Overcut always_online: true slash_commands: - command: /overcut url: https:///hooks/slack/slash-command description: Trigger an Overcut workflow. usage_hint: " [args]" should_escape: false oauth_config: redirect_urls: - https:///slack-auth-app/callback scopes: bot: - commands - app_mentions:read - channels:read - groups:read - channels:join - channels:history - groups:history - team:read - chat:write - reactions:write settings: event_subscriptions: request_url: https:///hooks/slack/events bot_events: - app_mention - message.channels - message.groups org_deploy_enabled: false socket_mode_enabled: false token_rotation_enabled: false ``` Review the summary and click **Create**. Slack may warn that the event request URL is not yet verified - that is expected; you verify it in Step 2 after the deployment knows the signing secret. On the app's **Basic Information** page, under **App Credentials**, collect: * **App ID** * **Client ID** * **Client Secret** * **Signing Secret** ## Step 2: Configure the deployment Set these environment variables on your deployment: | Variable | Value | | --------------------------- | ------------------------------------------------------- | | `SLACK_INTEGRATION_ENABLED` | `true` | | `SLACK_APP_ID` | The **App ID** | | `SLACK_CLIENT_ID` | The **Client ID** | | `SLACK_CLIENT_SECRET` | The **Client Secret** | | `SLACK_SIGNING_SECRET` | The **Signing Secret** | | `SLACK_REDIRECT_URI` | `https:///slack-auth-app/callback` | The redirect URI must be **byte-identical** to the redirect URL registered on the Slack app (Step 1), otherwise the OAuth step fails with a `redirect_uri` mismatch. ### Apply the configuration Restart the deployment so the new environment variables take effect. ### Verify the event endpoint Back in the Slack app settings, open **Event Subscriptions**. If the request URL shows as unverified, click **Retry**. Slack sends a challenge to `https:///hooks/slack/events`; with the deployment running and the signing secret configured, it turns **Verified**. ## Step 3: Connect in Overcut From the workspace sidebar (no project selected), go to **Integrations**. In the providers list, find **Slack** and click connect. You are redirected to Slack to authorize **your** app for the Slack workspace. Approve the requested scopes. After approval you return to Overcut and the Slack workspace appears in the connected providers list. From here, setup continues exactly as on Overcut Cloud - register channels in a project, choose routing modes, and trigger workflows: see [Connect to Slack](/docs/integrations/slack#register-channels-in-a-project). ## Troubleshooting * **Slack tile missing or disabled in Overcut**: `SLACK_INTEGRATION_ENABLED` is not `true`, or the deployment was not restarted after setting it. * **Event request URL verification fails**: Slack cannot reach `https:///hooks/slack/events` (check DNS, that port 443 is open to the internet, and that the TLS certificate is browser-trusted - a self-signed certificate fails here), or `SLACK_SIGNING_SECRET` is not set on the deployment. * **OAuth step fails with `redirect_uri` mismatch**: `SLACK_REDIRECT_URI` does not exactly match a redirect URL registered on the Slack app. * **Events deliver but signature validation fails (401 in the deployment logs)**: the app's **Signing Secret** and the deployed `SLACK_SIGNING_SECRET` do not match - re-copy it from **Basic Information** and re-apply. * **`/overcut` slash command returns an error in Slack**: the slash-command URL on the app does not point at `https:///hooks/slack/slash-command`, or the deployment is unreachable from Slack. * **Messages in a channel do not trigger anything**: the bot is not in the channel, or the channel is not registered in the project - see [Register channels in a project](/docs/integrations/slack#register-channels-in-a-project). For what you can do once connected (channels, routing modes, triggering workflows, interactive sessions), see the [Slack overview](/docs/integrations/slack). # Network Allowlisting Source: https://docs.overcut.ai/docs/network-allowlisting Allow inbound connections from Overcut Cloud through your firewall or VPN using the published egress IP range. Overcut Cloud makes outbound connections from a fixed range of public IP addresses. If a system Overcut connects to sits behind a corporate firewall, a VPN, or an IP allowlist, this is the range to permit: ``` 20.125.192.184/29 ``` Allowlist the entire range, never a single address. Overcut selects a source address per connection, so two consecutive requests to the same endpoint can arrive from different IP addresses in the range. A rule built around one observed address fails intermittently and unpredictably. ## Scope | | | | ------------ | --------------------------------------------------- | | Egress range | `20.125.192.184/29` | | Addresses | `20.125.192.184` through `20.125.192.191` (8 total) | | Applies to | Overcut Cloud (SaaS) only | | Direction | Outbound only, connections that Overcut initiates | The range covers connections Overcut Cloud opens towards your systems. It does not apply to traffic your systems send to Overcut, which reaches Overcut over the public internet from your own addresses. **Self-hosted Overcut deployments are out of scope.** A deployment you run on your own infrastructure connects to your systems from your own network, using addresses your network team controls. This range is not involved, and allowlisting it does nothing for a self-hosted setup. ## Configure the rule Add `20.125.192.184/29` as an allowed source on the firewall, security group, VPN policy, or application-level IP allowlist that guards the systems Overcut needs to reach. If your firewall does not accept CIDR notation, enter the range as `20.125.192.184-20.125.192.191`, or enumerate all eight addresses. Any form is fine as long as the full range is covered. ### All eight addresses are in use This includes the first and last address in the range. Firewall administrators often exclude the first and last address of a block out of habit, treating them as network and broadcast addresses. That does not apply here: this is a routed allocation, not a subnet, and both `20.125.192.184` and `20.125.192.191` carry live traffic. Excluding either one produces failures that look random. ## Security considerations The egress range is shared across all Overcut Cloud customers. Allowlisting it permits traffic from Overcut's infrastructure generally, not from your workspace specifically. An IP allowlist is a network control, not an authentication control. Keep these in place alongside the allowlist: * **Application-level authentication.** Continue to require credentials, tokens, or mutual TLS on the systems you open up. Never treat a connection from this range as authenticated. * **A narrow rule.** Scope the allowlist to the specific destination hosts and ports Overcut needs, rather than opening the range to your network broadly. * **The controls you already run.** Rate limiting, logging, and monitoring on the exposed endpoints stay as relevant as they were before. For how Overcut protects data in transit and at rest, see [Privacy & Security](/docs/privacy-and-security). ## If the range changes Overcut gives customers advance notice before the egress range changes. This page is the source of truth: read the range here when you build or audit a rule, rather than caching the value in a runbook where it can go stale. ## Related * [Privacy & Security](/docs/privacy-and-security) * [Connect to GitLab](/docs/integrations/gitlab) for a self-hosted GitLab instance that Overcut Cloud reaches over the public internet * [MCP Servers](/docs/reference/mcp-servers) for remote MCP servers you host # Approvals and Discussions Source: https://docs.overcut.ai/docs/orchestrations/approvals-and-discussions Approve, reject, or talk through pending orchestration decisions, and stop an instance when needed. When an orchestration instance needs a person, it pauses with status **Waiting on human**. This page covers how you respond: approving or rejecting a proposal, opening a discussion with an agent, and cancelling an instance. An instance waits for a human when a proposal targets a gated workflow or gated completion, when confidence is too low to auto-approve, when a limit was hit, or when the instance stalled with no proposal on the table. ## Approve or reject by replying There are no approve or reject buttons. When a decision needs you, Overcut posts a comment on the tracked item (the issue or pull request being worked), for example: > **Bug Resolver** needs a decision on this issue. > > Proposed next step: **Implement & PR** (confidence 85%). > > Reply to approve, reject, or suggest a different next step. Reply in your own words on that comment thread. "Approve", "go ahead", "no, run the review workflow first", or a clarifying instruction all work. The supervisor reads the reply, resolves the decision on your behalf, and the instance continues. Your login is recorded on the resolution, so the trail shows who consented. For completion proposals the comment reads "Proposed: **complete the orchestration**", and a reply approves or objects. When no next step is proposed, the comment asks how to proceed, and your reply becomes the direction. Gates always require this explicit consent. High confidence never passes a gate, and the routing AI cannot approve through one on its own. ## Discussion sessions Sometimes you need context before you can decide. A discussion session is a live chat with a discussion agent, scoped to the pending decision. It is available on gates where **Enable chat on this gate** is configured (see [Discussion agent](/docs/orchestrations/builder#discussion-agent)). A discussion starts in either of two ways: * You reply on the tracked item with a question rather than a decision, and the gate opens a chat. * You select **Start a discussion** in the **Discussion** panel on the instance page. The chat happens on a dedicated page (reachable from the **Discussion** panel via **Open the chat**) or directly on the tracked item's comment thread; both sides of the conversation land in the same transcript. In the chat page, Enter sends and Shift+Enter adds a newline, and a hint shows how long the session has before it expires. A discussion ends when: * The discussion agent reaches an outcome and reports it. * You select **End discussion**. The conversation so far is handed to the supervisor, which resolves the decision from it. * **Max chat duration (minutes)** expires. * The decision is resolved another way, or the instance ends. The discussion informs the decision, but it does not replace it: the supervisor keeps final authority and resumes the normal flow from the discussion's outcome. Past discussions stay linked from the decision's **Discussion** row on the instance trail. ## Cancel an instance Users with the cancel permission can stop a live instance from its detail page. **Cancel instance** appears while the status is **Queued**, **Active**, **Deciding**, or **Waiting on human**. Cancelling stops the orchestration immediately, including the workflow execution currently in flight. This cannot be undone. From any monitoring view, select **View Details** on the instance. In the **Cancel this instance?** dialog, optionally record a note in **Reason (optional)**. Select **Cancel instance** to confirm, or **Keep running** to close the dialog. Cancellation is recorded as a human decision on the trail, and Overcut posts a comment on the tracked item noting that the orchestration was cancelled. The status chip updates within a few seconds. ## Related * [Monitoring Instances](/docs/orchestrations/monitoring): find instances that are waiting on a person. * [Orchestration Builder](/docs/orchestrations/builder#gates): configure gates and discussion agents. # Orchestration Builder Source: https://docs.overcut.ai/docs/orchestrations/builder Configure an orchestration's goal, allowed workflows, entry triggers, gates, limits, and publishing from one canvas. The Builder is where you define everything about an orchestration. Open a project, go to **Build** > **Orchestrations**, and select an orchestration (or the pencil icon) to open its **Builder** tab. The Builder shows a canvas of nodes (goal, triggers, allowed workflows, gates) with a properties panel on the right. Selecting a node opens its settings in the panel; selecting nothing shows the orchestration-level settings. Edits save automatically to the draft as you type. Nothing affects live behavior until you publish. ## General settings With nothing selected, the panel shows: * **Orchestration name** (required). * **Color**: used for the orchestration's dot in lists and monitoring views. * **Default LLM Model**: the model used for routing decisions. * **Context Parameters**: values this orchestration sets for `{{params.}}` in every workflow it runs. They win over each workflow's own value, and they save immediately, independent of the draft. For example, set `branch_suffix` here so two orchestrations can run the same workflows with different branch names. See [Context Parameters](/docs/reference/context-parameters). ## Goal and instructions Select the **Goal & Instructions** node. * **Goal**: the outcome contract for one tracked item. Make "done" unambiguous, for example "Every production bug reported as an issue is investigated, root-caused, fixed behind a PR, and verified." The goal must be at least 20 characters. * **Orchestration instructions**: optional routing guidance, for example "Start with triage. If it is a bug, run RCA first; go straight to Implement & PR when the issue names the fix." Only the routing AI reads these. The workflows themselves run exactly as authored; the goal and instructions never change their steps. ## Allowed workflows Select the **Allowed Workflows** node and use the **Allowed Workflows** multi-select. This is the closed set of workflows instances may route between; the AI can only propose workflows from this list. If an allowed workflow is later deleted from the project, its badge is flagged on the canvas and publishing is blocked until you remove or replace it. When you install an orchestration template from the [Workspace Library](/docs/reference/workspace-library#install-an-orchestration-template), each workflow the template references is mapped to a workflow in this project, or installed as a copy, before the orchestration is created. The installed orchestration is a draft owned by this project; publish and activate it as usual. ## Triggers Each entry trigger defines one way an instance opens. At least one trigger is required. * **Entry event**: the event that opens an instance, or **slash command**. The selector lists the event types currently supported as orchestration entries. * For event-based entries, a condition builder filters which events match, using the same conditions as workflow triggers. * For slash commands: * **Slash command**: the comment command that opens an instance (for example `investigate`), without the leading slash. Saved lowercase. * **Require @overcut mention before command**: when on, the comment must mention `@overcut` before the command. * **Starts with workflow**: the workflow that runs when this trigger matches. It must be one of the allowed workflows. Entry is deterministic; no AI decision happens at this point. If a slash command is also used by a workflow trigger in the same project, the orchestration entry takes precedence. Publishing warns about collisions but does not block them. ## Gates A gate is a human consent checkpoint. Add one with **Add Gate** on the canvas. * **Gate name** (required): a kebab-case slug, unique within the orchestration, for example `approve-pr`. * **Description**: what is being consented to. * **Gate point**: choose one. * **Before workflow**: the instance pauses for approval before starting any of the selected **Gated workflows**. * **Before completion**: the instance pauses for approval before it is marked complete. Only one completion gate is allowed. Gated proposals always wait for a person. High confidence never passes a gate, and the routing AI cannot approve through one. How approval works is covered in [Approvals and Discussions](/docs/orchestrations/approvals-and-discussions). ### Discussion agent Each gate can open a chat when a human reply reads as a question rather than a decision. * **Enable chat on this gate**: allows the pending decision to open a discussion session. * **Discussion workflow**: **Built-in workflow** answers from the decision context, the case file, and the tracked item. Choose **Custom workflow** when the discussion needs your own agent, tools, or repository setup. A custom discussion workflow can be any project workflow, but it must contain exactly one agent session step as its last step. * **Allow access to the previous agent session**: grants the discussion agent read-only access to the last workflow session. Enable it only when that context is appropriate for the people in the discussion. * **Max chat duration (minutes)**: how long a discussion session can stay open. Minimum 5, default 60. ## Limits Limits are deterministic guardrails, enforced by the platform rather than the AI. Blank fields use the defaults. | Limit | Default | Maximum | What it bounds | | ---------------------------- | ------- | ------- | ------------------------------------------------------------------------------------ | | **Max steps** | 20 | 100 | Workflow runs one instance may take | | **Max repeats per workflow** | 3 | 20 | How often one workflow may run within an instance | | **Max active instances** | 25 | 500 | Instances of this orchestration running at once; excess instances wait as **Queued** | | **Idle timeout (hours)** | 24 | 336 | How long an instance may sit idle before it is escalated to a person | When a route would exceed **Max steps** or **Max repeats per workflow**, the proposal is rejected, the violation is recorded on the instance trail, and the instance waits for a human. Nothing is dropped silently. ## Publish, discard, and activate The top bar shows actions when the draft differs from the published version: * **Publish** opens the **Publish Changes** dialog. Write a **Publish Message** (required; Overcut suggests one) and confirm. New instances start from the new version; running instances stay pinned to the version that opened them. If the draft has problems, Publish highlights the sections to fix instead of publishing. * **Compare** opens the draft against the last published version in **History**. * **Discard** resets the draft to the last published version. For a never-published orchestration, it deletes the draft entirely. The activation toggle turns the orchestration on or off and appears after the first publish. Inactive orchestrations ignore their entry triggers. **Delete** removes the orchestration. ## Version history The **History** tab lists every published version, newest first, with the draft tagged **unpublished** and the current version tagged **latest**. Select a version to view its definition, use **Compare with** to diff against the draft, the latest, or the previous version, and use **Restore** to copy an old version into the current draft. Restoring overwrites uncommitted draft changes. ## Related * [Your First Orchestration](/docs/orchestrations/first-orchestration): end-to-end setup walkthrough. * [Approvals and Discussions](/docs/orchestrations/approvals-and-discussions): how gated decisions get resolved. * [Monitoring Instances](/docs/orchestrations/monitoring): follow instances after they open. * [Context Parameters](/docs/reference/context-parameters): how orchestration-level values resolve. * [Workspace Library](/docs/reference/workspace-library): orchestration templates and installation. # Your First Orchestration Source: https://docs.overcut.ai/docs/orchestrations/first-orchestration Create an orchestration, publish it, and open your first instance with a slash command. This guide walks through building a minimal orchestration: one goal, two allowed workflows, and a slash command that opens an instance on demand. It takes about ten minutes. You don't have to build everything by hand. Open **Assistant** in the sidebar and ask it to draft the workflows or the orchestration for you, or to guide you through any step in this guide. ## Before you start You need at least one published workflow in the project. An orchestration routes between existing workflows; it does not replace them. If you have none yet, start with [Workflows](/docs/workflows/workflows). If your workspace already maintains an orchestration template in the [Workspace Library](/docs/reference/workspace-library), you can skip the build and select **Install from Library** on the **Orchestrations** page instead. ## Create and configure Open your project and go to **Build** > **Orchestrations**, then select **New Orchestration**. Overcut creates a draft and opens the Builder. The draft stays private until you publish it. With nothing selected on the canvas, the right panel shows the orchestration settings. Set the **Orchestration name**. Then select the **Goal & Instructions** node and write the **Goal**: the outcome that means the item is done, for example "Every production bug reported as an issue is investigated, root-caused, fixed behind a PR, and verified." The goal must be at least 20 characters. Select the **Allowed Workflows** node and pick the workflows instances may route between. Start small: a triage workflow and an implementation workflow are enough. The AI can only propose workflows from this list. In the **Triggers** container, select **Add Trigger**. For **Entry event**, choose **slash command** and enter a command such as `investigate` (without the leading slash; it is saved lowercase). Then set **Starts with workflow** to the workflow that should always run first. The first workflow is deterministic: no AI decision happens at entry. Select **Add Gate** to require human approval before a sensitive workflow runs, or before the instance is marked complete. You can skip this for a first test and add gates later. See [Orchestration Builder](/docs/orchestrations/builder#gates) for gate options. Select **Publish** in the top bar. If anything is invalid, the Builder highlights the sections to fix. In the **Publish Changes** dialog, write a short **Publish Message** and confirm. New instances start from this published version. After the first publish, use the activation toggle in the top bar to turn the orchestration on. Inactive orchestrations ignore their triggers. ## Run it Comment `/investigate` (your slash command) on an issue or pull request in a connected repository. The trigger opens an instance and starts the first workflow. Follow the run in the orchestration's **Activity** tab: the instance appears in the live funnel, and **View Details** opens its decision trail. See [Monitoring Instances](/docs/orchestrations/monitoring). If the same slash command is also used by a workflow, the orchestration entry takes precedence. The publish dialog warns you about collisions. ## Where to go next * Configure gates, limits, and discussion agents in the [Orchestration Builder](/docs/orchestrations/builder). * Learn how to approve or reject pending decisions in [Approvals and Discussions](/docs/orchestrations/approvals-and-discussions). # Monitoring Instances Source: https://docs.overcut.ai/docs/orchestrations/monitoring Follow live orchestration activity, inspect an instance's decision trail and case file, and review history in Logs. Once an orchestration is live, you monitor it from three surfaces: the orchestration's **Dashboard** and **Activity** tabs for one orchestration, and **Monitor** > **Logs** for history across the project. Instance detail pages show the full decision trail for a single item. ## Instance statuses These statuses appear across all monitoring views: | Status | Meaning | | -------------------- | ---------------------------------------------------------------------------- | | **Queued** | Waiting to start, or held back by the **Max active instances** limit | | **Active** | A workflow run is executing | | **Deciding** | Overcut is evaluating what should happen next | | **Waiting on human** | A person needs to approve, answer, or unblock the instance | | **Completed** | The goal was reached; terminal | | **Cancelled** | Stopped before completion | | **Failed** | Work could not continue, for example a limit was reached with no way forward | Hover a status chip to see the reason when one is recorded. ## Dashboard Open an orchestration and select **Dashboard** for its health at a glance. The view auto-refreshes and follows the selected date range. * **Total Instances**, **Success Rate**, **Avg Duration**, and **Currently Active** cards summarize the period. Most cards link to the matching filtered instance list. * **Instances Per Day** charts volume over time, next to a per-status breakdown. * **Recent Instances** lists the newest instances, with **View all instances** opening the full list in **Logs**. ## Activity Select **Activity** for the live view of one orchestration. A funnel strip shows where every live instance is right now: * **Queued**: instances waiting to begin. * One box per allowed workflow, counting the instances currently in that workflow. * **Other workflows**: instances whose current workflow is no longer in the allowed set. * **Done**: recent terminal instances from the last day. A badge on a funnel box means instances there are waiting on a person. Select one or more boxes to filter the live table underneath; clear them to see everything. The table updates while work progresses and links each row to its instance detail page. ## Logs Open **Monitor** > **Logs** and switch to the **Orchestrations** tab for the historical **Orchestration Instances** list across the project. Filter by **Orchestration**, **Status**, and queued time range (**Last 24 hours**, **Last 7 days**, **Last 30 days**, or **All time**), and use **View Details** to open an instance. The **Workflows** tab shows workflow runs, including the runs that orchestrations started. An **Orchestration** column links each orchestration-driven run back to its instance, and the run-type filter can hide orchestration-driven runs or include system runs. ## Instance details The instance detail page is where you see why an orchestration moved the way it did. The summary bar shows the status, the **Orchestration**, the **Trigger** item (linked to its source), **Queued** and **Last activity** times, **Steps** against the configured maximum, and the pinned **Version**. ### The trail The trail alternates between decision entries and step entries, newest last. Density controls switch between **Headlines only**, an overview with every entry open, and full detail. Step entries show what a workflow run produced: * **Summary**: the reported result, with a verdict (**Achieved**, **Partially achieved**, **Blocked**, or **Not applicable**) and a confidence percentage. * **Proposed next**: the route or completion the run proposed. * **Artifacts** and **Links**: outputs and references added during the work, including a link to the workflow run itself. Decision entries show how the next move was chosen: * **Proposal**: the proposed route or completion, who proposed it, the confidence, and the rationale. * **Resolution**: the outcome and who resolved it. Human approvals show the approver, so consent is auditable. * **Proposal history**: earlier proposals and whether they were superseded, rejected, or resolved. * **Discussion**: a link to the discussion session, when one was held. ### Case file and links The side panel holds the **Case file**, the running context that accumulates one summary entry per step, and **Links**, which collects related runs, instances, and external references as work progresses. Together with the trail, they let you follow the whole engagement without opening each workflow run. ## Related * [Approvals and Discussions](/docs/orchestrations/approvals-and-discussions): act on instances that are waiting on a person. * [Workflow Execution Control](/docs/workflows/workflow-execution-control): how the underlying workflow runs are queued and controlled. # Orchestrations Source: https://docs.overcut.ai/docs/orchestrations/overview Coordinate a work item across a closed set of approved workflows until it reaches a defined goal. An **orchestration** is a goal-driven layer above individual workflows. It watches for a matching event or slash command, opens an **instance** for that work item (an issue or pull request, for example), and routes the item through approved workflows until the goal is met. Use an orchestration when one workflow run is not enough to finish the work. A production bug may need triage, root-cause analysis, a fix behind a PR, and a review. An orchestration keeps that one item moving through the right workflows while preserving a single timeline, a shared case file, and human approval points. Create, publish, and run an orchestration end to end. Configure the goal, allowed workflows, triggers, gates, and limits. Approve, reject, or discuss pending decisions as a human in the loop. Follow live activity, inspect the decision trail, and review history. ## Why orchestrations exist A workflow is one automation path: a trigger, steps, and an outcome. Real work often changes shape as it moves from intake to completion, and no single path covers it. Orchestrations coordinate that longer-lived path with a controlled loop: 1. An entry trigger matches an item and opens an instance. 2. The instance starts a configured first workflow, with no AI decision at entry. 3. The workflow runs and reports its result back to the instance. 4. The orchestration decides what happens next: route to another allowed workflow, wait for a human, or complete. 5. The loop repeats until the goal is reached, the instance is cancelled, or a limit is hit. The goal you write is the contract. Overcut works the item toward it, pauses when a person must decide, and stops when the goal is met. ## Orchestrations vs workflows | Model | What it defines | What it produces | Best for | | ----------------- | ------------------------------------------------------------ | ----------------------------- | ----------------------------------------------------------------------------- | | **Workflow** | A trigger, steps, and the order they run in | One workflow run | A repeatable automation path, such as reviewing a PR or triaging a ticket | | **Orchestration** | A goal, allowed workflows, entry triggers, gates, and limits | One instance per tracked item | Coordinating a work item across multiple workflows until the goal is complete | A workflow is still the unit that does work. The orchestration decides which approved workflow runs next. Workflows run exactly as you authored them; the orchestration never changes their steps. An orchestration cannot reach every workflow in the project. Instances route only to workflows listed in **Allowed Workflows**, a closed set you select in the Builder. ## What an orchestration contains You configure everything in the [Builder](/docs/orchestrations/builder): * **Goal**: what "done" means for one tracked item. * **Orchestration instructions**: optional routing guidance between workflows. * **Allowed Workflows**: the closed set of workflows instances may route between. * **Triggers**: the events or slash commands that open an instance, each with a deterministic first workflow. * **Gates**: human consent checkpoints before specific workflows or before completion. * **Limits**: deterministic guardrails on steps, repeats, active instances, and idle time. ## How decisions are made Every step boundary opens a decision point with a proposal: route to a workflow, or complete the instance. Each proposal carries a confidence score and a rationale, both visible on the instance page. * Proposals with high confidence auto-approve when no gate covers the target. * Proposals behind a **gate** always wait for explicit human consent. The AI can never pass a gate on its own. * Low-confidence proposals, dead ends, and limit violations also escalate to a person. Humans respond by replying on the tracked item, or through a discussion session. See [Approvals and Discussions](/docs/orchestrations/approvals-and-discussions). Limits are enforced by the platform, not the model. When an instance hits **Max steps** or **Max repeats per workflow**, the violation is recorded on the trail and the instance waits for a human instead of continuing. ## Published versions and running instances Orchestrations use published versions. Draft changes in the Builder do not affect anything until you select **Publish**. Each instance is pinned to the version that opened it and follows that definition for its whole life. Publishing a new version changes behavior only for new instances, so in-progress work stays stable while you iterate. The instance page shows the pinned **Version**, and the **History** tab lists every published version. ## Templates and shared values An orchestration authored in the [Workspace Library](/docs/reference/workspace-library) is a template: it never runs, and projects install it as an independent copy. During install, each workflow the template names is mapped to an existing workflow in the project or to a copy installed from the Library. Nothing stays linked to the Library. An orchestration can also set [context parameter](/docs/reference/context-parameters) values that every workflow it runs receives, so two orchestrations can run the same workflows with a different branch suffix or marker comment. ## Billing An orchestration instance bills as one workflow execution, regardless of how many routing decisions it takes. The workflow runs it starts bill as usual. Orchestrations availability depends on your plan. If **Orchestrations** does not appear under **Build** in the project sidebar, contact your account team. ## Related * [Workflows](/docs/workflows/workflows): the automation unit orchestrations route through. * [Workspace Library](/docs/reference/workspace-library): orchestration templates and how projects install them. * [Context Parameters](/docs/reference/context-parameters): orchestration-level values for the workflows it runs. * [Triggers](/docs/workflows/triggers): workflow trigger types and event context. * [Workflow Execution Control](/docs/workflows/workflow-execution-control): run queuing, priorities, and resource locking. # Privacy & Security Source: https://docs.overcut.ai/docs/privacy-and-security Understand how Overcut safeguards your intellectual property, enforces enterprise-grade security, and ensures compliance with global standards. At **Overcut**, your trust is our highest priority. We know your source code and ticketing data are among your most valuable assets, and our platform is designed from the ground up to protect them. This document outlines how Overcut safeguards your intellectual property, enforces enterprise-grade security, and ensures compliance with global standards. ## 1. Secure by Design Overcut was built with **privacy, security, and compliance** as core design principles - not afterthoughts. Every decision, from how we handle repository access to how agents execute tasks, is guided by three commitments: * **Minimal Exposure** – we access only what is strictly necessary, only when it’s needed. * **Complete Isolation** – every execution is sandboxed and torn down after use. * **Transparency & Auditability** – you remain in control with full visibility of every action. ## 2. Enterprise-Grade AI Integration Overcut gives enterprises flexibility in how they run AI - without compromising security. ### Option 1: Overcut-Managed Azure OpenAI (Default) * **No Training on Customer Data**: Your prompts, data, and code are never used to train foundation models. * **Regional Residency**: Data remains within your chosen Azure region. * **Enterprise-Ready Compliance**: Covered under Microsoft certifications (SOC 2 Type II, ISO 27001, GDPR, HIPAA, FedRAMP). * **Zero Data Retention**: Prompts and responses are not stored beyond immediate processing. * **Private Endpoints**: Encrypted connections directly between Overcut and Azure OpenAI. This is the **fastest path to secure AI adoption**, managed by Overcut. ### Option 2: Bring Your Own Key (Enterprise Plan) For organizations with stricter controls, Overcut supports **BYOK**: * **Use Your Own Azure OpenAI Tenant**: models run under your subscription, governed by your compliance policies. * **Full Control**: data never leaves your environment; Overcut connects securely via your keys and endpoints. * **Custom Models**: optionally connect to alternative LLM providers supported by your enterprise contracts. This option is ideal for customers with **dedicated compliance, residency, or vendor-management requirements**. ### Enforce residency with workspace defaults Administrators can set a workspace-wide default model that aligns workflows and agents to an approved model registry. Locking the workspace to a specific region or tenant helps every workflow and agent inherit the same residency guarantees unless a workflow owner explicitly selects another approved model. Configure this under **Account → Settings → Default LLM Model**, and reference the [Default Model Configuration quick start](/docs/quick-starts/default-model-configuration) for a full walkthrough. ## 3. Secure Code & Ticket Access Overcut follows a **just-in-time, least-privilege model** for handling your code and tickets. * **On-Demand Access** – repositories and tickets are fetched only when required for a specific task. * **Ephemeral Storage** – no persistent storage of your codebase or ticket data on Overcut infrastructure. * **Automatic Cleanup** – once the task is complete, all temporary data is securely deleted. * **Secure Caching** – when repositories are cached for performance optimization, the code is stored in enterprise-grade secured storage with encryption at rest and in transit. This ensures your intellectual property is never at risk of overexposure. ## 4. Controlled Access with Scoped Tokens Access to your systems is managed with **scoped, time-limited tokens**: * Tokens are **restricted to the task at hand, with the required repositories or projects**. * Only the permissions necessary for the task are granted. * Every token issuance, use, and expiration is **fully logged for audit**. This approach minimizes the attack surface and ensures compliance with least-privilege principles. ## 5. Isolated Execution Environments Each Overcut agent runs in a **dedicated, isolated environment** that is destroyed after use. * **Sandboxed by Default** – no cross-contamination between runs. * **No Shared State** – each execution starts clean and ends clean. * **Automatic Teardown** – containers, data, and network resources are deleted after completion. This guarantees that no customer data ever persists beyond the lifespan of a single task. ## 6. Organizational Control & Visibility You stay in control of how Overcut operates within your environment. * **Granular Permissions** – administrators can configure which tools each agent may use. * **Role-Based Access** – ensure the right people have the right level of control. * **Full Audit Trails**: every agent action, token use, and data access is recorded. Workspace administrators can use [Audit Trail](/docs/reference/audit-trail) to review workspace activity, filter events, and understand event details. * **Real-Time Monitoring** – track activity as it happens, with alerting and reporting. ## 7. Security Principles We Live By Our security model is anchored on globally recognized principles: 1. **Zero Trust** – no implicit trust; every request is authenticated and authorized. 2. **Least Privilege** – agents, tokens, and users get only what they need, nothing more. 3. **Defense in Depth** – multiple layers of security across network, application, and execution. 4. **Data Minimization** – only process what’s necessary, delete everything else. 5. **Transparency** – provide visibility through logs, reports, and clear governance. ## 8. Compliance & Certifications By building on Azure’s certified infrastructure and applying our own security controls, Overcut helps you meet enterprise compliance needs: * **SOC 2 Type II** * **ISO 27001** * **GDPR** * **HIPAA** (where applicable) * **FedRAMP** (via Azure) ## 9. Architecture Overview Below is a high-level view of how data flows securely through Overcut: ```mermaid theme={"dark"} flowchart LR subgraph Customer["Customer Organization"] REPO["Git Repositories (GitHub/GitLab/Bitbucket/Azure DevOps)"] TICKETS["Ticketing Systems (Jira/Azure DevOps/GitHub/GitLab)"] end subgraph Overcut["Overcut Platform"] SERVER["Overcut Orchestration
• Token Management
• Workflow Execution
• Audit Logging"] AGENT["Ephemeral Agent
• Isolated Sandbox
• Scoped Tools
• Auto-Cleanup"] end subgraph Azure["LLM Provider"] LLM["Enterprise LLM
• No Data Retention
• Private Endpoints
• SOC2/ISO27001 Compliant"] end REPO <--> SERVER TICKETS <--> SERVER SERVER -->|"Scoped, Time-Limited Tokens"| AGENT AGENT <-->|"Encrypted Requests/Responses"| LLM ``` ## 10. Your Next Steps To maximize security when adopting Overcut: 1. **Configure Repository Access** – Set up scoped tokens with minimum required permissions for each Git integration (GitHub, GitLab, Azure DevOps, Bitbucket). 2. **Customize Agent Tools** – Use repository-specific tool configurations to restrict which commands each agent can execute per repository. 3. **Choose Your AI Model** – Select between Overcut-managed Azure OpenAI (default) or bring your own key (BYOK) for enterprise compliance requirements. 4. **Enable Repository Caching Securely** – Configure caching settings per repository while ensuring cached code remains in enterprise-grade secured storage with encryption. 5. **Allowlist Overcut's Egress Range**: If Overcut Cloud needs to reach a system behind your firewall or VPN, permit its published egress IP range. See [Network Allowlisting](/docs/network-allowlisting). To discuss enterprise security requirements, certifications, or to request our detailed security package, contact [team@overcut.ai](mailto:team@overcut.ai). # Create & Edit Workflows Source: https://docs.overcut.ai/docs/quick-starts/create-workflows-from-playbooks Build workflows visually in the Workflow Builder or use the open-source playbook repo with your preferred AI coding agent to create and customize workflows. Overcut gives you two ways to create and edit workflows: 1. **Workflow Builder**: a visual, drag-and-drop editor inside Overcut where you build workflows step by step 2. **Playbook Repo + AI Agent**: clone the open-source [Overcut Playbooks](https://github.com/overcut-ai/overcut-playbooks) repo, open it in your preferred AI coding tool (Claude Code, Cursor, Codex, Gemini), and let the agent create or modify workflows for you Both approaches produce the same result: a `workflow.json` that you can import and run in Overcut. Build workflows visually: drag actions onto a canvas, configure triggers, assign agents, and publish directly from the UI. Clone the playbook repo, open it in your AI coding tool, and ask the agent to create or modify workflows with full context about Overcut's capabilities. *** ## Using the Workflow Builder The [Workflow Builder](/docs/how-to/workflow-builder) is a visual editor inside Overcut where you can: * Drag and drop actions (`agent.run`, `agent.session`, `git.clone`, etc.) onto a canvas * Configure triggers (PR opened, issue labeled, mention, slash command, scheduled) * Assign agents to each step and set timeouts * Edit step prompts inline * Publish, version, and manage workflows This is the best option when you want to build a workflow interactively, or make quick edits to an existing one. *** ## Using the Playbook Repo with AI For more complex workflows, or when you want to create and iterate faster, the [Overcut Playbooks](https://github.com/overcut-ai/overcut-playbooks) repository provides an **AI-powered workspace**. The repo ships with built-in skills and rules for popular AI coding tools, so your agent understands Overcut's workflow format, triggers, actions, template variables, and agent tools out of the box. ### Why use the playbook repo? Import any of the 15+ pre-built playbooks directly into Overcut. No need to build from scratch. Built-in skills teach your AI coding agent everything about Overcut workflows, so it can create or modify playbooks for you. Skills are shared across Claude Code, Cursor, Codex, Gemini, and more. Use whichever tool you prefer. Study real, production-tested workflows to understand patterns and build your own. *** ## Getting Started ```bash theme={"dark"} git clone https://github.com/overcut-ai/overcut-playbooks.git cd overcut-playbooks ``` Open the cloned repo in **Claude Code**, **Cursor**, **Codex**, **Gemini**, or any AI-enabled editor. The repo automatically loads the right skills and rules for each tool. Ask your AI agent to explore existing playbooks, modify them, or create entirely new workflows. For example: * *"Create a new playbook that runs security checks when a PR is opened"* * *"Modify the code-review playbook to add a linting step"* * *"Add a step to the create-pr-from-design playbook that notifies Slack when done"* The AI agent automatically picks up the repo's conventions: `workflow.json` format, step ID naming rules, prompt file structure, and all available trigger types, actions, and template variables. *** ## Built-in AI Skills The repo includes **6 deep-reference skills** that give your AI coding agent comprehensive knowledge about Overcut's workflow system. These are stored in `.agents/skills/` and automatically symlinked to each tool's config directory (`.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.gemini/skills/`). | Skill | What It Teaches the Agent | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Workflow Triggers** | All 22 event types (issue, PR, mention, scheduled, manual), condition operators, slash command setup, and cron scheduling | | **Step Actions** | The 6 action types (`agent.run`, `agent.session`, `git.clone`, `repo.identify`, `ci.executeWorkflow`, [`script.run`](/docs/workflows/run-script)) with full parameter schemas | | **Agent Session Design** | When to use `agent.session` vs `agent.run`, coordinator patterns, delegation templates, exit criteria, and interactive sessions | | **Agent Tools Reference** | All 35+ user-configurable tools across 8 categories, plus the 5 built-in agent types and their tool presets | | **Template Variables** | Handlebars `{{}}` syntax for referencing trigger context, step outputs, and using helpers like comparison and iteration | | **Prompt Engineering** | Structured output patterns, tool constraint tables, progress tracking, idempotency markers, and cross-workflow triggering | Each skill includes a main reference (`SKILL.md`) and detailed lookup tables in a `references/` folder, giving the agent everything it needs to produce valid, well-structured playbooks. The skills activate automatically based on context. When you ask the agent to create a trigger, it loads the workflow-triggers skill. When you ask about coordinating multiple agents, it loads the agent-session-design skill. *** ## Understanding Playbook Structure Every playbook follows a consistent structure that both humans and AI agents can work with: ``` playbook-name/ ├── workflow.json # The importable workflow definition ├── README.md # Documentation and usage guide ├── step-id-name.md # Prompt for a step (filename = step ID) ├── another-step-id.md # Each step gets its own prompt file └── special-agents/ # (Optional) Custom agent instructions └── agent-name.md ``` ### The Filename Convention The most important rule: **prompt filenames must exactly match the step IDs** in `workflow.json`. For example, if a step has `"id": "prep-context"`, the corresponding prompt file must be named `prep-context.md`. This convention enables a powerful workflow: 1. Edit the markdown prompt file in your editor 2. The change is immediately readable by your AI agent 3. Ask the agent to update `workflow.json` to match, or use the included `sync-prompts.py` script ```bash theme={"dark"} python3 scripts/sync-prompts.py create-pr-from-design ``` *** ## Import a Playbook into Overcut Navigate to the playbook folder in the repository and download the `workflow.json` file. In Overcut, go to the Workflow Builder and click **Import Workflow**. Select the downloaded `workflow.json` file to import the complete workflow structure. Every step that uses `agent.run` or `agent.session` references an agent ID. During import, you'll map each reference to one of your own configured agents. Choose the agent whose role and tools best match the step's purpose. For example, a step labeled "Backend Developer" should map to an agent with code editing tools, while a "Code Reviewer" step should map to an agent with pull request review tools. Review the imported workflow, adjust prompts or timeouts as needed, and publish it. For full details on the import/export process, see [Import & Export Workflows](/docs/workflows/workflow-import-export). *** ## Choosing the Right Agent for Each Step When mapping agents during import (or when building a new playbook), consider what each step needs: | Step Purpose | Recommended Agent Type | Key Tools Needed | | ------------------------------ | ---------------------- | ------------------------------------------- | | Code analysis / implementation | Senior Developer | File system, code utilities, git operations | | Code review | Code Reviewer | Pull request review, inline comments | | Documentation | Tech Writer | File system, ticket/issue tools | | Planning / requirements | Product Manager | Ticket tools, exploration | | Repository exploration | Explore Agent | Search, file reading | The model used for each step follows a cascade: **agent-specific setting → workflow default → workspace default → system default**. You can override the model at any level to balance cost and capability. *** ## Edit Existing Playbooks with AI The fastest way to customize a playbook is to ask your AI agent directly. ### Modify prompts Open the repo in your preferred tool and ask: ``` Update the planning step in create-pr-from-design to also consider performance implications for each phase. ``` The agent will edit `planning.md` and update the corresponding instruction in `workflow.json`, maintaining the filename-to-step-ID convention. ### Add or remove steps ``` Add a new step after "validate-implementation" that runs a security scan before finalizing the PR. ``` The agent will create a new prompt file, update `workflow.json` with the step definition and flow connections, and ensure the step ID matches the filename. ### Change triggers or conditions ``` Change this playbook's trigger from a slash command to automatically run when an issue is labeled "implement". ``` The agent knows all 22 trigger event types and their condition operators, so it can reconfigure the trigger correctly. *** ## Create a New Workflow from Scratch You don't have to start from an existing playbook. Ask your AI agent to build one from your requirements: ``` Create a new playbook called "auto-test-generation" that: 1. Triggers when a PR is opened 2. Clones the repo and checks out the PR branch 3. Analyzes which files changed 4. Generates unit tests for the changed code 5. Commits the tests and pushes to the PR branch 6. Posts a comment on the PR summarizing what was tested ``` The agent will: * Create the playbook folder with the correct naming convention * Write `workflow.json` with all steps, flow connections, and trigger configuration * Create individual prompt `.md` files for each agent step * Write a `README.md` with usage instructions Point the agent to similar existing playbooks as reference. For example: *"Use the create-pr-from-design playbook as a pattern: it has a similar multi-step structure with progress tracking."* *** ## Example: The Create PR from Design Playbook To see these concepts in action, look at the `create-pr-from-design` playbook, the most detailed workflow in the repo. It automatically creates implementation pull requests from approved design documents, triggered by the `/pr` slash command on an issue. ### The 8-step pipeline | Step | Action | What It Does | | --------------------- | --------------- | ---------------------------------------------------------------------- | | **Identify Repos** | `repo.identify` | Determines which repository the issue relates to | | **Clone Repo** | `git.clone` | Shallow-clones the identified repository | | **Prepare Context** | `agent.run` | Reads the issue, resolves dependencies, determines the base branch | | **Planning** | `agent.session` | Creates a phased implementation plan from the design document | | **Setup PR** | `agent.run` | Creates a branch and opens a draft pull request | | **Implement Changes** | `agent.session` | Implements each phase with individual commits and progress tracking | | **Validate** | `agent.session` | Writes tests, runs validation, fixes lint issues | | **Finalize PR** | `agent.run` | Updates PR description, removes draft status, posts completion summary | ### How steps connect Each step's output flows to the next via template variables: ``` {{outputs.identify-repos}} → Clone step knows which repo {{outputs.prep-context}} → Planning step knows the scope and base branch {{outputs.planning.message}} → Implementation step knows the phased plan {{outputs.setup-pr.message}} → Implementation step knows the branch and PR URL ``` ### Agent assignment This playbook uses two agent personas, **Backend Developer** and **Frontend Developer**, assigned to different steps based on the task: * Single-focus steps (prep context, setup PR, finalize) use `agent.run` with one agent * Complex steps (planning, implementation, validation) use `agent.session` with both agents coordinated by an automatic coordinator When you import this playbook, you'll map these to your own agents with the appropriate roles and tools. *** ## Sync Prompts Utility The repo includes a `sync-prompts.py` script that reads all `.md` prompt files in a playbook directory and updates the corresponding `instruction` fields in `workflow.json`: ```bash theme={"dark"} python3 scripts/sync-prompts.py ``` This is useful when you've edited prompt files manually (without AI) and want to sync the changes into the workflow definition. The script matches filenames to step IDs, handles JSON escaping, and reports any mismatches. *** ## Next Steps * **[Browse the Playbooks Repository](https://github.com/overcut-ai/overcut-playbooks)**: Explore all available workflows and their READMEs * **[Import & Export Workflows](/docs/workflows/workflow-import-export)**: Detailed guide for importing workflows into Overcut * **[Agent Differences](/docs/workflows/agent-differences)**: Understand when to use `agent.run` vs `agent.session` * **[Workflow Builder](/docs/how-to/workflow-builder)**: Learn the visual editor for fine-tuning imported workflows * **[Contributing Guide](https://github.com/overcut-ai/overcut-playbooks/blob/main/CONTRIBUTING.md)**: Share your playbooks with the community # Default Model Configuration Source: https://docs.overcut.ai/docs/quick-starts/default-model-configuration Plan, configure, and verify workspace, workflow, and coordinator default LLM selections with rollback guidance. Ensure every Overcut workflow runs on the right LLM without touching each agent individually. This guide walks workspace admins and workflow builders through: 1. Validating prerequisites and supported providers 2. Choosing a workspace-wide default model 3. Setting workflow-level defaults and coordinator overrides 4. Verifying the cascade through the UI and execution logs 5. Rolling back safely when governance needs change Use this guide alongside the [Workflow Execution Control](/docs/workflows/workflow-execution-control) and [Agent Session](/docs/workflows/agent-session) docs to understand how defaults are enforced during runtime. *** ## Prerequisites * **Workspace admin access** to edit **Account → Settings**. * **Published agents and workflows** that use the default model placeholder so they can inherit new defaults automatically. * An active custom **LLM Model** from Anthropic or AWS Bedrock if you run steps with the **Claude** engine. The model must belong to the current workspace and cannot be a system model. See [LLM Models](/docs/reference/llm-models#claude) for compatible configuration options. [Test the model](/docs/reference/llm-models#testing-a-model) before you assign it as a default so runs use its verified capabilities. *** ## Step 1: Choose workspace defaults Navigate to Account → Settings and locate the Default LLM Model and Default Claude Engine Model fields. Use Default LLM Model to select the main model for the workspace (e.g., gpt-4.1). If you use the Claude engine, select an active Anthropic or AWS Bedrock custom model in Default Claude Engine Model. This selection is separate from Default LLM Model and does not change the default used by the Overcut engine. Click Save Changes. To stop using a Claude-specific workspace default, clear the selection in Default Claude Engine Model and click Save Changes. Claude steps can then fall through to Default LLM Model, but only if that model is compatible with the Claude engine. Setting the workspace defaults means workflows that leave their metadata field empty or set to the default model placeholder inherit the applicable choice automatically. *** ## Claude engine model resolution The **Claude** engine checks these settings in order and uses the first model that is not set to the default model placeholder: 1. Coordinator override 2. Agent model 3. Workflow default 4. **Default Claude Engine Model** 5. **Default LLM Model** That first resolved model must be active, owned by the current workspace, non-system, and provided by Anthropic or AWS Bedrock. If it is not eligible, the Claude engine does not skip it and try a lower-priority setting. If no setting resolves to a model, the step fails because the Claude engine has no system-model fallback. This order applies only to the **Claude** engine. The **Overcut** engine uses its own cascade and can use a system model as its final fallback. See [Workspace Settings](/docs/reference/workspace-settings#model-resolution-order) for the canonical Claude resolution rules and [LLM Models](/docs/reference/llm-models#overcut-vs-claude) for engine compatibility. *** ## Step 2: Override specific workflows Some workflows (e.g., code review or red-team testing) may require a stronger or different model. In the workflow builder, click the canvas to open the Workflow Settings and find the Default LLM Model selector. Choose a model key (for example gpt-5.1-codex) and save the workflow. Click Save. When set, agents and coordinators left on the default model placeholder fall back to the workflow default. Workflows left on the default model placeholder continue to fall back to the workspace default. *** ## Step 3: Configure coordinator overrides Use coordinator overrides when a multi-agent session needs a faster planning model, but its child agents should continue using the workflow default. ```yaml theme={"dark"} steps: - id: "code-review-session" action: "agent.session" params: goal: "Complete review plan" agentIds: ["coordinator", "code-reviewer"] coordinatorModelKey: "azure-openai-gpt-5.1-codex" ``` Guidelines: * When not set, the coordinator will fall back to the workflow default, or the workspace default if the workflow default is not set. * Keep overrides scoped to steps that truly benefit from a different coordinator model. * Child agents never inherit the coordinator override; they evaluate their own `modelKey` → workflow default → workspace default chain. *** ## Step 4: Configure agent overrides Use agent overrides when an agent needs a different model than the workflow default. In the "Agent Roles" menu, select an agent to edit its settings. Choose a model key (for example gpt-5.1-codex) and save the agent. Guidelines: * When not set, the agent will fall back to the workflow default, or the workspace default if the workflow default is not set. *** ## Next steps * Review the [Building Blocks](/docs/building-blocks) guide to see how agents inherit models. * Learn how execution locks and priorities interact with these defaults in [Workflow Execution Control](/docs/workflows/workflow-execution-control). * Share compliance outcomes via the [Privacy & Security](/docs/privacy-and-security) guidance. # Quick Start Guides Source: https://docs.overcut.ai/docs/quick-starts/index Get started with Overcut's most popular automation workflows Welcome to Overcut's Quick Start guides! These step-by-step tutorials will help you set up powerful automation workflows for your development process. Each guide focuses on a specific use case that you can implement in minutes. If you want to start from a ready-to-use template, browse the Playbook Catalog to find and install a workflow that matches your goal. ## Available Guides Connect Overcut to your Git repositories and ticket systems: GitHub, GitLab, Azure DevOps, Bitbucket, Jira, and more. Register and activate the repositories Overcut should work with, and configure each one for agent runs. Use Anthropic's Claude Agent SDK as an alternative execution engine for your workflows. Browse the Playbook Catalog to find ready-to-use AI agent workflows, preview how each playbook works, and install the right template for your team. Install a template from the Playbook Catalog, then customize it in Workflow Builder or work more deeply with the open-source playbook repository and your preferred AI coding agent. Plan, configure, and verify workspace and workflow default LLM settings with coordinator overrides and rollback guidance. Give agents access to private package feeds like Azure DevOps NuGet using a Vault secret and a reusable skill. Define one context parameter, set a different value per repository, and verify the resolved value in the Playground and Run Context. ## Common Elements Each Quick Start guide will walk you through: 1. **Creating a Workflow** - Setting up a new workflow in Overcut 2. **Configuring Triggers** - Defining when your automation should run 3. **Adding Actions** - Setting up repository access and agent interactions 4. **Testing the Flow** - Verifying your automation works as expected # MCP Catalog Source: https://docs.overcut.ai/docs/quick-starts/mcp-catalog Browse and install pre-configured MCP servers from the open-source catalog with guided setup. Install MCP servers in your Overcut workspace with one click using the **MCP Catalog**: a curated, open-source collection of pre-configured server definitions. The catalog is designed for MCP-based connections, usually when you want to bring third-party systems into Overcut that do not have native workspace support. Each catalog entry includes the server configuration, required secrets, and a recommended tool set, so you can go from discovery to a working integration without writing JSON by hand. For first-class providers such as GitHub, GitLab, Azure DevOps, Jira, Linear, ClickUp, and Slack, most teams should start with native workspace integrations instead. Use the Integrations overview to choose the right connection path, and see the MCP Servers reference when you want to extend agents with external tools. The catalog is powered by the open-source repository at [overcut-ai/overcut-mcp-catalog](https://github.com/overcut-ai/overcut-mcp-catalog). You can browse entries, suggest new servers, or contribute directly. *** ## What is the MCP Catalog? The MCP Catalog is an in-app gallery of MCP server definitions. Overcut fetches the catalog from the [overcut-mcp-catalog](https://github.com/overcut-ai/overcut-mcp-catalog) GitHub repository and presents it as a searchable, filterable page inside your workspace. It is the standard way to add MCP-based access to external tools and unsupported systems, and it can also complement native integrations when your workflow needs extra tool coverage. MCP servers in the catalog are provided by third parties. Configurations, tool sets, and APIs may change as providers release new versions. Always review the server's documentation and verify its authenticity before installing. Overcut does not guarantee the behavior, availability, or security of third-party MCP servers. Each catalog entry defines: * **Server configuration**: the JSON config Overcut uses to connect (command + args or URL + headers) * **Required secrets**: credentials the server needs, with descriptions and help links * **Recommended tools**: a curated subset of tools suitable for most use cases * **All tools**: the full set of tools the server provides *** ## Browse the Catalog MCP Catalog in the Overcut workspace Navigate to MCP Servers in the sidebar and click Add MCP Server. This opens the catalog. Use the search field to find servers by name or description. Use category filters to narrow results by use case (e.g. monitoring, design, documentation). Each catalog card shows its status: Installed if the server already exists in your workspace, or Install if it hasn't been added yet. If a server is already installed, you can go directly to [assigning it to an agent](/docs/reference/mcp-servers#assigning-mcp-servers-to-agents). If not, click the card to start the guided install flow. *** ## Install from the Catalog Click a catalog card to open its install page. You'll see the server description, configuration preview, and setup inputs. For each required credential, enter a new secret value, or (if the same credential already exists in your Vault) it will be detected and attached automatically. Use the All Tools toggle to grant every tool, or leave it off to use per-tool checkboxes. Tools default to the catalog's recommended set. Toggle individual tools on or off as needed. The install page shows a read-only preview of the server's JSON configuration. Verify it looks correct before proceeding. Click Install MCP Server. Overcut creates the server and redirects you to its detail page so you can verify the setup immediately. Reuse existing Vault secrets whenever possible. This keeps credentials consistent across MCP servers and simplifies future rotation. *** ## Split a Server Across Agents You can install the same MCP server multiple times with different tool sets and assign each instance to different agents. This gives you fine-grained control over what each agent can do. **Common patterns:** * **Scoped access**: give a read-only Datadog instance to a triage agent (only log query tools) and a full-access instance to an incident responder (query + alert management tools) * **Project isolation**: install the same Sentry server twice with different API keys so two agents monitor different projects independently * **Least privilege**: limit each agent to only the tools it actually needs, reducing the risk of unintended actions Keeping the tool set small helps the agent stay focused. Too many tools can slow down execution and lead to less accurate results. When in doubt, start with the recommended tools and add more only as needed. *** ## Add a Custom Server If the server you need isn't in the catalog, click **Add Custom** in the top-right corner of the catalog page. This creates a blank MCP server entry and opens its detail page, where you can configure it manually. See the [MCP Servers reference](/docs/reference/mcp-servers#creating-a-custom-mcp-server) for the full manual setup flow. *** ## Contribute to the Catalog The catalog is open source at [overcut-ai/overcut-mcp-catalog](https://github.com/overcut-ai/overcut-mcp-catalog). Each server is defined as a directory containing a `catalog.json` file. ### Repository structure ``` overcut-mcp-catalog/ sentry/ catalog.json # Server definition icon.svg # Optional icon figma/ catalog.json icon.svg ... ``` ### Catalog entry schema Each `catalog.json` follows this structure: ```jsonc theme={"dark"} { "name": "Sentry", "description": "Search errors, investigate issues...", "category": "monitoring", "tags": ["errors", "debugging"], "iconUrl": "https://raw.githubusercontent.com/.../icon.svg", "websiteUrl": "https://github.com/getsentry/sentry-mcp", "priority": 10, "serverConfig": { "command": "npx", "args": ["-y", "@sentry/mcp-server@latest"], "env": { "SENTRY_ACCESS_TOKEN": "${SENTRY_ACCESS_TOKEN}" } }, "requiredSecrets": [ { "envVar": "SENTRY_ACCESS_TOKEN", "displayName": "Sentry Access Token", "description": "Create an Internal Integration token...", "helpUrl": "https://docs.sentry.io/..." } ], "recommendedTools": ["search_issues", "get_issue_details"], "allTools": ["search_issues", "get_issue_details", "create_issue", "..."] } ``` See the [CONTRIBUTING.md](https://github.com/overcut-ai/overcut-mcp-catalog/blob/main/CONTRIBUTING.md) for full guidelines on adding new entries. ### Create entries with AI The catalog repository ships with built-in rules for popular AI coding tools (Claude Code, Cursor, Codex, Gemini). Clone it and use your preferred agent to generate new catalog entries: ```bash theme={"dark"} git clone https://github.com/overcut-ai/overcut-mcp-catalog.git ``` Ask your AI agent to create a new entry. It understands the catalog schema, secret conventions, and tool discovery patterns automatically. *** ## Next Steps * **[MCP Servers Reference](/docs/reference/mcp-servers)**: Configuration reference, manual setup, allowed tools, and runtime behavior * **[Vault](/docs/reference/vault)**: Manage the secrets referenced by MCP server configurations * **[Agent Run Action](/docs/workflows/agent-run)**: Execute agents with MCP tools * **[Overcut Playbooks](/docs/quick-starts/playbooks)**: Pre-built workflows you can import and customize # Overcut Skills Source: https://docs.overcut.ai/docs/quick-starts/overcut-skills Official Overcut skills you add to your AI coding agent to manage your workspace and migrate existing automation frameworks into Overcut. New here? Start with [Connect Your Coding Agent](/docs/get-started/connect-your-coding-agent). One command signs you in and connects your agent to Overcut, with no skill install or manual token needed. Overcut also publishes official skills that connect an AI coding agent to Overcut. Install one, and your agent can manage your Overcut account in plain language or convert an existing automation framework into Overcut artifacts, without you writing GraphQL or learning a new format. The skills follow the open [Agent Skills spec](https://github.com/anthropics/skills), so any agent that supports `SKILL.md` can use them. They are published from the open-source [overcut-ai/overcut-skills](https://github.com/overcut-ai/overcut-skills) repository. This section is about skills your coding agent runs. For the in-product Skills feature (adding `SKILL.md`-based skills to your Overcut agents), see the [Skills reference](/docs/reference/skills). ## The skills Connect to the Overcut GraphQL API with a personal token to explore and manage your account: build workflows, agents, and orchestrations, monitor and analyze executions, and debug runs. Convert an existing agent or automation framework (Argo, LangGraph, CrewAI, n8n, GitHub Actions, and more) into Overcut-ready Skills, Agents, and Workflow definitions. The **Overcut API Skill** (`overcut-api`) gives your agent direct access to the GraphQL API. The **Convert to Overcut** skill (`convert-to-overcut`) is for migrations, and hands off to the API skill when you are ready to import the result into a live project. ## Install You add these skills the same way you add any skill to your agent. The exact steps and commands vary by agent, so check your agent's documentation. There are two common paths: If your agent supports plugin marketplaces, add the marketplace repository `overcut-ai/overcut-skills` and install the plugin you want: `overcut` for the API skill, `overcut-importer` for the converter. Otherwise, clone the [overcut-ai/overcut-skills](https://github.com/overcut-ai/overcut-skills) repository and copy the skill folder you want (under `plugins//skills/`, including its `references/`, `scripts/`, and `assets/`) into the directory your agent loads `SKILL.md` skills from. For example, in Claude Code: ```sh theme={"dark"} # 1. Add this marketplace /plugin marketplace add overcut-ai/overcut-skills # 2. Install a plugin /plugin install overcut@overcut-skills /plugin install overcut-importer@overcut-skills ``` Once installed, your agent uses the skill automatically when your request matches it. ## Next * [Overcut API Skill](/docs/quick-starts/overcut-skills/overcut-api): manage your account from your agent. * [Convert to Overcut](/docs/quick-starts/overcut-skills/convert-to-overcut): migrate an existing framework into Overcut. # Convert to Overcut Source: https://docs.overcut.ai/docs/quick-starts/overcut-skills/convert-to-overcut Add the convert-to-overcut skill to your AI coding agent to migrate an existing automation framework into Overcut Skills, Agents, and Workflows. The `convert-to-overcut` skill takes your existing agent or automation framework files and produces Overcut-native artifacts: Skills, Agent specs, and Workflow definitions that import cleanly into an Overcut project. It carries over your SDLC business logic and drops the source framework's orchestration plumbing. It is the companion to the [Overcut API Skill](/docs/quick-starts/overcut-skills/overcut-api): the converter writes the artifacts, and the API skill imports them into a live project when you are ready. ## What it converts The skill recognizes and maps several source frameworks, and falls back to reading intent directly for anything it does not recognize: * **Argo Workflows** and CronWorkflow * **kagents** * **LangGraph** * **CrewAI** * **AutoGen** * **n8n** * **GitHub Actions** * Any arbitrary skills or prompts folder The skill converts business logic, not infrastructure. It keeps what an agent should do, when it should run, in what order, and which capabilities it needs. It drops framework plumbing that Overcut handles for you, such as pod and resource specs, retries and timeouts, state machines, and memory backends. ## How it works This is a one-shot batch conversion. You point the skill at your source files, and it produces a reviewable output folder plus a `MANIFEST.md` that explains every decision. The skill scans your source directory, detects which framework or frameworks are present, and maps each construct to the Overcut artifact it will become (a Skill, an Agent, a Workflow step, a trigger, or dropped as plumbing). For each construct, it captures the intent in plain language: instructions, roles, quality bars, and step order, separated from the framework that expressed them. It writes one `SKILL.md` per skill, one agent spec per persona, and one workflow definition per pipeline. External tool calls (Slack, GitHub, Jira, and others) are mapped to Overcut built-in tools or MCP servers where possible. Anything it cannot map with confidence becomes a flagged TODO rather than a guess. It writes an `out/` folder and runs a validator that checks the JSON parses, every `SKILL.md` has valid frontmatter, agents carry the required fields, and workflow steps reference real step ids. The output stays importable even where it contains placeholders. You review the `MANIFEST.md`: the source-to-target mapping, everything dropped as plumbing, and every open TODO. Nothing is imported automatically. Required-but-missing fields become explicit placeholders and TODOs, never silent guesses. Review the `MANIFEST.md` and resolve TODOs (such as unmapped integrations and secrets to create) before you import. ## Add the skill You add this skill the same way you add any skill to your agent. The exact steps vary by agent, so check your agent's documentation. There are two common paths: If your agent supports plugin marketplaces, add the marketplace repository `overcut-ai/overcut-skills` and install the `overcut-importer` plugin. Otherwise, clone the [overcut-ai/overcut-skills](https://github.com/overcut-ai/overcut-skills) repository and copy the `convert-to-overcut` skill folder (at `plugins/overcut-importer/skills/convert-to-overcut/`, including its `references/`, `scripts/`, and `assets/`) into the directory your agent loads `SKILL.md` skills from. For example, in Claude Code: ```sh theme={"dark"} # 1. Add this marketplace /plugin marketplace add overcut-ai/overcut-skills # 2. Install the plugin /plugin install overcut-importer@overcut-skills ``` Once installed, ask your agent to convert your framework to Overcut and the skill runs. ## Import the result When you are ready to push the converted artifacts into a live project, install the [Overcut API Skill](/docs/quick-starts/overcut-skills/overcut-api) as well. The converter hands off to it in this order: 1. Commit the `out/skills/` folders into a repository connected to the project, then create the Skills from those paths. 2. Create an Agent per generated agent spec, then assign its Skills, MCP servers, and secrets. 3. Create a Workflow per generated definition. This edits the draft. You review it in the workflow builder and commit it live yourself. The converter produces artifacts and a plan; it does not design SDLC strategy. Deep product-design questions belong to the built-in Overcut assistant in the web app. ## Related * [Overcut API Skill](/docs/quick-starts/overcut-skills/overcut-api): import the converted artifacts into a live project. * [Create and edit workflows](/docs/quick-starts/create-workflows-from-playbooks): work with playbooks and your preferred AI coding agent. * [Skills](/docs/reference/skills): add `SKILL.md`-based skills to your Overcut agents. # Overcut API Skill Source: https://docs.overcut.ai/docs/quick-starts/overcut-skills/overcut-api Add the overcut-api skill to your AI coding agent to build workflows and agents, monitor executions, and debug runs in plain language. The `overcut-api` skill connects an AI coding agent to the Overcut GraphQL API. Once it is available, you can explore and manage your Overcut account in plain language: build a workflow, inspect an agent's skills, check why a run failed, or review token usage, without opening the web app. For a new setup, [Connect Your Coding Agent](/docs/get-started/connect-your-coding-agent) is the faster path: the CLI signs you in and connects your agent without installing this skill or creating a token by hand. Use this skill when you want direct GraphQL access and to manage the token yourself. For the full list of skills and the general install path, see the [Overcut Skills](/docs/quick-starts/overcut-skills) overview. ## What the skill does Everything you can see in the Overcut web app is also reachable through a single GraphQL endpoint, and the skill teaches your agent how to reach it. With a personal API token, it can: * **Explore your account**: workspaces, projects, workflows, agents, skills, MCP servers, secrets, repositories, and playbooks. * **Build and manage**: create and update workflows, agents, and orchestrations, assign skills and MCP servers, add workflows from playbooks, and trigger a workflow run. * **Monitor and analyze executions**: track workflow runs and orchestration instances, inspect execution history, and review token-usage analytics. * **Debug runs**: walk a failed run down through its steps, logs, and threads to find the root cause. * **Script your setup**: audit or report on your configuration from outside the UI. The skill defaults to read-only. It asks for confirmation before any create, update, delete, commit, or trigger action, and it never reads or prints secret values. ## Add the skill You add this skill the same way you add any skill to your agent. The exact steps vary by agent, so check your agent's documentation. There are two common paths: If your agent supports plugin marketplaces, add the marketplace repository `overcut-ai/overcut-skills` and install the `overcut` plugin. Otherwise, clone the [overcut-ai/overcut-skills](https://github.com/overcut-ai/overcut-skills) repository and copy the `overcut-api` skill folder (at `plugins/overcut/skills/overcut-api/`, including its `references/` and `scripts/`) into the directory your agent loads `SKILL.md` skills from. For example, in Claude Code: ```sh theme={"dark"} # 1. Add this marketplace /plugin marketplace add overcut-ai/overcut-skills # 2. Install the plugin /plugin install overcut@overcut-skills ``` Once installed, your agent uses the skill automatically when you ask it to work with your Overcut account. ## Authenticate The skill needs a personal API token so it can call the API as you. In the Overcut web app, go to **Workspace Settings → Security → API Tokens** and select **New API Token**. Copy the token when it is shown. You will not be able to see it again. Set the token as an environment variable before you start your agent: ```sh theme={"dark"} export OVERCUT_API_TOKEN="" # Production is the default. Override only for staging or self-hosted: # export OVERCUT_API_URL="https://server.overcut.ai/graphql" ``` The token carries the same permissions as the user who created it and expires after about 30 days of inactivity. Treat it like a password: never commit it or paste it into chat. For safety, create a dedicated, least-privilege user and generate the token as that user, so a leaked token has a limited blast radius. ## Use it Once the skill is available and the token is set, ask your agent in plain language. The skill translates your request into the right API calls. Example prompts: * "List my Overcut workflows and show which ones are active." * "Create a workflow from the code-review playbook in this project." * "Show the skills and MCP servers assigned to the code-review agent." * "Why did the last run of the release workflow fail?" * "Summarize token usage for this project over the last week." The skill starts from your workspace, drills into a project, and then into individual entities, asking for confirmation before it changes anything. Workflows run on a draft plus committed model: edits change the draft, and production keeps running the last committed version until you commit. The skill never commits, discards, or triggers without your explicit confirmation. ## What it doesn't cover The skill is about reaching the API: connecting, exploring, and running CRUD operations. It does not cover deeper product-design questions, such as how to write good step instructions, choose a base agent, or design triggers. For those, use the built-in Overcut assistant in the web app, which has current knowledge of the whole product. ## Related * [Connect Your Coding Agent](/docs/get-started/connect-your-coding-agent): CLI-managed connection for a new setup. * [Convert to Overcut](/docs/quick-starts/overcut-skills/convert-to-overcut): migrate an existing framework, then import it with this skill. * [Skills](/docs/reference/skills): add `SKILL.md`-based skills to your Overcut agents. * [Workflows](/docs/workflows/workflows): how workflows, steps, and triggers work. # Overcut Playbooks Source: https://docs.overcut.ai/docs/quick-starts/playbooks Browse, preview, and install ready-to-use workflow templates from the Playbook Catalog Overcut Playbooks help you launch proven workflow templates without starting from scratch. Use the **Playbook Catalog** to browse templates in Overcut, preview how each one works, and add the right workflow to your workspace. Use the [Overcut Playbooks repository](https://github.com/overcut-ai/overcut-playbooks) when you want to explore source files, read deeper implementation examples, or customize playbooks outside the product. ## What are Playbooks? Playbooks are pre-configured workflows that automate common software development tasks. Each playbook gives you a starting point that you can install in Overcut and then tailor to your team. ## Why Use Playbooks? Playbooks help teams move faster with reusable automation patterns: * 🚀 **Start faster**: Add a ready-to-use workflow instead of building every step manually * 🎯 **Use proven templates**: Begin with workflows designed for common engineering tasks * 🔧 **Customize after install**: Open the workflow in Workflow Builder and adapt it to your process * 📚 **Learn by example**: See how complete workflows are structured before creating your own ## Browse the Playbook Catalog The Playbook Catalog is where you discover public workflow templates in Overcut. It gives you a dedicated browsing experience so you can compare options, open previews, and install the workflows that match your team's needs. Playbooks are public and curated by Overcut. For templates that your own workspace maintains, use **Install from Library** on the Workflows page instead; see [Workspace Library](/docs/reference/workspace-library). You can also add a Playbook inside the Library to turn it into a private template for your projects. ### Open the catalog You can reach the Playbook Catalog from the main workflow experience in Overcut: * In the workflows area, select **Add from Playbook** to open the full catalog. * After completing onboarding, select **Browse Playbooks** to go directly to the catalog and explore recommended templates. ### Search playbooks Use the catalog search field to find playbooks by **name** or **description**. This helps you quickly narrow the list when you already know the kind of workflow you want to automate. ### Filter by workflow type Use the trigger category filters to narrow the catalog by workflow type. For example, you can focus on playbooks for pull requests, issues, scheduled work, or other trigger-driven automation patterns. If your search and filters do not match any results, the catalog shows an empty state so you can adjust your criteria and keep browsing. ## Preview a playbook before installing Select any playbook card in the catalog to open its detail view. In the detail view, you can review: * The playbook name * A short description of what it does * The first instruction or setup guidance included with the workflow This preview helps you understand the playbook before adding it to your workspace. ## Understand install status The playbook detail view also shows whether a matching workflow is already installed in your workspace. If Overcut finds an installed workflow with the same playbook name, the detail view lets you know before you install again. This makes it easier to avoid confusion when your workspace already has the workflow you are looking for. ## Install a playbook When you find a playbook you want to use, select **Add to Workspace**. Overcut installs the workflow into your workspace so you can open it in Workflow Builder and customize it. After installation, Overcut confirms the workflow was added and gives you a direct path to open it in Workflow Builder. ### If a matching workflow is already installed If the playbook is already installed, Overcut highlights that status in the detail view and gives you an **Open existing** option. This takes you directly to the existing workflow instead of making you guess whether you should create another copy. You can still choose to install the playbook again if you want another copy to customize separately. *** ## Create & Customize with AI The playbook repository is also an **AI-powered workspace**. It includes built-in skills and rules for popular AI coding tools such as Claude Code, Cursor, Codex, and Gemini, so you can clone it and use your preferred agent to create new workflows or customize existing ones. ```bash theme={"dark"} git clone https://github.com/overcut-ai/overcut-playbooks.git ``` Open the repo in your AI coding tool and start asking: * *"Create a new playbook that runs security checks when a PR is opened"* * *"Modify the code-review playbook to add a linting step"* * *"Explain how the create-pr-from-design playbook works"* The agent understands Overcut's workflow format, trigger types, step actions, template variables, and agent tool capabilities. For a complete walkthrough on using the playbook repo with AI agents, see **[Create & Edit Workflows](/docs/quick-starts/create-workflows-from-playbooks)**. *** ## Customizing Playbooks ### Understanding Playbook Structure Each playbook folder contains: ``` playbook-name/ ├── workflow.json # Import this into Overcut ├── README.md # Documentation and usage guide ├── step-id-name.md # Prompt for step (filename = step ID) ├── another-step-id.md # Each prompt file matches its step ID └── special-agents/ # (Optional) Specialized agent instructions └── agent-name.md # Instructions for configuring custom agents ``` ### Editing Prompts Prompt filenames match step IDs in `workflow.json`, enabling AI-assisted updates: 1. Edit the markdown file for the step you want to change 2. Use AI to update the `workflow.json` file to match your changes 3. Re-import the updated workflow into Overcut **Bidirectional Editing**: You can edit prompts in the markdown files and have AI update the workflow, or modify the workflow in Overcut and export it back. The naming convention (step ID = filename) makes this seamless. ### Special Agents Some workflows require specialized agents with domain-specific expertise. When a playbook needs agents like "Security Engineer" or "Database Architect", you'll find configuration instructions in the `special-agents/` folder. *** ## Best Practices ### Start Simple Begin with a single playbook that addresses your most immediate need. Once you're comfortable with the workflow, expand to additional playbooks. ### Customize Gradually Install the playbook first, test it, then customize prompts to match your team's style. This helps you understand the workflow before making changes. ### Monitor and Iterate Track how playbooks perform in your environment. Adjust prompts based on what works well and what needs improvement. Each team's codebase and process is different. ### Combine Playbooks Many playbooks work well together. For example: * **Requirements Document Generation** → **Technical Design Proposal** → **Create PR from Design** * **Auto Root Cause Analysis** → **Fix Review Comments** *** ## Next Steps * **[Create & Edit Workflows](/docs/quick-starts/create-workflows-from-playbooks)**: Build workflows visually or use your AI coding agent with the playbook repo * **[Import & Export Workflows](/docs/workflows/workflow-import-export)**: Detailed guide for importing workflows into Overcut * **[Workflow Builder](/docs/how-to/workflow-builder)**: Customize installed workflows in the builder * **[Browse Playbooks Repository](https://github.com/overcut-ai/overcut-playbooks)**: Explore source files, READMEs, and examples *** ## Contributing Found a playbook that works well for your team? Consider contributing improvements back to the community. The playbooks repository welcomes: * New playbooks for common workflows * Improvements to existing playbooks * Better prompts and documentation * Bug fixes and edge case handling See the [Contributing Guide](https://github.com/overcut-ai/overcut-playbooks/blob/main/CONTRIBUTING.md) for details. # Private Package Registries Source: https://docs.overcut.ai/docs/quick-starts/private-package-registries Give agents access to private package feeds like Azure DevOps NuGet using a Vault secret and a reusable skill. Many projects restore dependencies from a private registry: a NuGet feed on Azure DevOps, a scoped npm registry, or an internal PyPI index. Agents working in those repositories need credentials to run `dotnet restore`, `npm install`, or `pip install` successfully. This guide shows the recommended pattern: store the registry credential as a [Vault](/docs/reference/vault) secret and teach agents how to use it with a [skill](/docs/reference/skills). The same two building blocks work for any registry. This guide uses a private NuGet feed on Azure DevOps as the worked example, then shows how to adapt it to other package managers. ## How it works Vault secrets are injected as environment variables into the agent's execution sandbox at runtime. The secret value is never sent to the AI model; the agent only references the variable by name in shell commands. A skill carries the instructions for registering the feed, so every agent that builds the affected repositories knows what to do without you repeating the setup in each workflow step. In Azure DevOps, go to **User settings → Personal access tokens → New Token** and create a token with only the **Packaging → Read** scope. That is the only scope needed to restore packages. Note the expiration date so you can rotate the token in time. Open the project, then go to **Project Settings → Project Vault** and click **New Secret**. Name it `ADO_NUGET_PAT` (names must start with an uppercase letter and contain only uppercase letters, numbers, and underscores) and paste the token as the value. Either toggle **Available for All Executions**, or assign the secret to the specific workflows and agents that build .NET code. See [Assigning Secrets](/docs/reference/vault#assigning-secrets) for the options. Skills are `SKILL.md` files discovered from your connected repositories (Overcut scans the `skills/`, `.claude/skills/`, and `.agents/skills/` directories). Add one to a repository your workspace is connected to, for example at `skills/private-nuget-feed/SKILL.md`: ```markdown theme={"dark"} --- name: private-nuget-feed description: How to authenticate to our private Azure DevOps NuGet feed before restoring or building .NET projects. Use whenever a task involves dotnet restore, build, or test. --- # Private NuGet Feed Setup Before running any `dotnet restore`, `dotnet build`, or `dotnet test` command, register our private NuGet feed (once per task): dotnet nuget add source "https://pkgs.dev.azure.com///_packaging//nuget/v3/index.json" \ --name private-feed \ --username unused \ --password "$ADO_NUGET_PAT" \ --store-password-in-clear-text - If the command fails because the source `private-feed` already exists, the feed is already registered; continue with the build. - Always pass the password as the literal shell reference `$ADO_NUGET_PAT` so the shell resolves it; the variable is preset in your environment. - If restore fails with 401, report that the NuGet credentials appear to be invalid or expired instead of retrying with other credentials. ``` Replace ``, ``, and `` with your values. The description matters: it is what tells the agent to use the skill when a .NET task comes up. In your project, go to **Skills**, select **Add Skill**, pick the repository that contains the skill, and add it. Then open each agent that works with your .NET repositories and select the skill in the agent's **Skills** section. See [Skills](/docs/reference/skills) for the full flow. Trigger a workflow that restores packages from the private feed. The agent registers the feed using the injected variable and the restore succeeds. If it fails with `401 (Unauthorized)`, check the troubleshooting section below. The feed URL format above is for organizations on `dev.azure.com/`. If your organization uses the legacy `.visualstudio.com` domain, copy the exact `index.json` URL from the feed's **Connect to feed → dotnet** page instead of constructing it. ## Adapting to other package managers The pattern is identical for any registry: a least-privilege credential in the Vault, plus a skill that tells the agent how to wire it up before installing dependencies. Only the setup command changes. | Registry | Vault secret | Skill instructs the agent to | | --------------------- | -------------------- | ------------------------------------------------------------------------------------------------- | | npm (scoped registry) | `NPM_REGISTRY_TOKEN` | Write an `.npmrc` entry: `//registry.example.com/:_authToken=${NPM_REGISTRY_TOKEN}` | | PyPI (private index) | `PIP_INDEX_TOKEN` | Export `PIP_INDEX_URL=https://user:$PIP_INDEX_TOKEN@pypi.example.com/simple` before `pip install` | | Maven (private repo) | `MAVEN_REPO_TOKEN` | Write a `~/.m2/settings.xml` server entry referencing the variable | ## Alternatives * **Configuration committed to the repository.** NuGet expands environment variables in `nuget.config` using `%VAR%` syntax, so you can commit the feed and credential reference instead of using a skill. This makes restores deterministic, but the committed credentials section takes precedence on developer machines too: every developer must set the same variable locally or their restores fail with 401. * **Custom agent image.** If you already use a [custom agent image](/docs/reference/agent-images), you can bake the registry configuration into the image (for example, a user-level NuGet config or the Azure Artifacts Credential Provider) and keep only the credential in the Vault. ## Troubleshooting * **Restore fails with `401 (Unauthorized)`**: the token is expired or lacks the Packaging Read scope. Generate a new token and update the secret value in the Project Vault; no workflow or skill changes are needed. * **The variable is empty in the sandbox**: the secret is not available to that execution. Make sure it is set to **Available for All Executions** or assigned to the workflow or agent that runs the build. * **The agent skips the feed setup**: the skill was not loaded. Confirm the skill is enabled in the project's **Skills** list and assigned to the agent, and that its description mentions the build commands it applies to. ## Related documentation * [Vault](/docs/reference/vault): secret storage, assignment, and the security model * [Skills](/docs/reference/skills): discovering, adding, and assigning repository-backed skills * [Agent Images](/docs/reference/agent-images): bake registry configuration into a custom execution image * [Azure DevOps Integration](/docs/integrations/azure-devops): connect Azure DevOps repositories to Overcut # Reuse a Workflow Across Repositories Source: https://docs.overcut.ai/docs/quick-starts/reuse-a-workflow-across-repositories Run one workflow against repositories with different base branches by defining a context parameter once and setting a value per repository. Most of your repositories branch from `main`, but two legacy services still use `develop`. Instead of keeping a copy of the pull request workflow per repository, define one `base_branch` context parameter, set a repository value where it differs, and reference it from the workflow. This guide takes about ten minutes. ## Before you start You need a project with at least two connected repositories and a workflow that runs an agent against a repository. Defining a workspace parameter requires a role that can create context parameters; ask a workspace admin if the **New Parameter** button is missing. Open **Context Parameters** in the workspace navigation and select **New Parameter**. Enter `base_branch` as the **Key**, leave **Level** at **Workspace (visible to every project)**, and set the **Default value** to `main`. Save. The default is what every run uses unless a more specific value applies. Open the legacy repository's page and find its **Context Parameters** panel. Select **Add override**, pick `base_branch`, enter `develop`, and save. The value applies immediately to the next run on that repository. You can do the same from the parameter's own page: open `base_branch`, select **Add override** in the **Overrides** section, and choose the repository under **Where it applies**. Open the workflow in Workflow Builder, select the Agent Run step, and edit **Instructions**. Type `{{params.` and pick `base_branch` from the completion list. For example: ```text theme={"dark"} Open the pull request against {{params.base_branch}}. Never target any other branch. ``` Publish the workflow. Publishing checks that every referenced key exists. Open the **Playground**, select the workflow, then select the legacy repository. The **Context parameters** panel lists `params.base_branch` with the value `develop` and the source `Repository: `. Switch to any other repository and the panel shows `main` from `workspace default`. If the panel says `no value: the run will fail at preparation`, the key has no default and no value on this path. If it says `not defined: publishing will be blocked`, check the spelling. Run the workflow from the Playground against the legacy repository. When the run appears under **Logs**, open **View Details** and select **Context** in the run header. The **Run Context** panel shows `"base_branch": "develop"` under `params`. That snapshot is what every step in the run used. ## What you built One published workflow serves every repository. Adding a third legacy repository is one value on that repository's page, with no workflow edit and no publish. Changing the convention for everyone is one edit to the default. ## What to try next * **An orchestration value.** Two orchestrations run this workflow with different branch-name suffixes. Add a `branch_suffix` parameter, reference it in the instruction, and set a value on each orchestration in its properties panel. The orchestration value wins over the workflow's own value. * **An agent value.** Set `review_tone` to `thorough` on a security reviewer agent and `concise` on everyone else. Each agent's steps resolve its own value in the same run; the **Run Context** panel shows the difference under `agentParamOverrides`. * **A Run Script step.** Read the same value from a script as `$OC_PARAM_BASE_BRANCH`, or map it into **Environment Variables**. See [Run Script](/docs/workflows/run-script). ## Related * [Context Parameters](/docs/reference/context-parameters): every control, the resolution order, and troubleshooting. * [Reuse Across Projects](/docs/concepts/reuse-across-projects): when a parameter is the right tool and when the Workspace Library is. # Agent Images Source: https://docs.overcut.ai/docs/reference/agent-images Register container images from your own registry so agents build and test with the exact toolchain your repositories need. An agent image is the container your agents run in. Cloning, builds, tests, `script.run` steps, and stdio MCP servers all execute inside it. Overcut ships two system images that cover common stacks. When a repository needs something they lack (Rust, Bazel, a pinned SDK, an internal CLI), you register an image from your own registry on the **Agent Images** page and select it for that repository. Open **Agent Images** from the workspace sidebar, under **Agent Runtime**. Registering custom images is an Enterprise feature. On other plans the page describes the feature and offers **Get access to custom images**. System images are available on every plan. *** ## How it works Build the image with the SDKs, compilers, and CLIs your repositories need. Overcut adds its own runtime at run start, so nothing Overcut-specific goes into the image. Any public or private OCI registry: GitHub Container Registry, Docker Hub, Azure Container Registry, GitLab, Quay, Artifactory, and others. Overcut resolves the tag to a digest once at registration. Every run uses that digest, even if the tag moves upstream. You choose when to pick up a new build. Images are workspace-level. Each repository picks one, or keeps the default. See [Repository Agent Image](/docs/repositories/agent-image) for the repository setting. *** ## System and workspace images | Kind | Who maintains it | Where it appears | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **System images** | Overcut. **Universal 2** (the default) and **Universal 6** are based on Microsoft's dev container universal image and ship Python, Node.js, Java, Go, Ruby, PHP, and .NET. | In every repository's **Agent Image** picker under **System images**. They are not listed on the Agent Images page and cannot be edited. | | **Workspace images** | You. Registered from a registry you control and visible only to your workspace. | On the Agent Images page, and in the repository picker under **Workspace images** once they are **Ready**. | Toolchain first, image second. If a repository only needs a newer version of a language the default image already ships, select **Universal 6** instead of registering a custom image. Custom images are for toolchains the universal images lack. Custom images are also not a substitute for [Repository Caching](/docs/repositories/repository-caching). Put SDKs, compilers, system packages, and private CLIs in the image. Leave `npm install` and similar dependency installs to the cache. *** ## Image requirements Overcut copies your image into its own registry and checks it before making it selectable. The image must: * Be built for **linux/amd64**. Multi-architecture images are fine; Overcut picks the amd64 variant. * Be at most **4 GiB compressed**. * Include `bash` and `git`. * Have a writable `/tmp`. Every standard base image does; only minimal images built from `scratch` lack it. * Use a **glibc** userland with `libstdc++` (Debian, Ubuntu, RHEL, and similar). Alpine and other musl-based images, and `scratch` images, fail the check. * Work when run as a non-root user. Overcut runs every image as a fixed non-root user, ignoring the image's own `USER`, so toolchains must be runnable by a non-root user. Anything that only works as root (a tool installed with root-only permissions, an SDK that writes to its install directory) fails at run time. Nothing else is required. Overcut sets the home directory on a writable volume it mounts, so the image needs no user account or home. At run start it mounts its own runtime into the container, which is why glibc and `libstdc++` must be present. Never bake tokens or secrets into an image. Image layers are permanent. Store credentials in the [Vault](/docs/reference/vault) and let workflows inject them at run time. *** ## Registering an image Select **Agent Images** in the workspace sidebar, then click **Register image**. Enter a **Name**. It is shown in the repository image picker and must be unique in the workspace. Add an optional **Description** so teammates know what the image ships. In **Image reference**, enter the full `registry/repository:tag`, in lowercase, for example `ghcr.io/acme/runner:1.2`. Docker Hub images can omit the registry host. Under **Registry access**, leave **Credential** at **None (public image)** for a public image. For a private image, pick an existing credential for that registry host or click **New credential** to add one. See [Registry credentials](#registry-credentials). Click Save. Overcut resolves the digest, copies the image, and runs the compatibility check in the background. The image detail page opens and updates as registration progresses. Registration takes from seconds to a few minutes depending on image size. The image becomes selectable in repository settings once its status is **Ready**. ### Registry credentials Private images need a credential for their registry. The credential's **Registry host** must match the host in the image reference (`ghcr.io` for `ghcr.io/acme/runner:1.2`, `docker.io` for Docker Hub). Click **New credential** in the register form to open the **New registry credential** dialog and fill in: | Field | Value | | --------------------- | ---------------------------------------------------------------- | | **Name** | A label such as `ghcr read token`. | | **Registry host** | Pre-filled from the image reference. | | **Username** | The registry username, or the account name the token belongs to. | | **Password or token** | A read-only token or password for the registry. | Use a token with pull-only permissions. The value is stored encrypted, sent to the registry only during registration and refresh, and never shown again. To rotate a token, create a new credential and select it on the image; saving registers the image again with the new credential. Registry credentials are separate from the Vault. They authenticate Overcut to your registry when it copies the image, and are never available to agents or workflows. *** ## Image status Each image shows a status on the Agent Images list and on its detail page, with a message under **Details** that explains the current step or the failure reason. | Status | Meaning | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Pending** | Overcut is resolving the image digest and size from your registry. | | **Importing** | The digest is known. The image is being copied and checked for compatibility. | | **Ready** | The image is selectable by repositories. Runs use the digest shown on the detail page. | | **Failed** | Registration failed. The details column shows why: authentication (401 or 403), image not found, too large, or a list of failed compatibility checks. The image cannot be selected. | | **Disabled** | A user deactivated the image. It cannot be selected, and runs on repositories that still select it fail until you activate it again or switch them. | The detail page also shows the pinned **Digest**, **Size (compressed)**, where runs pull the copy from (**Runs from**), and when it was **Registered**. ### Refreshing and retrying Runs stay pinned to the digest resolved at registration. When you push a new build to the same tag, click **Refresh** on the image detail page: * If the tag now points at a new digest, Overcut registers the new build while the current digest keeps serving runs. The status message shows **Refreshing** until the swap completes. * If nothing changed, the message shows **Up to date**. * If the new build fails registration, the message starts with **Refresh failed** and the previous digest stays in use. On a **Failed** image the same button reads **Retry**. Use it after fixing the reference, the credential, or the image itself. ### Editing an image Open the image and change any field, then Save: * Changing the **Name** or **Description** takes effect immediately and does not affect runs. * Changing the **Image reference** or the **Credential** registers the image again. A Ready image keeps running on its current digest until the new copy is ready. A Failed image restarts its registration. Refresh, Retry, and Save are unavailable while a registration is in progress. Refresh is also unavailable on a Disabled image; activate it first. ### Deactivating and deleting * **Deactivate** a Ready image with the activation toggle next to its name on the detail page. Repositories can no longer select it, and runs on repositories that still select it fail at preparation. Click the toggle again to activate it. The toggle is only shown for Ready and Disabled images. * **Delete** removes the image from the workspace. The button is unavailable while a registration is in progress or while any repository selects the image; the tooltip tells you how many. Switch those repositories to another image first. Runs already in progress are not affected. *** ## Selecting an image for a repository Images apply per repository. Open the repository's settings, and in the **Agent Image** section pick from **Default Image**, **System images**, or **Workspace images**. Only Ready, active workspace images appear. The choice applies from the next run. For ticket repositories (Jira, Azure DevOps boards), set the image on the linked **code** repository: that is where agents build and test. Resolution order and conflict handling are covered in [Repository Agent Image](/docs/repositories/agent-image#how-overcut-selects-the-image-for-a-run). After switching a repository to a new image, run one of its workflows from the Playground to confirm builds and tests pass in the new environment before relying on it in production. *** ## Plan limits Custom images require an Enterprise plan and count against a per-workspace quota. Pending, Importing, and Ready images count toward it; Failed and Disabled images do not, so a broken registration never blocks a retry. When you hit the limit, registering shows **Your current plan allows up to N custom agent images**. Delete or deactivate images you no longer use, or contact Overcut to raise the limit. *** ## Troubleshooting | Symptom | Cause | Fix | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Image **Failed**, details mention 401, 403, unauthorized, or denied | Private image without a credential, wrong credential, or a credential whose registry host does not match the reference | Select the right credential on the image (or create one) and Save, or click **Retry** after fixing it | | Image **Failed**, details mention not found or manifest unknown | Wrong repository or tag, or no linux/amd64 variant published | Correct the **Image reference** and Save | | Image **Failed**, details mention size or larger than | Image exceeds 4 GiB compressed | Slim the image (multi-stage build, drop package caches), push, then **Retry** | | Image **Failed**, details list bash, git, glibc, libstdc++, or /tmp | The image does not meet the [requirements](#image-requirements); typically an Alpine or scratch base | Rebuild on a glibc base with the listed items, push, then **Retry** | | Register shows **Your current plan does not allow custom agent images** | The workspace plan does not include custom images | Click **Get access to custom images** on the Agent Images page | | Run fails at preparation with **Agent image ... is not available: status is Disabled** (or Failed) | The repository selects an image that is no longer Ready | Activate or Retry the image, or switch the repository to another image | | Run fails at preparation with **image pull failed** | The image copy could not be pulled | Click **Refresh** to re-check the source, and confirm the image still exists in your registry | | Run fails at preparation with **agent image ... is incompatible** | The image passed registration but cannot run Overcut's injected runtime | Rebuild on a glibc base with `libstdc++`, push, then **Refresh** | | A build or test step fails with `command not found` for a language or tool | The repository runs on an image without that toolchain | Select **Universal 6** or register a custom image, then select it for the repository | *** ## Chat Overcut chat can list images and their status, register an image from a reference you provide, refresh or retry a registration, activate or deactivate an image, and select an image for a repository. It never asks for registry passwords: create credentials on the Agent Images page and chat can attach an existing one. Deleting images stays in the UI. See [Chat with Overcut](/docs/how-to/chat-with-overcut). *** ## Related * [Repository Agent Image](/docs/repositories/agent-image): the per-repository setting and how a run resolves its image * [Repository Caching](/docs/repositories/repository-caching): speed up dependency installs without changing the image * [Private Package Registries](/docs/quick-starts/private-package-registries): bake registry configuration into a custom image * [Vault](/docs/reference/vault): where credentials for workflows belong # Audit Trail Source: https://docs.overcut.ai/docs/reference/audit-trail An immutable record of who changed what in your workspace, for security review, compliance, and incident investigation. ## Overview Audit Trail is the system of record for change in your workspace. Every time someone creates, updates, or removes a resource, Overcut writes an event that captures who did it, what they did, which resource was affected, and when. That history gives security and compliance teams the accountability they need: a verifiable answer to "who changed this, and when," without depending on anyone's memory or on the resource itself still existing. Use Audit Trail to investigate a configuration change, reconstruct the sequence of events around an incident, confirm that a sensitive value was rotated, or produce evidence for an access review or compliance audit. The Audit Trail page in workspace settings, showing a table of events with action, entity, name, performed-by, and time columns, and an Event Details panel with a before and after JSON diff for an agent model change. Events are captured automatically whenever a resource changes, so coverage does not depend on each feature remembering to log. Records are append-only: Overcut writes them and nothing in the product edits or deletes them, so the history you review is the history as it happened. ## Access Viewing Audit Trail is restricted to roles responsible for security, compliance, and operational review, so workspace activity stays visible only to the people accountable for it. If you do not see Audit Trail in the workspace, ask a workspace administrator to confirm your role includes permission to view audit logs. ## What gets recorded Each event captures a single change to a single resource. The fields below are what you review and filter on: | Field | What it tells you | | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Action** | The kind of change: `Create`, `Update`, `Delete`, `Soft Delete`, or `Restore`. | | **Entity** | The type of resource affected, such as a project, user, role, repository, workflow, agent, secret, or context parameter. | | **Name** | The resource's display name when available, otherwise an identifier. | | **Performed by** | The user who made the change, or a system actor for automated activity. | | **Time** | When the action occurred. | | **Changes** | A before and after comparison of the changed fields, when change details are available. | The before and after comparison is a summary of which fields changed, not a full copy of the resource. Treat it as evidence that a change happened and what it affected, rather than a backup you can restore from. ## How sensitive values are protected When a change touches a secret or other protected field, Overcut redacts the value before the event is ever written. The event still records that the field changed, who changed it, and when, but the value itself never enters the audit log. This applies to resources like project secrets, API tokens, and credentials. The event names which fields were redacted, so you can see exactly what changed while the values themselves stay out of the log. Audit Trail confirms that a protected value was added, changed, or removed. It is not a way to read or recover the value. To validate, rotate, or replace a secret, use the resource's own settings (for example, the project [Vault](/docs/reference/vault)). Audit Trail is for confirming the change occurred, not for retrieving the value. ## Filter the history Events are shown newest first, scoped to the last 7 days by default. Widen or remove the time range to review older activity. Combine filters to narrow a large history down to the change you are investigating: * **Action**: isolate creates, updates, deletions, or restores. * **Entity type**: focus on one category of resource, such as users, repositories, or secrets. * **Actor**: see everything a specific user did. * **Project**: limit results to a single project's activity. * **Time range**: Last 24 hours, Last 7 days, Last 30 days, or All time. A typical investigation starts with a time range and an entity type, then adds an actor or action to find the specific event and the related changes around it. ## What activity is covered Audit Trail records change across the resources teams configure and operate, including: * **Workspaces and projects**: workspace and project settings and configuration. * **People and access**: users, teams, roles, permissions, and invitations. * **Source control**: connected repositories and Git organizations. * **Automation**: workflows, agents, skills, MCP servers, and channels. * **Sensitive configuration**: API tokens, project and Library secrets, LLM model credentials, and Custom Events. * **Context parameters**: definitions and the values set on each scope. Values are plain text by design, so the value itself is recorded, unlike a secret. Audit Trail captures changes to configuration and access, not runtime activity. It records the per-resource changes teams make, so an individual run's internal steps are out of scope. For the details of a workflow run, look at its execution log instead. ## Related references * [Privacy and Security](/docs/privacy-and-security): how Overcut protects workspace data and secrets. * [Vault](/docs/reference/vault): manage the secrets used by workflows, agents, and MCP servers. * [Context Parameters](/docs/reference/context-parameters): the plain-text values whose changes are recorded in full. * [Workspace Settings](/docs/reference/workspace-settings): configure workspace-level profile, defaults, and credentials. # Base Agent Types Source: https://docs.overcut.ai/docs/reference/base-agents Reference for all built-in base agent types, their default toolsets, and when to use each. Every Overcut agent is built on a **base agent type**. The base type determines two things: the agent's default toolset, and its built-in role instructions. Each base type ships with pre-configured instructions covering the agent's role, relevant engineering processes, and guidelines for using its tools correctly: for example, how a Senior Developer should approach making code changes, or how a Code Reviewer should structure feedback. These instructions run in the background and you don't need to repeat them in your workflow prompts. You can extend any base type with additional instructions, extra tools, and [MCP Servers](/docs/reference/mcp-servers) to create specialized agents tailored to your workflows. Additional instructions are layered on top of the base instructions, not replacing them. For example, you can create a "Backend Developer" and a "Frontend Developer" agent, both built on **Senior Developer**, each with their own specialized instructions and tool extensions. Backend Developer agent configured on the Senior Developer base type: the Base Agent selector, the default toolset rendered as chips, and the Additional Instructions used to specialize it. *** ## Comparison | Base Type | Default Tools | Best for | | ------------------------------------- | ------------- | ----------------------------------------------- | | [Senior Developer](#senior-developer) | 30 | Implementation, debugging, full code lifecycle | | [Tech Writer](#tech-writer) | 25 | Documentation, spec writing, structured content | | [Code Reviewer](#code-reviewer) | 24 | PR reviews, code quality, CI monitoring | | [Product Manager](#product-manager) | 18 | Ticket management, planning, triage | | [Custom](#custom) | **0** | Fully custom roles with hand-picked tools | *** ## Senior Developer A full-stack engineering agent with the broadest default toolset. It can read and write code, run terminal commands, manage tickets, open and close pull requests, and monitor CI pipelines. **Best for:** Feature implementation, bug fixes, refactoring, debugging, and any task that requires making changes to the codebase. ### Default tools **File System**: Read File, Write File, Edit File, Append File, Delete File, Create Directory, List Directory **Code Utilities**: Search Code, Semantic Code Search, Execute Terminal Commands, Explore Codebase **Tickets and Issues**: Create Ticket, Update Ticket, Read Ticket, List Tickets, Add Comment to Ticket, Update Comment on Ticket **Pull Requests**: Create Pull Request, Read Pull Request, Update Pull Request, List Pull Requests, Add Comment to Pull Request, Update Comment on Pull Request, Close Pull Request, Get Pull Request Diff **CI/CD**: List PR CI Runs, Get CI Run Details, Get CI Run Logs, Get CI Job Logs, Retry CI Workflow See the [full tool descriptions](/docs/reference/tools) for details on each tool. *** ## Tech Writer A writing-focused agent with full file access and the ability to create and update tickets and pull requests. Designed for agents that produce or maintain documentation, specs, or structured content. **Best for:** Writing and updating documentation, drafting specs from tickets, generating changelogs, and any task that primarily involves producing text content in the repository. ### Default tools **File System**: Read File, Write File, Edit File, Append File, Delete File, Create Directory, List Directory **Code Utilities**: Search Code, Semantic Code Search, Execute Terminal Commands, Explore Codebase **Tickets and Issues**: Create Ticket, Update Ticket, Read Ticket, List Tickets, Add Comment to Ticket, Update Comment on Ticket **Pull Requests**: Create Pull Request, Read Pull Request, Update Pull Request, List Pull Requests, Add Comment to Pull Request, Update Comment on Pull Request, Close Pull Request, Get Pull Request Diff See the [full tool descriptions](/docs/reference/tools) for details on each tool. *** ## Code Reviewer A read-focused agent built specifically for pull request reviews. It can read (but not write) files, analyze code changes, add inline review comments, and monitor CI runs, but cannot create or merge PRs, or update ticket fields. **Best for:** PR code reviews, automated quality checks, security analysis, and any task that should inspect code without making changes. ### Default tools **File System**: Read File, Append File, List Directory **Code Utilities**: Search Code, Semantic Code Search, Execute Terminal Commands, Explore Codebase **Tickets and Issues**: Read Ticket, List Tickets, Add Comment to Ticket, Update Comment on Ticket **Pull Requests**: Read Pull Request, Update Pull Request, List Pull Requests, Add Comment to Pull Request, Update Comment on Pull Request, Get Pull Request Diff **Code Review**: Add Review Comment, Reply to Review Comment, Submit Review **CI/CD**: List PR CI Runs, Get CI Run Details, Get CI Run Logs, Get CI Job Logs See the [full tool descriptions](/docs/reference/tools) for details on each tool. *** ## Product Manager A planning and coordination agent focused on tickets and pull request oversight. It can read files and code, but cannot write to the repository directly. It manages the full ticket lifecycle and can comment on pull requests. **Best for:** Issue triage, sprint planning, ticket creation from PRs or incidents, dependency analysis, and any workflow that coordinates work without touching code directly. ### Default tools **File System**: Read File, List Directory **Code Utilities**: Search Code, Semantic Code Search, Execute Terminal Commands, Explore Codebase **Tickets and Issues**: Create Ticket, Update Ticket, Read Ticket, List Tickets, Add Comment to Ticket, Update Comment on Ticket **Pull Requests**: Read Pull Request, Update Pull Request, List Pull Requests, Add Comment to Pull Request, Update Comment on Pull Request, Get Pull Request Diff See the [full tool descriptions](/docs/reference/tools) for details on each tool. *** ## Custom The Custom base type starts with **no default tools** and no role-specific instructions. It includes only the general agent harness (the base operational framework shared by all agents), with no persona, no process guidelines, and no assumptions about what the agent should do. This makes Custom well-suited for focused, specific tasks where you want full control over the agent's behavior. Because there are no pre-configured role instructions, there's no risk of them conflicting with your own instructions. **Custom agents start with an empty tool list.** When you select Custom as the base type, the tool selection UI will show no tools selected. The agent will have no built-in capabilities until you add tools manually. **Best for:** Specific, narrowly-scoped tasks where you want to provide all instructions yourself without interference from role defaults. Examples include a dedicated security auditor, a changelog generator with restricted write access, or a triage-only agent that should never touch code. ### Configuring a Custom agent In **Agent Roles** → **Add Agent**, choose **Custom** from the base agent type selector. From the tool selection list, pick only the tools this agent needs. See the [Agent Tools Reference](/docs/reference/tools) for descriptions of each tool and which category it belongs to. Unlike other base types, Custom has no pre-configured role instructions. Use the **Additional Instructions** field to fully define the agent's role, behavior, and constraints. Since there are no background instructions to rely on, this step is essential for the agent to behave as intended. Choose the LLM model for this agent. Custom agents follow the same [model fallback cascade](/docs/building-blocks#model-defaults-and-fallback-order) as all other agents. If your agent shares most of its behavior with an existing base type but needs fewer tools, consider using that base type with **Additional Instructions** to constrain its behavior, rather than starting from scratch with Custom. *** ## Automatically injected tools All agents, regardless of base type, automatically receive the following tools at runtime. These cannot be added or removed from the tool selection UI: * **Scratchpad tools** (`write_scratchpad`, `append_scratchpad`, `read_scratchpad`, `list_scratchpads`): for staging notes and sharing findings. See [Scratchpad Tools](/docs/reference/scratchpad-tools). * **Memory tools**: for reading and writing persistent memory across runs. * **Update Status**: for sending real-time status updates visible in the Overcut UI. *** ## Extending agents with additional tools and MCP You can add tools to any agent beyond its base type defaults: * **Additional Tools**: in the agent's settings, select tools to layer on top of the base type's defaults. * **MCP Servers**: connect external tool servers for web search, databases, APIs, and more. See [MCP Servers](/docs/reference/mcp-servers) and the [MCP Catalog](/docs/quick-starts/mcp-catalog). * **Skills**: assign active skills to the agent so it can follow reusable guidance alongside its base instructions. Add and manage project skills in the project [Skills](/docs/reference/skills) area; skills from the Workspace Library appear in the same picker with a **Library** badge. The MCP Servers and Skills panels on a Backend Developer agent, populated with attached servers (Datadog, Sentry, Notion) and project skills (PR Description, Test Plan, Incident Postmortem). Use skills for reusable guidance that more than one agent may need, such as repository-specific conventions or workflow checklists. Keep agent-specific behavior in **Additional Instructions**. ## Context parameters in agent instructions **Additional Instructions** can reference a [context parameter](/docs/reference/context-parameters) as `{{params.}}`, for example `Reply in {{params.response_language}}.` Type `{{params.` in the editor to pick from the keys visible to the project. Saving the agent checks that every referenced key exists. The agent's **Context Parameters** panel sets values that apply wherever this agent runs. An agent value is the most specific scope, so it wins over the project, repository, workflow, and orchestration values for that agent's steps only. Two agents in the same run can resolve the same key differently. ## Agents in the Workspace Library An agent is owned by one project or by the [Workspace Library](/docs/reference/workspace-library). Workflows in any project can run a Library agent; the agent picker in an Agent Run or Agent Session step groups agents under **Project** and **Workspace library**. A Library agent can attach only Library MCP servers, skills, and secrets. To share a project agent, select **Promote to library** on its page after promoting the secrets, MCP servers, and skills it depends on. Promotion moves the agent; workflows that already use it keep working. ## Assign skills to an agent Skills are added to the project, or to the Workspace Library, first, then assigned to individual agents. Only enabled skills are available for assignment. Go to your project's **Agents** area and select the agent you want to update. In the agent's **Skills** section, select one or more enabled skills to attach to that agent. Library skills carry a **Library** badge. Save your changes so the agent uses those skills in future runs. ### Remove skills from an agent If an agent no longer needs a skill, open the same **Skills** section in the agent settings and remove the skill from the assignment list, then save the agent. ### Before you assign a skill * Add the skill in the project [Skills](/docs/reference/skills) area first, or in the Workspace Library if every project should be able to use it. * Confirm the skill is enabled. Only enabled skills are available for assignment to agents. * Review the skill details in **Skills** to make sure you are assigning the right guidance to the right agent. # Context Parameters Source: https://docs.overcut.ai/docs/reference/context-parameters Define a value once, reference it from instructions by key, and let each project, repository, workflow, orchestration, or agent supply its own value at run time. A context parameter is a named plain-text value that workflows and agents reference as `{{params.}}`. Each run resolves every referenced key to the most specific value on its path, so one workflow or agent serves many teams, repositories, and orchestrations without being copied. Definitions live on the workspace **Context Parameters** page and in each project's settings; values can be set on projects, repositories, workflows, orchestrations, and agents. ## When to use a context parameter Teams copy a workflow, an agent, or an orchestration because one constant differs between the copies: a base branch, a branch-name suffix, a pull request title format, a reviewer list, a set of review conventions. The definition is identical and only the value changes per project, repository, or orchestration. A context parameter keeps one definition and moves the value out of it. | You need | Use | Not | | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | A non-secret value that differs by project, repository, workflow, orchestration, or agent | Context parameter | A copy of the workflow | | A credential such as an API key or token | [Vault](/docs/reference/vault) secret, injected as an environment variable and hidden from the model | A context parameter, which is visible in prompts and logs | | A value a person types when they start a run | Manual run inputs in the Playground, or slash command arguments | A context parameter, which is stored configuration | | Ambient guidance about one codebase that every agent should know | Repository custom instructions | A context parameter, unless an instruction needs to place the value inline | Typical keys: `base_branch` (`develop` for two legacy repositories, `main` everywhere else), `branch_suffix` per orchestration, `review_conventions` per repository, `pr_title_format` per project, `default_reviewers` per project. ## How values resolve A parameter has one **definition** (key, description, optional default) and any number of **values**, one per entity. When a run is prepared, Overcut looks for each referenced key from the most specific scope to the least specific and uses the first value it finds: ```text theme={"dark"} workspace default < project < repository < workflow < orchestration < agent ``` Two placements are deliberate: * **An orchestration beats the workflow's own value.** The workflow value is what the workflow uses on its own. An orchestration hands configuration to every workflow it runs, so it wins when both exist. * **A repository sits below a workflow.** Repository values describe the codebase, such as its base branch. A workflow author who sets a value on the workflow is making a narrower, deliberate choice. For example, `review_branch` has these values: | Scope | Value | | ----------------- | ------------ | | Workspace default | `main` | | Project | `develop` | | Repository | `release` | | Workflow | `staging` | | Orchestration | `production` | A standalone run of that workflow on that repository uses `staging`. The same workflow started by the orchestration uses `production`. Three more rules shape what a run sees: * **Agent values apply per step, not per run.** A value set on an agent applies only to the Agent Run or Agent Session steps that use that agent. Two agents in the same run can resolve the same key differently. * **Resolution happens once, at preparation.** Overcut resolves every referenced key before the first step starts and freezes that snapshot for the run. Editing a default or a value affects the next run, not one that is already prepared. * **Only referenced keys load, and nothing is broadcast.** A run loads the keys its steps and agents actually name. A parameter reaches an agent only through an instruction that contains `{{params.}}`; it is never added to the agent's context on its own. ## Define a parameter Create workspace definitions from **Context Parameters** in the workspace navigation. Create project definitions from **Project Settings → Context Parameters → Project Context Parameters**. Both open the same form. Enter the **Key**. Overcut formats it as lowercase with underscores as you type, so `Review Branch` becomes `review_branch`. Keys are unique across the workspace, including across the workspace and project levels, and cannot be changed after creation. **Level** is either **Workspace (visible to every project)** or **Project: *project name***. A workspace parameter can be given values at every scope. A project parameter is visible only inside that project, and its default acts as the project's value, so it takes no separate project value and cannot be given a value on another project's resources. The **Default value** is used when no more specific value applies. Turn on **No default: every run must find a value at a more specific level** when every run should get its value from a project, repository, workflow, orchestration, or agent. A referenced key with no value stops the run during preparation. Keys can contain letters, digits, and underscores, start with a letter or underscore, and are at most 64 characters. A value can be up to 16 KB, so multi-line conventions fit. A workflow, including the agents it uses, can reference at most 50 keys. Values are plain text. They appear in rendered prompts, run logs, and the audit trail. Keep credentials in the [Vault](/docs/reference/vault). ## Reference a parameter Insert a parameter into a supported field with this syntax: ```text theme={"dark"} Open the pull request against {{params.review_branch}}. ``` | Field | Rendered | | ------------------------------------------------------------------------- | -------- | | **Instructions** on any workflow step | Yes | | String inputs on a workflow step, such as a branch or a working directory | Yes | | **Environment Variables** values on a Run Script step | Yes | | **Inputs** values on an Execute CI Workflow step | Yes | | **Additional Instructions** on an agent | Yes | | **Bash Script** body on a Run Script step | No | Three editors offer completion: **Instructions** on an Agent Run step, **Instructions** on an Agent Session step, and **Additional Instructions** on an agent. Type `{{params.` to list the keys visible to the project with their descriptions and defaults. Parameters work with the same template helpers as trigger data. Values are strings, so a switch looks like this: ```text theme={"dark"} {{#if (eq params.strict_mode "true")}} Block the merge on any failing check. {{/if}} ``` ### In a Run Script step The **Bash Script** body is never rendered, which keeps trigger text and agent output from being interpreted as shell syntax. Put the reference in **Environment Variables** and read the variable from the script: ```yaml theme={"dark"} params: script: | printf 'Release channel: %s\n' "$RELEASE_CHANNEL" env: RELEASE_CHANNEL: "{{params.release_channel}}" ``` Run Script also receives every key the workflow references as `OC_PARAM_`, with the key in uppercase. `release_channel` is available as `$OC_PARAM_RELEASE_CHANNEL`. These variables carry the run-wide value, not an agent's value. ## Set values per scope There are two places to manage values: * **On the definition.** Open a parameter and use its **Overrides** section. Select **Add override**, choose where it applies (a project, repository, workflow, orchestration, or agent), enter the value, and select **Save**. The grid lists every value with its type, the entity it belongs to, and the value. * **On the entity.** Open a project (**Project Settings → Context Parameters → Project Values**), a repository, a workflow (the metadata panel in Workflow Builder), an orchestration (the properties panel with nothing selected), or an agent, and use its **Context Parameters** panel. Select **Add override**, pick the parameter, and enter the value. An entity's panel lists only the values set on that entity. It does not show what the entity inherits or which value a run would use. To see the effective value and its source, use the Playground preview described below. Values save immediately. A workflow or orchestration value is independent of the draft, so you do not publish to apply it; the next run picks it up. Use **Edit** to replace a value. Use **Delete**, then confirm with **Remove**, to remove it. Runs that include the entity then fall back to the next less specific value or the default. Removing a value never deletes the definition. Setting a value on a repository requires a workspace-level grant, because repositories belong to the workspace rather than to a project. ## Preview and verify ### Before a run In the **Playground**, select a workflow and, when relevant, a repository. The **Context parameters** panel lists each key the workflow references, the value it would resolve to, and the scope that supplies it, for example `Repository: web-app` or `workspace default`. The preview uses the committed workflow. If the Playground run is set to use the working draft, the preview follows the draft. A manual run resolves workspace defaults plus project, repository, and workflow values. Orchestration and agent values do not apply, because they are not part of a manual run. | Panel shows | Meaning | What to do | | -------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------ | | The value and its source scope | Resolved | Confirm that the source is the scope you intended. | | `not defined: publishing will be blocked` | No definition with that key is visible to the project | Check the spelling, then create the definition at the right level. | | `no value: the run will fail at preparation` | A definition exists but nothing on the manual-run path supplies a value | Add a default, or a value on the project, repository, or workflow. | The panel is empty when the selected workflow references no parameters. ### After a run Open **Logs → Workflow Executions**, select **View Details**, then select **Context** in the run header. The **Run Context** panel shows read-only JSON with the run's `trigger` data, step `outputs`, and the resolved parameters under `params`. When an agent used a more specific value, the panel also shows `agentParamOverrides`, grouped by agent. Run Context shows the frozen values a specific run used. It does not show which scope won. For that, use the Playground. ## Troubleshooting | Symptom | Cause | Fix | | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Publishing a workflow, or saving an agent, fails with `Unknown context parameter(s): params.. Define them under Context Parameters before publishing.` | The key has no visible definition. It was never created, or it is a project parameter of another project. | Create the definition, at the workspace level if more than one project needs it. Draft saves do not validate keys; only publish and agent save do. | | A run shows **Failed** with no failed step, and the preparation step reports `Context parameter(s) params. has no value for this run` | The key is defined but has no default and no value on the run's path. | Add a default, or a value on the project, repository, workflow, or orchestration. A key used only in an agent's Additional Instructions can also be satisfied by a value on that agent. | | The run used a value that the workflow's panel does not show | A more specific scope supplied it. The usual cause is an orchestration or an agent value. | Preview in the Playground for the manual-run path, and check the orchestration's and agent's **Context Parameters** panels for the rest. | | The Playground shows one value and the orchestration run used another | Orchestration values do not apply to manual runs. | Expected. Use Run Context on the orchestration run to see the frozen value. | | A multi-repository run used the wrong repository's value | Repository values come from the trigger repository, or the repository selected for a manual run. A repository identified later by a Repo Identify step does not change the resolved values. | Set the value on the workflow or orchestration instead, or trigger the run from the repository that should win. | | A scheduled or custom-event run ignored a repository value | Runs without a repository skip the repository scope. | Add a default or a project, workflow, or orchestration value. | ## Lifecycle and governance **Delete a definition.** Select **Delete** on the parameter and confirm the `Delete ""?` dialog. Every value is removed with it. Published workflows and agents that still reference the key fail at run preparation until you define the key again. Deleting a definition is different from removing one value. **Promote to workspace.** A project parameter has a **Promote to workspace** action. The parameter becomes visible to every project, keeps its id and every existing value, and cannot be moved back. Use it when a second project needs the same key, and before a Library template references it. **Export and import.** A workflow export lists the keys it references, with their descriptions, but not their definitions or values. An imported workflow lands as a draft and publishes only after every referenced key is defined in the target workspace. The same applies to templates installed from the [Workspace Library](/docs/reference/workspace-library): a template's keys must be workspace parameters, because a project parameter is not visible to the project that installs the copy. **Permissions.** Creating, editing, and deleting definitions and setting values are separate permissions on workspace roles. A project parameter follows that project's role assignments. Workspace parameters, and promoting to the workspace, need a workspace-level grant. Setting a value follows the entity that receives it, so a project editor can set a project or workflow value for a workspace parameter. The UI shows every action; an action you are not allowed to perform fails when you save. **Audit Trail.** Definition and value changes are recorded in the [Audit Trail](/docs/reference/audit-trail), including the value itself. Values are never treated as secrets. ## Chat Overcut chat can list definitions, create and edit them, set and remove values on any scope, and preview which values a workflow would use on a manual run. It can also insert `{{params.}}` references into workflow steps and agent instructions, checking that each key exists. Deleting a definition and **Promote to workspace** stay in the UI. See [Chat with Overcut](/docs/how-to/chat-with-overcut). ## Related * [Reuse a Workflow Across Repositories](/docs/quick-starts/reuse-a-workflow-across-repositories): an end-to-end walkthrough. * [Reuse Across Projects](/docs/concepts/reuse-across-projects): when to use a parameter, a Library resource, or a template. * [Workspace Library](/docs/reference/workspace-library): shared resources and templates. * [Vault](/docs/reference/vault): credentials that must stay hidden. * [Run Script](/docs/workflows/run-script): environment variables and `OC_PARAM_`. # Custom Events API Source: https://docs.overcut.ai/docs/reference/custom-events-api Full request and response contract for the Custom Events webhook endpoint: methods, auth, payload, query params, errors, and limits. This page is the dispatcher's wire-level reference for the Custom Events webhook. For setup walkthroughs and recipes, see [Custom Events (Integrations)](/docs/integrations/custom-events). For workflow-side filtering and run access, see [Custom Events in workflows](/docs/workflows/custom-events). ## Endpoint ``` POST https://workflow-dispatcher.overcut.ai/trigger-event/ GET https://workflow-dispatcher.overcut.ai/trigger-event/ ``` `` is an opaque, 32-byte random string. It identifies the Custom Event and, even on its own, acts as the baseline credential: anyone who has the URL can fire the event unless an additional auth header is required. The exact URL for your event is shown on the event detail page in **Custom Events → (event) → Webhook URL**. Reveal it with **Show** and copy it with **Copy**, or click **Example** to grab a complete curl snippet. | Method | Body | Query params | | ------ | ---------------- | ------------------------- | | `POST` | JSON, up to 1 MB | Optional | | `GET` | (none) | All data via query params | A successful call returns **`202 Accepted`** with `{"success":true,"eventId":""}` immediately. Trigger evaluation and workflow dispatch happen asynchronously: a 202 means "your event was accepted," not "a workflow has finished." ## Authentication The auth mode is set on the event itself, not per request. No auth header required. URL token is the only credential. Suitable for low-risk internal sources or prototypes. Standard `Authorization: Bearer ` header. The `Bearer` prefix is matched case-insensitively. The secret is whatever non-whitespace follows. ``` Authorization: Bearer 9bff…c11d ``` Any header name chosen at create time. The header name is matched case-insensitively; the value is compared after trimming whitespace. ``` X-API-Key: 9bff…c11d ``` Secrets are stored as SHA-256 hashes. The plaintext is shown one time only, in the **New secret** panel at create or rotate time. There is no API or UI to read it back. If lost, [rotate](/docs/integrations/custom-events#rotate-the-url-token-or-secret). Custom Events do not verify HMAC body signatures. TLS protects the transport and the Bearer / custom header value protects authenticity. If you need provider-native signatures (`X-Hub-Signature`, `Stripe-Signature`, etc.), use the [native integrations](/docs/integrations/overview) instead. ## Payload The request body is arbitrary JSON. Overcut does not validate its shape: workflow trigger conditions read whatever the sender sends. ```bash theme={"dark"} curl -X POST 'https://workflow-dispatcher.overcut.ai/trigger-event/' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "environment": "production", "status": "success", "service": { "name": "api" } }' ``` ### Size limit The body is capped at **1 MB**. Larger requests are rejected with `413 payload_too_large`. ### Query-string merge Every `key=value` pair on the URL (other than the reserved [`projectId`](#projectid) and [`lockKey`](#lockkey)) is merged into the payload as a top-level string field. This lets GET-only systems send data: ``` GET .../trigger-event/?environment=production&status=success ``` Body values win on conflict: if both the body and the query string set `environment`, the body value is kept. ### Well-known meta fields Four payload keys are dual-use: they shape how the workflow run appears in Overcut **and** remain available to trigger conditions under `payload.*`. | Key | Type | Sets | Default if absent | | -------------- | ------ | ------------------------------------ | ---------------------------------------------- | | `objectName` | string | The run's label in the runs list | the event's slug (e.g. `deployment_completed`) | | `objectNumber` | string | The run's object-number badge | empty | | `objectUrl` | string | The click-through link from the run | empty | | `actor` | string | The run's actor (displayed as a Bot) | none | Accepted in both body and query string. Body wins on conflict. Scalar values are coerced to strings (a JSON number `1234` becomes `"1234"`). Non-scalar shapes (arrays, objects) are ignored for lifting but still pass through under `payload`. ## Query parameters ### `projectId` Narrows the call to a single project. The project must exist in the event's workspace and be in the event's allowlist (or the event must be scoped to **All projects**). Reserved: never merged into `payload`. Omit to fan out: every project that allows the event receives an independent firing, evaluated against its own workflows. ### `lockKey` Opt-in serialization scope. Requests sharing the same `(event, lockKey)` pair run one at a time, and within a short dedupe window collapse into a single queued execution per workflow. Reserved: never merged into `payload`. Charset and length: `^[A-Za-z0-9_.\-:]{1,128}$`. Invalid values return `400 lockkey_invalid`. When `projectId` is also present, the lock scope folds in the project: two calls to **different** projects with the same `lockKey` run in parallel. ### Lock-key formula The full key the dispatcher uses internally: | Call shape | Lock key | | ----------------------------- | -------------------------------------------------------------- | | No `lockKey` | `custom::` (unique per call, never merges) | | `?lockKey=X` | `custom::X` | | `?projectId=P&lockKey=X` | `custom::P:X` | | `?projectId=P` (no `lockKey`) | `custom::P:` | The same key formula governs both serialization (one execution at a time per key) and dedupe-window merging (repeats collapse into one queued run per workflow). ## Responses ### Success ``` HTTP/1.1 202 Accepted Content-Type: application/json { "success": true, "eventId": "ckh3z9q8l0001abcd1234efgh" } ``` The `eventId` is the dispatcher's record of the inbound webhook (one row per accepted request). It is useful for correlating against logs but is not the workflow run ID: a single inbound event can produce zero, one, or many workflow runs depending on which workflows match. ### Error envelope Every error returns JSON with a stable `error` code and a human-readable `message`: ``` HTTP/1.1 403 Forbidden Content-Type: application/json { "error": "project_not_allowed", "message": "Project abc123 is not in this event's allowlist." } ``` ### Error codes | Code | HTTP | Cause | | --------------------- | ---- | ------------------------------------------------------------------------------------------- | | `token_invalid` | 404 | Unknown or revoked URL token. Also returned for deleted events. | | `auth_missing` | 401 | The required `Authorization` or custom header was not sent. | | `auth_invalid` | 401 | The secret did not match. | | `project_not_found` | 404 | `?projectId=` references a project that does not exist or belongs to a different workspace. | | `project_not_allowed` | 403 | `?projectId=` references a project that is not in the event's allowlist. | | `payload_too_large` | 413 | Request body exceeded 1 MB. | | `lockkey_invalid` | 400 | `?lockKey=` violates the charset or length rule. | | `internal_error` | 500 | Unexpected dispatcher failure. Safe to retry. | The dispatcher does **not** auto-retry: how to handle a non-2xx is up to the sending system's webhook framework. ## Operational notes * **No idempotency key.** There is no `Idempotency-Key` header today. To deduplicate retries from a flaky sender, have the sender pass a stable `?lockKey=` so repeats within the dedupe window collapse onto the same execution. * **No per-event rate limits.** Standard dispatcher abuse protection applies. There is no `Retry-After` contract. * **Fan-out.** One inbound webhook produces one dispatcher event row and (after fan-out and matching) zero or more workflow runs. * **Deleted events.** Deleted events return `token_invalid` (404). Past workflow runs for a deleted event remain in the history and continue to show the event's slug. ## Related Setup, auth modes, rotation, project scoping, and four ready-to-paste recipes. Pick an event in the trigger picker, filter on `payload.*`, and access event data in steps. The `trigger.*` and `trigger.payload.*` template variables exposed to downstream steps. Operator list, event merging, priority queuing, and the Custom Event lock-key formula. # Event Context Reference Source: https://docs.overcut.ai/docs/reference/event-context Complete reference of all event context properties available in Overcut workflows for building dynamic automations. Event context provides access to all information about the event that triggered your workflow. You can use this data throughout your workflow using template variables like `{{trigger.issue.title}}` or `{{trigger.repository.fullName}}`. All event properties are **platform-agnostic**: they work consistently whether your event comes from GitHub, GitLab, Jira, Bitbucket, Azure DevOps, or ClickUp. Overcut automatically normalizes platform-specific data into this standardized format. *** ## Template Variable Syntax Access event context properties using double curly braces: ```handlebars theme={"dark"} {{trigger.issue.title}} {{trigger.repository.fullName}} {{trigger.pullRequest.headBranch}} {{trigger.actor.login}} ``` You can use these template variables in: * Agent instructions * Action parameters * Conditional logic * Step outputs Templates have three namespaces: `trigger` for the event described on this page, `outputs` for previous step results, and `params` for [context parameters](/docs/reference/context-parameters), reusable values such as `{{params.base_branch}}` that each project, repository, workflow, orchestration, or agent can set. *** ## Inspect context for a run This page describes the context shape available to workflow templates. To inspect the actual values for one workflow run, open the run details and select **Context** to open the **Run Context** panel. The panel shows read-only JSON with the run's `trigger` data, `outputs` from completed steps, and the resolved context parameters under `params`. Use it to confirm the values behind template expressions such as `{{trigger.issue.title}}`, `{{outputs..}}`, and `{{params.}}`. Step outputs update while the run executes; parameters are frozen when the run is prepared. *** ## Base Event Properties These properties are available for **all event types**: ### Event Metadata The standardized event type that triggered the workflow (e.g., `issue_opened`, `pull_request_merged`, `mention`). **Example:** `{{trigger.eventType}}` Human-readable name of the object that triggered the event. **Example:** `{{trigger.triggerObjectName}}` Number or identifier of the triggering object (issue number, PR number, etc.). **Example:** `{{trigger.triggerObjectNumber}}` Direct URL to the triggering object in the source platform. **Example:** `{{trigger.triggerObjectUrl}}` ### Repository Context Repository name (e.g., `"blog-server"`). **Example:** `{{trigger.repository.name}}` Full repository name including owner (e.g., `"acme/blog-server"`). **Example:** `{{trigger.repository.fullName}}` Repository owner username or organization name. **Example:** `{{trigger.repository.owner}}` Clone URL for the repository. **Example:** `{{trigger.repository.url}}` Default branch name (e.g., `"main"`, `"master"`). **Example:** `{{trigger.repository.defaultBranch}}` Git provider name (e.g., `"github"`, `"gitlab"`, `"bitbucket"`). **Example:** `{{trigger.repository.provider}}` ### Actor Context The user or bot that triggered the event. Username or login of the actor. **Example:** `{{trigger.actor.login}}` Display name of the actor. **Example:** `{{trigger.actor.name}}` Email address of the actor (if available). **Example:** `{{trigger.actor.email}}` Type of actor: `"User"`, `"Bot"`, or `"Organization"`. **Example:** `{{trigger.actor.type}}` ### Organization Context Available when the repository belongs to an organization. Organization username or login. **Example:** `{{trigger.organization.login}}` Organization display name. **Example:** `{{trigger.organization.name}}` *** ## Issue Event Properties Available for issue-related events: `issue_opened`, `issue_closed`, `issue_edited`, `issue_assigned`, `issue_unassigned`, `issue_labeled`, `issue_unlabeled`, `issue_commented`. ### Core Issue Properties Issue number (unique within the repository). **Example:** `{{trigger.issue.number}}` Issue title. **Example:** `{{trigger.issue.title}}` **ClickUp**: For non-creation events, the task title may not be included in the webhook payload. `trigger.issue.title` may be empty in these cases. Current state of the issue: `"open"` or `"closed"`. **Example:** `{{trigger.issue.state}}` Issue description or body content. **Example:** `{{trigger.issue.body}}` Username of the issue author. **Example:** `{{trigger.issue.author}}` ### Issue Metadata Array of label names attached to the issue. **Example:** `{{trigger.issue.labels}}` or `{{trigger.issue.labels.[0]}}` for first label Array of usernames assigned to the issue. **Example:** `{{trigger.issue.assignees}}` or `{{trigger.issue.assignees.[0]}}` Milestone title if the issue is assigned to a milestone. **Example:** `{{trigger.issue.milestone}}` Normalized issue type coming from the source tracker (e.g., `"Bug"`, `"Task"`, `"Story"`). Use this to branch workflows by work item type without writing provider-specific logic. **Example:** `{{trigger.issue.workItemType}}` **GitHub** issues may return an empty string because the platform does not classify issues, while Jira, GitLab, and Azure DevOps provide their native issue types. Whether the issue is confidential. **Example:** `{{trigger.issue.confidential}}` **GitLab only** - This property is only available for GitLab issues. Returns `undefined` for other providers. ### Status Transition Fields Previous status name for a status transition. Use this value to target a specific change, such as moving from "Backlog" to "In Progress". **Example:** `{{trigger.statusFrom}}` **Provider availability:** Jira, Azure DevOps, and ClickUp include the previous status for state change events. Linear does not include the prior status, so `trigger.statusFrom` is undefined for Linear transitions. New status name after the transition. The value matches the label shown in your tracker. **Example:** `{{trigger.statusTo}}` **Provider availability:** Jira, Azure DevOps, Linear, and ClickUp supply the destination status for state change events. These fields are empty for issue events that only provide open or closed state without transition details. ### Issue Timestamps ISO timestamp when the issue was created. **Example:** `{{trigger.issue.createdAt}}` ISO timestamp when the issue was last updated. **Example:** `{{trigger.issue.updatedAt}}` ISO timestamp when the issue was closed (if applicable). **Example:** `{{trigger.issue.closedAt}}` *** ## Pull Request Event Properties Available for PR-related events: `pull_request_opened`, `pull_request_closed`, `pull_request_merged`, `pull_request_edited`, `pull_request_reviewed`, `pull_request_assigned`, `pull_request_unassigned`, `pull_request_labeled`, `pull_request_unlabeled`, `pull_request_commented`, `pull_request_review_commented`. Whether the event was caused by new commits being pushed to the pull request. * Always `true` for `pull_request_opened` events (initial commit set). * `true` for `pull_request_edited` **only** when the edit originates from new commits. * `false` for metadata-only changes such as title/body edits, label updates, or reviewer requests. Use this flag in trigger conditions to run workflows exclusively on code-changing updates. **GitLab and GitHub only** - This property is only available for GitLab and GitHub pull requests. Returns `false` for other providers. Normalized action describing the latest change detected on the pull request. Use it to filter workflows based on the specific action that occurred. **Available values:** * `opened` — the pull request was created. * `closed` — the pull request was closed without merging. * `merged` — the pull request was merged. * `reopened` — a previously closed pull request was reopened. * `ready_for_review` — the author (or maintainer) marked a draft pull request ready for review. * `converted_to_draft` — the pull request was converted to a draft. **Provider support:** `opened`, `closed`, and `merged` are available across all providers. `reopened` is supported on GitHub, GitLab, and Azure DevOps. Draft transitions (`ready_for_review`, `converted_to_draft`) are available on GitHub, GitLab, and Azure DevOps only. Bitbucket does not support draft pull requests. Normalized state of the pull request at the time of the event. Values are `opened`, `closed`, or `merged`, regardless of the underlying provider terminology. Use this field to distinguish lifecycle changes (closed vs. merged) while `trigger.prAction` captures the precise activity that fired the webhook. **Provider Differences**: While all core properties (number, title, state, branches, labels, assignees) are available across all providers, some advanced properties like change statistics, merge status, and reviewer information are provider-specific. Check the individual property notes below for availability. ### Core Pull Request Properties Pull request number. **Example:** `{{trigger.pullRequest.number}}` Pull request title. **Example:** `{{trigger.pullRequest.title}}` Current state: `"open"`, `"closed"`, or `"merged"`. **Example:** `{{trigger.pullRequest.state}}` Pull request description or body content. **Example:** `{{trigger.pullRequest.body}}` Username of the pull request author. **Example:** `{{trigger.pullRequest.author}}` ### Branch Information Target branch name (where the PR will be merged into). **Example:** `{{trigger.pullRequest.baseBranch}}` Source branch name (the branch with changes). **Example:** `{{trigger.pullRequest.headBranch}}` Base commit SHA. **Example:** `{{trigger.pullRequest.baseSha}}` **Not available on GitLab** - GitLab webhooks don't include the base SHA (would require an additional API call). Head commit SHA. **Example:** `{{trigger.pullRequest.headSha}}` Merge commit SHA (available after merge). **Example:** `{{trigger.pullRequest.mergeCommitSha}}` ### Pull Request Metadata Array of label names attached to the pull request. **Example:** `{{trigger.pullRequest.labels}}` Array of assignee usernames. **Example:** `{{trigger.pullRequest.assignees}}` Array of requested reviewer usernames. **Example:** `{{trigger.pullRequest.requestedReviewers}}` **GitHub only** - GitLab returns an empty array (no explicit reviewer request concept). Not available on Bitbucket or Azure DevOps. Milestone title if assigned. **Example:** `{{trigger.pullRequest.milestone}}` Whether the pull request is a draft. **Example:** `{{trigger.pullRequest.draft}}` ### Change Statistics **GitHub only** - Change statistics (additions, deletions, changedFiles) are only available for GitHub pull requests. Other providers don't include these metrics in their webhook payloads. Number of lines added. **Example:** `{{trigger.pullRequest.additions}}` Number of lines deleted. **Example:** `{{trigger.pullRequest.deletions}}` Number of files changed. **Example:** `{{trigger.pullRequest.changedFiles}}` ### Merge Status Whether the pull request can be merged (null if unknown). **Example:** `{{trigger.pullRequest.mergeable}}` **GitHub and GitLab only** - Not available on Bitbucket or Azure DevOps. Whether the pull request can be rebased (null if unknown). **Example:** `{{trigger.pullRequest.rebaseable}}` **GitHub only** - Not available on other providers. Whether auto-merge is enabled. **Example:** `{{trigger.pullRequest.autoMerge}}` **GitHub only** - Not available on other providers. ### Pull Request Timestamps ISO timestamp when the pull request was created. **Example:** `{{trigger.pullRequest.createdAt}}` ISO timestamp when the pull request was last updated. **Example:** `{{trigger.pullRequest.updatedAt}}` ISO timestamp when the pull request was closed (if applicable). **Example:** `{{trigger.pullRequest.closedAt}}` ISO timestamp when the pull request was merged (if applicable). **Example:** `{{trigger.pullRequest.mergedAt}}` *** ## CI Workflow Event Properties Available for CI workflow events: `ci_workflow_queued`, `ci_workflow_started`, `ci_workflow_completed`, `ci_workflow_failed`, `ci_workflow_cancelled`, `ci_workflow_timed_out`. Pull request context (`trigger.pullRequest.*`) is only populated when `trigger.ciWorkflow.isPullRequest` is `true`. The fields available vary by provider. See [Pull Request Context in CI Events](#pull-request-context-in-ci-events) for details. ### Run Identity Unique identifier for the CI run, as assigned by the provider. **Example:** `{{trigger.ciWorkflow.runId}}` Name of the pipeline or workflow that executed. **Example:** `{{trigger.ciWorkflow.workflowName}}` URL to view the run in the CI provider's UI. **Example:** `{{trigger.ciWorkflow.workflowUrl}}` Optional: not every provider includes a direct link in its webhook payload. ### Status and Outcome Normalized run status. One of: `Queued`, `InProgress`, `Succeeded`, `Failed`, `Cancelled`, `TimedOut`. **Example:** `{{trigger.ciWorkflow.status}}` Raw, provider-specific conclusion value (e.g., GitHub's `action_required` or GitLab's `manual`). Use `status` for cross-provider logic and `conclusion` when you need provider-level detail. **Example:** `{{trigger.ciWorkflow.conclusion}}` Optional: only present on terminal-state events (`ci_workflow_completed`, `ci_workflow_failed`, `ci_workflow_cancelled`, `ci_workflow_timed_out`). ### Source Context The branch that triggered the CI run. **Example:** `{{trigger.ciWorkflow.branch}}` The commit SHA that the CI run executed against. **Example:** `{{trigger.ciWorkflow.commitSha}}` Whether the CI run is associated with a pull request. When `true`, `trigger.pullRequest.*` fields are available. **Example:** `{{trigger.ciWorkflow.isPullRequest}}` Pull request number when the run is PR-associated. **Example:** `{{trigger.ciWorkflow.pullRequestId}}` Optional: only present when `trigger.ciWorkflow.isPullRequest` is `true`. ### Pull Request Context in CI Events When a CI run is associated with a pull request, `trigger.pullRequest.*` fields are populated, but what is available depends on the provider: * **GitHub Actions**: PR number and branch names are available; title is not included in the webhook payload. * **GitLab CI**: Full merge request data is only available on MR-triggered pipelines. Add a `merge_request_event` rule to your `.gitlab-ci.yml` to ensure MR context is sent. * **Azure DevOps**: PR ID and branch names are available; title is not included. * **Bitbucket Pipelines**: Full PR context including title is available. When available, these fields follow the same schema as [Pull Request Event Properties](#pull-request-event-properties) above. ### Timing ISO timestamp when the run was queued. **Example:** `{{trigger.ciWorkflow.queuedAt}}` Optional: not available on Azure DevOps. ISO timestamp when the run started executing. **Example:** `{{trigger.ciWorkflow.startedAt}}` Optional: not present for `ci_workflow_queued` events. ISO timestamp when the run finished. **Example:** `{{trigger.ciWorkflow.completedAt}}` Optional: only present on terminal-state events. Run duration in milliseconds. **Example:** `{{trigger.ciWorkflow.duration}}` Optional: only present on terminal-state events when both start and end times are known. ### Additional Fields Total number of jobs in the pipeline. **Example:** `{{trigger.ciWorkflow.jobCount}}` **GitLab only**: other providers do not include job count in their webhook payloads. *** ## Action-Specific Context These properties provide additional context about the specific action that triggered the event. ### Label Operations Available for `issue_labeled`, `issue_unlabeled`, `pull_request_labeled`, `pull_request_unlabeled` events. The `labelsAdded` / `labelsRemoved` arrays are also populated on `issue_edited` for providers without a discrete label event (see the Azure DevOps note below). The label that was added or removed. When several labels change at once this is the **first added** label only - use `trigger.labelsAdded` to see all of them. **Not supported on Azure DevOps or GitLab** - these providers deliver label changes as `issue_edited`; use `trigger.labelsAdded` / `trigger.labelsRemoved` instead. **Example:** `{{trigger.label}}` The action performed: `"added"` or `"removed"`. **Not supported on Azure DevOps or GitLab** - these providers deliver label changes as `issue_edited` (a single event can both add and remove labels), so this field is not set; use `trigger.labelsAdded` / `trigger.labelsRemoved` instead. **Example:** `{{trigger.labelAction}}` All labels added in this change. Match a specific one with the `contains` operator (e.g. `context.trigger.labelsAdded contains "ready-for-development"`). **Example:** `{{trigger.labelsAdded}}` All labels removed in this change. Counterpart to `trigger.labelsAdded`. **Not supported on Linear** - Linear's webhook does not include the names of removed labels, so this field is omitted for Linear label removals. **Example:** `{{trigger.labelsRemoved}}` **Provider support:** `trigger.label` and `trigger.labelAction` are populated only by providers that emit a discrete label event - **GitHub, Jira, Linear, and ClickUp**. **Azure DevOps** and **GitLab** deliver label changes as `issue_edited` (and a single ADO/GitLab event can add and remove labels at the same time), so `trigger.label`/`trigger.labelAction` are **not set**. Use `trigger.labelsAdded` / `trigger.labelsRemoved` instead - for example, trigger on **Issue edited** with a condition `context.trigger.labelsAdded contains " ### Assignee Operations Available for `issue_assigned`, `issue_unassigned`, `pull_request_assigned`, `pull_request_unassigned` events. Username of the assignee that was added or removed. **Example:** `{{trigger.assignee}}` The action performed: `"assigned"` or `"unassigned"`. **Example:** `{{trigger.assigneeAction}}` ### Milestone Operations The milestone that was added or removed. **Example:** `{{trigger.milestone}}` The action performed: `"added"` or `"removed"`. **Example:** `{{trigger.milestoneAction}}` ### Comment Operations Available for `issue_commented`, `pull_request_commented`, `pull_request_review_commented` events. Comment ID from the git provider. **Example:** `{{trigger.commentId}}` Username of the comment author. **Example:** `{{trigger.commentAuthor}}` Full content of the comment. **Example:** `{{trigger.commentBody}}` Where the comment was made: `"issue"` or `"pull_request"`. **Example:** `{{trigger.commentLocation}}` ISO timestamp when the comment was created. **Example:** `{{trigger.commentCreatedAt}}` ### Review Operations Available for `pull_request_reviewed` events. Username of the reviewer. **Example:** `{{trigger.reviewer}}` Review state: `"approved"`, `"changes_requested"`, `"commented"`, or `"dismissed"`. **Example:** `{{trigger.reviewState}}` Review action: `"submitted"`, `"edited"`, or `"dismissed"`. **Example:** `{{trigger.reviewAction}}` ### Mention Operations Available for `mention` events. Username of the user who mentioned the bot. **Example:** `{{trigger.mentionedBy}}` Where the mention occurred (e.g., `"issue"`, `"pull_request"`, `"comment"`). **Example:** `{{trigger.mentionLocation}}` The full message or content containing the mention. **Example:** `{{trigger.mentionContent}}` ### Slash Command Operations Available for `slash_command` events. The slash command that was used (e.g., `"/review"`). **Example:** `{{trigger.slashCommand}}` Whether the slash command was used with an @mention. **Example:** `{{trigger.slashCommandWithMention}}` *** ## Practical Examples ### Example 1: Accessing Issue Properties Use issue properties in an agent instruction: ```yaml theme={"dark"} - id: "analyze-issue" action: "agent.run" params: agentId: "triage-bot" instruction: | Review issue #{{trigger.issue.number}}: "{{trigger.issue.title}}" Issue details: - Author: @{{trigger.issue.author}} - State: {{trigger.issue.state}} - Labels: {{trigger.issue.labels}} - Created: {{trigger.issue.createdAt}} {{trigger.issue.body}} ``` ### Example 2: Clone PR Branch Use pull request branch information in git operations: ```yaml theme={"dark"} - id: "clone-pr-branch" action: "git.clone" params: repoFullName: "{{trigger.repository.fullName}}" branch: "{{trigger.pullRequest.headBranch}}" ``` ### Example 3: Conditional Logic Based on Event State Use Handlebars helpers for conditional logic: ```yaml theme={"dark"} - id: "context-aware-agent" action: "agent.run" params: instruction: | {{#if (eq trigger.issue.state "closed")}} This issue is already closed. Provide a summary of the resolution. {{else}} This issue is open. Analyze and provide recommendations. {{/if}} {{#if trigger.issue.labels}} Labels present: {{trigger.issue.labels}} {{else}} No labels assigned yet. {{/if}} ``` ### Example 4: Working with Arrays Access array elements and iterate: ```yaml theme={"dark"} - id: "check-assignees" action: "agent.run" params: instruction: | Issue assignees: {{#if trigger.issue.assignees}} {{#each trigger.issue.assignees}} - @{{this}} {{/each}} {{else}} No assignees yet. {{/if}} First label: {{trigger.issue.labels.[0]}} ``` ### Example 5: Mention the Original Author Reference the event author in responses: ```yaml theme={"dark"} - id: "respond-to-user" action: "agent.run" params: instruction: | @{{trigger.issue.author}}, I've analyzed your issue and here are my findings... ``` ### Example 6: Use Comment Context Access comment-specific properties: ```yaml theme={"dark"} - id: "process-comment" action: "agent.run" params: instruction: | Process comment by @{{trigger.commentAuthor}}: {{trigger.commentBody}} Respond in the {{trigger.commentLocation}} thread. ``` ### Example 7: Conditional Repository Selection Combine with conditional logic for dynamic behavior: ```yaml theme={"dark"} - id: "clone-code" action: "git.clone" params: repoFullName: | {{#if outputs.identify-repos.[0]}} {{outputs.identify-repos.[0].repoFullName}} {{else}} {{trigger.repository.fullName}} {{/if}} branch: "{{trigger.repository.defaultBranch}}" ``` ### Example 8: Filter by Actor Type Exclude bot-triggered events: ```yaml theme={"dark"} # In trigger conditions trigger: eventType: "issue_commented" conditions: - field: "context.actor.type" operator: "not_equals" value: "Bot" ``` ### Example 9: Run Workflow Only When Commits Are Added to a PR Use the trigger.commitAdded flag to avoid running expensive jobs on metadata-only changes: ```yaml theme={"dark"} trigger: eventType: "pull_request_edited" conditions: - field: "context.trigger.commitAdded" operator: "equals" value: true ``` In this setup, the workflow will execute when a pull request is opened or when new commits are pushed, but it will not run if the PR author only updates the title, description, labels, or other metadata. *** ## Custom Event Properties Workflows triggered by a [Custom Event](/docs/integrations/custom-events) receive the inbound webhook body and any query-string parameters under `trigger.payload.*`. The four well-known meta fields are also lifted into the standard `trigger.*` slots so they look like any other trigger in the runs list. ### Event Metadata Always `"custom_event"` for Custom Event triggers. Populated from the caller's `objectName` payload field. Falls back to the event's slug (for example, `deployment_completed`) when absent. **Example:** `{{trigger.triggerObjectName}}` → `"Deploy #1234 to production"` Populated from the caller's `objectNumber` payload field. Empty when absent. **Example:** `{{trigger.triggerObjectNumber}}` → `"1234"` Populated from the caller's `objectUrl` payload field. Used as the run's click-through link when present. **Example:** `{{trigger.triggerObjectUrl}}` → `"https://github.com/acme/api/actions/runs/1234"` Populated from the caller's `actor` payload field. `trigger.actor.type` is always `"Bot"` for Custom Events. **Example:** `{{trigger.actor.login}}` → `"deploy-bot"` ### Payload The full request body. Query-string parameters (other than the reserved `projectId` and `lockKey`) are merged in as top-level string fields. Body values win on conflict. **Example:** `{{trigger.payload.environment}}` → `"production"` Use dot notation for nested keys: `{{trigger.payload.service.region}}`. Missing intermediate keys evaluate to undefined without throwing. ### Custom Event Identifiers Internal ID of the Custom Event definition. The event's slug, e.g. `"deployment_completed"`. This is what trigger conditions match against. Set when the caller targeted a specific project via `?projectId=`. Undefined on workspace-wide fan-out. Set when the caller passed `?lockKey=`. Undefined otherwise. *** ## Template Helpers Overcut supports Handlebars helpers for advanced logic: ### Comparison Helpers * `{{#if (eq value1 value2)}}` - Equals * `{{#if (ne value1 value2)}}` - Not equals * `{{#if (gt value1 value2)}}` - Greater than * `{{#if (lt value1 value2)}}` - Less than * `{{#if (gte value1 value2)}}` - Greater than or equal * `{{#if (lte value1 value2)}}` - Less than or equal ### Logical Helpers * `{{#if (and condition1 condition2)}}` - Logical AND * `{{#if (or condition1 condition2)}}` - Logical OR * `{{#if (not condition)}}` - Logical NOT ### Iteration * `{{#each array}}...{{/each}}` - Iterate over arrays * `{{@index}}` - Current iteration index * `{{@first}}` / `{{@last}}` - First/last iteration flags *** ## Notes and Best Practices ### Platform Normalization All properties are automatically normalized from platform-specific formats. For example, GitHub's `pull_request` becomes `pullRequest`, and Jira's `key` becomes `number`. ### Property Availability Not all properties are available for all events. For example, `trigger.pullRequest` is only available for pull request events, and `trigger.issue` only for issue events. Optional properties may be `null` or `undefined` if not provided by the platform. ### Provider-Specific Properties While Overcut normalizes events across all platforms, some properties are only available from specific providers due to webhook payload limitations: **Issue Properties:** * `confidential` - GitLab only **Pull Request Properties:** * `additions`, `deletions`, `changedFiles` - GitHub only * `autoMerge`, `rebaseable` - GitHub only * `mergeable` - GitHub and GitLab only * `requestedReviewers` - GitHub only (GitLab returns empty array) * `baseSha` - Not available on GitLab **CI Workflow Properties:** * `jobCount` - GitLab only * `queuedAt` - Not available on Azure DevOps * `trigger.pullRequest.title` in CI events - Bitbucket only ### Array Access When accessing array elements, always check if the array exists first using `{{#if trigger.issue.labels}}` to avoid template rendering errors. ### Dynamic Workflows Combine event context with step outputs (`{{outputs.step-id.property}}`) for powerful dynamic workflows that adapt based on runtime data. *** ## Related Documentation Learn about trigger types and event normalization Understand workflow structure and template variables Use event context in agent instructions Clone repositories using trigger context # Interactive Sessions Source: https://docs.overcut.ai/docs/reference/interactive-sessions How interactive sessions work, comment routing behavior, and configuration options for ongoing conversations with agents. Interactive sessions enable ongoing conversations between users and agents, maintaining context across multiple comments without restarting workflows. For basic agent setup, see [Agent Session Action](/docs/workflows/agent-session) and [Agent Differences](/docs/workflows/agent-differences). *** ## How Sessions Work Comments route directly to active sessions instead of creating new workflows. Full conversation history maintained throughout the session. Sessions can be ended with keywords or interrupted by slash commands. Configurable duration limits prevent sessions from running indefinitely. ## Session vs Standard Workflows ### **Standard Workflow** Each mention or slash command creates a new workflow execution: ``` User: "@overcut review this" → New workflow starts (mention trigger) User: "What about line 45?" → No workflow triggered (plain comment) User: "@overcut /help" → New workflow starts (slash command) ``` ### **Interactive Session** One workflow handles multiple comments: ``` User: "@overcut review this" → Workflow starts, session becomes active User: "What about line 45?" → Routes to active session (plain comment) User: "/done" → Routes to session, triggers completion signal, ends ``` *** ## Comment Routing Rules When a comment or Slack thread reply is posted, Overcut routes live conversations before it evaluates new triggers: Is there a workflow run or interactive session currently live for this PR, issue, or Slack thread? If yes, the message continues the existing run or session. It does not start a duplicate workflow. If no live run or session exists, Overcut evaluates triggers normally and may start a new workflow. Slack thread replies can be evaluated as **Trigger Event** `thread reply` only in [registered Slack channels](/docs/integrations/slack) set to `Watch all messages`. An in-thread `@overcut` mention is a `mention` event, not a `thread reply` event. *** ## Session Configuration ### **Comment Handling Options** Interactive sessions provide two key configuration options that control how they respond to user comments: Controls whether the session accepts and processes new comments from users. When enabled, session waits for user replies after agent responses before proceeding. ### **Configuration Details** | Parameter | Description | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Listen To Comments` | Whether the session accepts new comments during execution. When false, the session will not accept new comments and will end when the agent completes its current step. | | `Keep Session Open For Comments` | Whether to pause and wait for user input after agent completes. When true, the session will wait for an additional time for user reply. | | `Max Duration (minutes)` | How long session stays active. When the session reaches the max duration, it will end and the flow will continue to the next step. | ## Session Termination Sessions end when any of these conditions are met: `maxDurationMinutes` timeout reached `/done` (ends session) or `/quit` (terminates workflow) Any other slash command terminates session and starts new workflow Starting a new session terminates the existing one ### **Manual Termination Commands** Two built-in commands provide direct session control: * **`/done`**: Completes the current session step gracefully * **`/quit`**: Terminates the entire workflow immediately ### **Slash Command Interruption** Other slash commands provide immediate user control: ``` User: "@overcut help with this bug" → Session starts User: "Can you explain the error?" → Routes to session User: "/review" → Session terminated, review starts ``` **What happens:** 1. Session receives termination signal 2. Session cleared from database (stops comment routing) 3. Agent gets 5 minutes to wrap up gracefully 4. New slash command workflow queues or starts *** ## Best Practices Match session duration to expected interaction length Use `/done` to end sessions or `/quit` to terminate workflows Expect users to use slash commands to change direction Design workflows that work well together when users switch between them ### **When to Use Sessions** **✅ Good for:** * Interactive help and support * Answering questions about code changes * Collaborative problem-solving * Expected back-and-forth conversation **❌ Not suitable for:** * Independent automation tasks * One-time analysis or reviews * Tasks that don't require follow-up *** ## FAQ Yes! Use `/done` or `/quit` commands, or any slash command to terminate gracefully. * **Comment events** (including mentions): Route to the active session * **Slack thread replies**: Continue the live run or session first. If no run or session is live, replies in registered channels set to `Watch all messages` can match workflows with **Trigger Event** set to `thread reply`. * **Slash commands**: Terminate the session and start new workflow * **Other events** (labels, PR opened): Create new workflows that queue normally Only one active execution can be active at a time. Yes! Sessions work consistently across GitHub, GitLab, Jira, Bitbucket, Azure DevOps, and registered Slack channels. *** ## Related Documentation Basic session setup and multi-agent coordination How triggers, queuing, and slash commands work When to use different agent action types Setting up and using slash command triggers # LLM Models Source: https://docs.overcut.ai/docs/reference/llm-models Connect your own LLM providers, configure custom models, and control which model each agent uses. Overcut ships with a set of system-managed models, but you can bring your own API keys (BYOK) to connect models from any supported provider. Custom models are configured once at the workspace level and can then be assigned to individual agents, workflows, or set as the workspace default. *** ## Overview LLM Models page showing configured provider cards and the Add LLM Model button Connect your existing API keys from OpenAI, Anthropic, Azure, AWS Bedrock, or OpenRouter. Assign a specific model to each agent: use a fast model for triage and a powerful model for code review. Set defaults at the workspace, workflow, or agent level. Agents inherit the closest configured default automatically. API keys are encrypted at rest and never exposed in the UI, logs, or to the LLM itself. *** ## Supported Providers | Provider | Config Type | Notes | | -------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | **OpenAI** | API key + model name | Supports optional gateway settings for proxies and compatible APIs | | **Azure OpenAI** | API key + endpoint + deployment | Standard Azure OpenAI Service. Supports extra static headers | | **Azure OpenAI (Responses API)** | API key or token + model + endpoint | Azure-native Responses API with full gateway settings | | **Anthropic** | API key or Claude subscription token + model | Supports Anthropic directly and Anthropic-compatible gateways that provide the `/v1/messages` API | | **AWS Bedrock** | Bedrock API key or IAM credentials + region + model | Supports a Bedrock model ID or inference-profile ID | | **OpenRouter** | API key + model name | Access 200+ models. Supports optional gateway settings | *** ## Creating a Custom Model Navigate to LLM Models in the main menu. Click the Add LLM Model button. Enter a model name (e.g. "Claude Sonnet for Production") and select a provider. Fill in the provider-specific configuration. Each provider requires different fields. For gateway-backed providers, configure endpoint, auth, and header settings only when your gateway requires them. See the Provider Configuration section below. Click Test Model next to Save Changes. Overcut checks the connection and detects what the model supports. See Testing a Model. Click Save Changes. Overcut encrypts your API key or token and stores the model together with its test result. It is now available for assignment. Once a model is created, the provider and model key cannot be changed. To switch providers, create a new model and reassign your agents. Use Edit Config on the model page to change credentials, endpoints, or the model ID within the same provider. *** ## Testing a Model Testing a model confirms that Overcut can reach it with your credentials and detects what it supports, so runs use the right features from the start. Click Test Model next to Save Changes when you create a model or edit its configuration, or on the page of any saved custom model. The test checks the connection first, then four capabilities: * **Tool calling**: Whether agents can use tools during a run. * **Vision**: Whether images can be sent to the model. * **Native PDF**: Whether PDF attachments can be sent as documents, or should be converted to text first. * **Prompt caching**: Whether the provider can reuse the shared prefix of each request. See Prompt caching. When the results look right, click Looks right and save. Overcut stores the detected capabilities with the model and enables each feature it supports: images go only to models with vision, PDFs go as documents or as extracted text, and prompt caching turns on where it is verified. Open a model at any time to see its result under Detected Capabilities. Each model shows a status of Tested, Test failed, or Not tested. If the connection fails, the dialog shows the provider's error so you can fix the configuration and test again. Changing any provider setting resets the status to Not tested until you test the new configuration. You can save a model without testing it. Overcut then falls back to assumptions based on the provider, the model name, and the Supports Vision setting. Testing replaces those assumptions with verified results. ### Vision support Until a model passes a test, the model page shows a Supports Vision toggle. It is off by default. Turn it on only when both the model and its configured endpoint accept images. After a successful test, the detected Vision result replaces the toggle. Enabling Supports Vision for an incompatible model or endpoint can cause requests with image content to fail. Test the model to detect vision support instead. ### Prompt caching Overcut handles prompt caching for you. The shared prefix of each request (tools and system prompt) is reused across turns, which lowers latency and cost. OpenAI and Azure OpenAI cache automatically on their side and need nothing from Overcut. Anthropic and AWS Bedrock require an explicit cache checkpoint in the request, and Overcut adds it automatically for Claude models on Anthropic, OpenRouter, and AWS Bedrock. Testing the model confirms that caching works with your configuration. A Supported result shows the verified method (Anthropic cache breakpoints or Bedrock Converse cache points), and Overcut uses that method for every run. For OpenAI and Azure OpenAI, the result is Not supported because no checkpoint is needed. *** ## Provider Configuration ### OpenAI Your OpenAI API key. The model identifier (e.g. gpt-4.1, gpt-4o, o3). Optional. Overrides the API endpoint for proxies, gateways, or OpenAI-compatible endpoints. For gateway authentication and header options, see Gateway and Custom Endpoint Settings. ### Azure OpenAI Your Azure OpenAI resource key. The Azure OpenAI resource URL (e.g. [https://your-resource.openai.azure.com](https://your-resource.openai.azure.com)). The name of the deployed model in your Azure resource. The Azure OpenAI API version (e.g. 2024-02-15-preview). For static gateway headers, see Gateway and Custom Endpoint Settings. ### Azure OpenAI (Responses API) Your Azure OpenAI key or the gateway token your endpoint expects. The model deployment name to use. Your Azure OpenAI resource endpoint with the /openai path (e.g. [https://your-resource.cognitiveservices.azure.com/openai](https://your-resource.cognitiveservices.azure.com/openai)). The API version (e.g. 2025-04-01-preview). Choose Yes to use the Responses API format, or No when your endpoint expects the non-Responses format. For gateway authentication and header options, see Gateway and Custom Endpoint Settings. ### Anthropic Your Anthropic API key from console.anthropic.com. Use this or a Claude Subscription Token, not both. A token generated by running claude setup-token. Usage is billed against your Claude subscription, and available models depend on your plan. Use this or an API Key, not both. Optional. The URL of an Anthropic-compatible gateway. The gateway must support the Anthropic /v1/messages API. OpenAI-compatible endpoints do not work. The Claude model ID (for example, claude-sonnet-4-5-20250929) or an alias such as sonnet, opus, or haiku. Optional. A model to use when the primary model is unavailable. An Anthropic model configured with only a Claude Subscription Token works with the Claude engine. The Overcut engine requires an Anthropic API Key. ### AWS Bedrock A Bedrock API key generated in the AWS console. When you provide this key, you can leave both IAM credential fields empty. Your AWS access key ID. Not needed when a Bedrock API Key is set; required together with Secret Access Key when using IAM credentials. Your AWS secret access key. Not needed when a Bedrock API Key is set; required together with Access Key ID when using IAM credentials. The AWS region where your Bedrock models are available (e.g. us-east-1). The Bedrock model ID or inference-profile ID (e.g. anthropic.claude-3-sonnet-20240229-v1:0). Provide either a Bedrock API Key or a complete Access Key ID and Secret Access Key pair. The Bedrock API Key takes precedence when both methods are populated. Validation fails if you provide only one IAM field or neither authentication method. ### OpenRouter Your OpenRouter API key. The OpenRouter model identifier, in provider/model format (e.g. anthropic/claude-sonnet-4, openai/gpt-4.1). Optional. Overrides the default OpenRouter endpoint when you use a compatible gateway. For gateway authentication and header options, see Gateway and Custom Endpoint Settings. *** ## Gateway and Custom Endpoint Settings Gateway settings appear only for providers that support OpenAI-compatible endpoints or static gateway headers. Use them when your provider traffic must pass through a proxy, API gateway, Azure API Management, or another OpenAI-compatible endpoint. | Field | Appears for | Use it when | | --------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Base URL** | OpenAI, OpenRouter, Azure OpenAI (Responses API) | You need to send requests to a proxy, gateway, custom endpoint, or compatible API instead of the provider's default endpoint. | | **Auth method** | OpenAI, OpenRouter, Azure OpenAI (Responses API) | Your gateway expects the API credential in a specific authentication header. | | **Custom auth header name** | OpenAI, OpenRouter, Azure OpenAI (Responses API) | You choose **Custom header** in **Auth method** and need to name the header that carries the credential. | | **Extra headers (JSON)** | OpenAI, OpenRouter, Azure OpenAI, Azure OpenAI (Responses API) | Your gateway requires static routing headers, tenant headers, or other fixed headers on every request. | | **Use Responses API** | Azure OpenAI (Responses API) | You need to choose whether the endpoint uses the Responses API format. | ### Auth method choices For OpenAI, OpenRouter, and Azure OpenAI (Responses API), choose the Auth method that matches your endpoint or gateway: * Bearer token (Authorization header): Sends the credential in the Authorization bearer header. This is the default choice for OpenAI-compatible endpoints. * api-key header: Sends the credential in the api-key header. Use this when Azure OpenAI or your gateway expects an api-key header. * Custom header: Sends the credential under the header you enter in Custom auth header name. When you choose Custom header, fill in Custom auth header name with the exact header name your gateway expects, such as x-api-key. Overcut requires this field when Auth method is Custom header. ### Extra headers (JSON) Use Extra headers (JSON) for static headers that should be sent with every request to the endpoint. The value must be a JSON object. Header names and header values must both be strings. ```json theme={"dark"} { "X-Tenant-Id": "acme", "X-Gateway-Route": "production" } ``` Do not use Extra headers (JSON) for the primary API credential when Auth method can represent it. Use Auth method and Custom auth header name for the credential header, then use Extra headers (JSON) for additional fixed headers. *** ## Assigning Models ### Per-Agent Each agent has a model selector in its settings. Choose a specific model or leave it on **Default Model** to inherit from the workflow or workspace. Navigate to Agent Roles and select an agent. Use the Model dropdown to pick a custom model or Default Model. ### Per-Workflow Set a workflow-level default in the Workflow Builder so all agents in that workflow inherit the same model unless they have their own override. Click the canvas background to open Workflow Settings. Select a model from the Default LLM Model dropdown. ### Per-Workspace Set a workspace-wide default in **Account → Settings**. All workflows and agents that don't specify their own model will use this default. *** ## Inactive Models Set a model to inactive when you want to stop it from being selected without losing its configuration. Inactive models remain visible in LLM Models so you can review them, edit their details, or reactivate them: open the model and use the Inactive control to switch it back to Active. Inactive models are hidden anywhere a model is selected: agent Model dropdowns, workflow Default LLM Model dropdowns, and the workspace default model picker. *** ## Model Cascade Model resolution depends on the execution engine. Both engines use the first configured value in their cascade, but the Claude engine has its own workspace default and eligibility requirements. ### Overcut engine cascade 1. **Coordinator override**: The model selected for the coordinator in an Agent Session step. This override applies only to the coordinator, not its sub-agents. 2. **Agent model**: The agent's own model selection. 3. **Workflow default**: The **Default LLM Model** set in Workflow Settings. 4. **Workspace default**: The **Default LLM Model** set in Account → Settings. 5. **System default**: Overcut's managed default model. ### Claude engine cascade 1. **Coordinator override**: The model selected for the coordinator in an Agent Session step. 2. **Agent model**: The agent's own model selection. 3. **Workflow default**: The **Default LLM Model** set in Workflow Settings. 4. **Workspace Claude default**: The **Default Claude Engine Model** set in Account → Settings. 5. **Main workspace default**: The **Default LLM Model** set in Account → Settings. **Default Claude Engine Model** is separate from **Default LLM Model**, so you can choose a Claude-compatible workspace default without changing the default for the Overcut engine. You can also clear **Default Claude Engine Model** to let the Claude cascade continue to the main workspace default. The Claude engine validates the first model resolved by this order. It does not skip an invalid candidate and continue down the cascade. The resolved model must be active, owned by the current workspace, non-system, and provided by Anthropic or AWS Bedrock. If it does not meet every requirement, the step fails. The Claude engine does not fall back to a system model. For a step-by-step walkthrough of configuring defaults at each level, see the Default Model Configuration guide. *** ## Overcut vs. Claude Overcut supports two execution engines. In the Workflow Builder, use Execution Engine to select Overcut or Claude for an agent step. This section covers model eligibility only. For what else changes between engines (tools, sub-agents, recovery, usage reporting), see [Execution Engines](/docs/concepts/execution-engines). ### Overcut The default engine supports every provider listed on this page. * **Model selection**: Uses agent, workflow, and workspace model settings, with a system model available as the final fallback. * **Providers**: OpenAI, Azure OpenAI, Anthropic, AWS Bedrock, and OpenRouter. * **Credentials and billing**: Custom models use your provider credentials and billing. System models use Overcut billing. ### Claude The Claude engine runs the Claude Agent SDK with credentials from a compatible custom LLM Model. * **Eligible models**: The resolved model must be active, owned by the current workspace, non-system, and provided by Anthropic or AWS Bedrock. * **Model selection**: Uses the Claude-specific cascade above, including the separate Default Claude Engine Model. The first resolved candidate must be eligible. * **Credentials and billing**: Usage goes through the Anthropic or AWS credentials saved on the selected model. * **No system fallback**: The Claude engine cannot use system models. If the cascade does not resolve an eligible custom model, the step fails and you must select or configure one. Provider compatibility differs by engine. OpenAI, Azure OpenAI, and OpenRouter models can run with the Overcut engine, but not the Claude engine. An Anthropic model that uses only a Claude Subscription Token can run only with the Claude engine. Both engines support MCP Servers, the same agent roles, and the same Overcut tools for ticketing, pull requests, and Git operations. *** ## Security * API keys are **encrypted at rest** and never returned through the UI or API. * Decrypting a model's configuration requires the `llmModel.readEncryptedConfig` permission. * System models (managed by Overcut) cannot be edited or deleted by workspace users. *** ## Next Steps * **[Default Model Configuration](/docs/quick-starts/default-model-configuration)**: Step-by-step guide for setting workspace, workflow, and coordinator defaults * **[Claude Agent SDK Integration](/docs/integrations/claude-agent-sdk)**: Detailed setup guide for the Claude Code engine * **[Vault](/docs/reference/vault)**: Manage secrets used across your workspace * **[Core Building Blocks](/docs/building-blocks)**: Understand how agents, actions, and triggers connect # Machine Sizes Source: https://docs.overcut.ai/docs/reference/machine-sizes Choose the CPU and memory available to workflow execution machines, and understand how each size affects credit consumption per run. Every workflow run executes on a dedicated machine. The machine size determines the CPU and memory available to that machine, and how many credits the run consumes. Workflows that run heavy builds, large test suites, or memory-intensive analysis benefit from a larger size, while most workflows run comfortably on the default. ## Available sizes | Size | Resources for workspace commands | Credit cost | | -------- | -------------------------------- | ------------- | | Standard | 2 vCPU / 1.5 GB | 1 credit/run | | Large | 4 vCPU / 3 GB | 2 credits/run | | X-Large | 8 vCPU / 6 GB | 4 credits/run | **Default:** Standard. Workflows without an explicit machine size run on Standard. ## Setting the machine size Machine size is configured per workflow in [Workflow Metadata](/docs/how-to/workflow-builder#machine-size): 1. Open the workflow in Workflow Builder 2. Click the canvas background to show workflow metadata 3. Under **Settings**, choose a **Machine Size** The selector shows each size with its credit cost, so you can weigh resources against consumption before committing. Leave the setting unset to use the default. ## Credits and billing Credit cost is charged per run, based on the workflow's machine size. A workflow set to Large consumes twice the credits of the same workflow on Standard, and X-Large consumes four times as much. Each run records the machine size it executed on. You can see it in the workflow runs list and in the run summary panel, alongside token usage. Machine size affects the compute credits of the execution machine, not LLM token usage. To analyze token consumption, see [Token Usage Analytics](/docs/workflows/token-usage-analytics). ## Choosing a size Choose a larger size when the workflow: * Runs heavy build or test commands * Installs large dependency trees * Analyzes large repositories or monorepos * Uses memory-intensive steps Keep the default for lightweight triage, comment, routing, or status workflows, especially when the workflow does not run expensive local commands. Start on Standard and move up only if runs fail or slow down on resource-heavy steps. Larger sizes multiply the credit cost of every run, including the ones that never needed the extra headroom. ## Related documentation * [Workflow Metadata](/docs/how-to/workflow-builder): all workflow-level settings, including machine size * [Token Usage Analytics](/docs/workflows/token-usage-analytics): analyze LLM token consumption per run # MCP Servers Source: https://docs.overcut.ai/docs/reference/mcp-servers Extend your agents with external tools by connecting Model Context Protocol (MCP) servers to your Overcut workspace. MCP Servers let you give Overcut agents access to tools provided by external [Model Context Protocol](https://modelcontextprotocol.io/) servers. Use MCP when you want to connect third-party systems that do not have native Overcut support, such as observability platforms, design tools, internal services, or custom APIs. For first-class providers such as GitHub, GitLab, Azure DevOps, Jira, Linear, ClickUp, and Slack, start with native workspace integrations and use MCP as a supplemental or fallback option when you need extra capabilities. The fastest way to add an MCP server is through the MCP Catalog: browse common servers and install with guided setup. Use the manual flow below when you need a custom configuration. If you are connecting GitHub, GitLab, Azure DevOps, Jira, Linear, ClickUp, or Slack, start with the Integrations overview to choose the native workspace integration path first. This page covers workspace MCP servers, which extend agents running inside Overcut. To connect an external coding agent to your Overcut account through the hosted MCP gateway, follow [Connect Your Coding Agent](/docs/get-started/connect-your-coding-agent). *** ## When to use MCP Use MCP when you want to: * Connect a third-party system that Overcut does not support as a native workspace integration * Give agents access to external tools such as Datadog, Figma, Notion, Confluence, or internal services * Add a supplemental capability alongside a native integration, such as a provider-specific tool that is not part of Overcut's built-in workflow * Keep a fallback path available for a supported provider when your team needs a different external tool surface **Examples:** * Use the GitHub workspace integration to connect repositories and pull requests, then add an MCP server for a separate GitHub-adjacent tool if your workflow needs it. * Use the Jira workspace integration for ticket operations, then add an MCP server for Confluence so agents can reference internal documentation. * Use MCP for a monitoring platform such as Datadog when you want agents to investigate logs or incidents in a system that is not connected through a native workspace integration. ## Overview Browse and install pre-configured servers from the open-source catalog with one click. Support for local stdio servers (command-based) and remote SSE/HTTP servers (URL-based). Restrict which tools an agent can use from a server to keep execution focused and secure. Assign specific MCP servers to individual agents so each agent gets exactly the tools it needs. *** ## Creating a Custom MCP Server Use this flow when you need to configure a server that isn't in the [MCP Catalog](/docs/quick-starts/mcp-catalog), or when you need full control over the configuration. Navigate to MCP Servers in the workspace sidebar. Click Add MCP Server to open the catalog, then click Add Custom. Provide a JSON configuration object. The config must contain **either** a command field (for a local stdio server) **or** a url field (for a remote SSE/HTTP server), not both. See the Configuration Reference below for details. In the Secrets section, click Add Secret to attach one or more secrets from the Vault. In the Allowed Tools section, add tool names to restrict which tools agents can call. Leave the list empty to allow all tools exposed by the server. Toggle the server to Active. Only active servers can be assigned to agents. *** ## Managing MCP Server Secrets Secrets attached to an MCP server become available to the server whenever an agent uses it. This keeps credentials scoped to the MCP integration while letting you reuse secrets across servers. A project MCP server can attach secrets from the Project Vault or the Library Vault; a Workspace Library MCP server can attach Library secrets only. Go to MCP Servers, then select the server you want to update. In the Secrets section, click Add Secret to attach one or more secrets. Save your changes to apply the updates. Remove secrets you no longer want the server to use, then save the server. Removing a secret from the server does not delete it from the Vault. Attach only the secrets the MCP server needs. This keeps access focused and easier to audit. *** ## Configuration Reference ### Stdio: Local Command Use this mode to run an MCP server as a local process. Overcut starts the command and communicates with it over standard input/output. ```json theme={"dark"} { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"], "env": { "NODE_ENV": "production" } } ``` The executable to run (e.g. npx, python, node). Arguments passed to the command. Environment variables set for the process. Use placeholders to reference secrets stored in the Vault. They are resolved at runtime and never exposed to the LLM. ### SSE / HTTP: Remote Server Use this mode to connect to a remote MCP server over HTTP with Server-Sent Events. If you host the server yourself and it sits behind a firewall, allow Overcut Cloud's [egress IP range](/docs/network-allowlisting) so agents can reach it. ```json theme={"dark"} { "url": "https://mcp.example.com/sse", "headers": { "Authorization": "Bearer ${MY_API_KEY}" } } ``` The full URL of the remote MCP server endpoint. HTTP headers sent with every request. Use placeholders to reference secrets stored in the Vault. The configuration must contain **exactly one** of command or url. Including both or neither will fail validation. *** ## Allowed Tools By default, an MCP server exposes all of its tools to any agent it's assigned to. You can limit this by building an **Allowed Tools** list using the add/remove editor on the server's detail page. When the allowed tools list has entries, agents can only call the tools in that list, even if the server advertises additional tools. This is useful for: * **Reducing scope**: give an agent access to only the tools it needs * **Security**: prevent agents from calling sensitive or destructive tools * **Clarity**: keep the agent's tool set focused on the task at hand If the list is empty, the server is unrestricted. Agents can use all tools the server provides. When installing from the MCP Catalog, you choose tools during the install flow. The catalog pre-selects a recommended set that you can adjust before installation. *** ## Assigning MCP Servers to Agents MCP servers are assigned on a per-agent basis. Each agent can have zero or more MCP servers, and each server can be shared across multiple agents. Agents in any project can also attach MCP servers from the [Workspace Library](/docs/reference/workspace-library); they appear in the picker with a **Library** badge and stay managed in the Library. To share a project MCP server with every project, promote its secrets to the Library first, then select **Promote to library** on the server's page. A Library MCP server cannot be deleted while an agent still uses it. Navigate to Agent Roles and select the agent you want to configure. Scroll to the MCP Servers section in the agent settings. Click Add MCP Server, search for available servers, and select one or more to assign. Only active servers appear in the list. Click the remove icon next to any assigned server to unassign it from the agent. *** ## How It Works at Runtime When a workflow step runs an agent that has MCP servers assigned: 1. **Bootstrap**: Overcut connects to each assigned MCP server and discovers the tools it exposes. Each server has a 30-second timeout to complete its bootstrap. 2. **Tool Registration**: Discovered tools are registered with a namespaced format: `mcp____`. This prevents name collisions when multiple servers expose tools with the same name. 3. **Execution**: The agent can call any registered MCP tool as part of its task. Tool calls are routed to the appropriate MCP server transparently. 4. **Filtering**: If the allowed tools list has entries, only matching tools are registered. If the list is empty, all tools from that server are available. *** ## Examples The examples below are provided as a starting point. Package names, environment variables, and endpoints may change over time. Refer to each provider's official MCP documentation for the most up-to-date configuration. The examples use placeholders for credentials. Store the actual values in the Vault and make sure each secret is assigned to the relevant agent or marked as available for all executions. ### Design: Figma Connect a Figma MCP server so agents can read design files, inspect components, and extract design tokens during code generation or review workflows. ```json theme={"dark"} { "command": "npx", "args": ["-y", "figma-developer-mcp", "--stdio"], "env": { "FIGMA_API_KEY": "${FIGMA_API_KEY}" } } ``` ### Logs: Datadog Give agents access to your Datadog logs and metrics so they can investigate incidents, correlate errors with code changes, or summarize recent alerts. ```json theme={"dark"} { "command": "npx", "args": ["-y", "@winor30/mcp-server-datadog"], "env": { "DATADOG_API_KEY": "${DATADOG_API_KEY}", "DATADOG_APP_KEY": "${DATADOG_APP_KEY}", "DATADOG_SITE": "datadoghq.com" } } ``` ### Logs: Coralogix Connect to Coralogix so agents can query logs, search for error patterns, and pull observability data into their analysis. Replace `{region}` with your Coralogix region (e.g. `us2`, `eu1`, `ap1`). ```json theme={"dark"} { "command": "npx", "args": [ "mcp-remote", "https://api.{region}.coralogix.com/mgmt/api/v1/mcp", "--header", "Authorization: Bearer ${CORALOGIX_API_KEY}" ] } ``` ### Documentation: Notion Let agents read and search your team's Notion workspace to pull in product specs, runbooks, or architecture docs when working on tasks. ```json theme={"dark"} { "command": "npx", "args": ["-y", "@notionhq/notion-mcp-server"], "env": { "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ${NOTION_API_KEY}\",\"Notion-Version\":\"2022-06-28\"}" } } ``` ### Documentation: Confluence Connect to Confluence so agents can look up internal documentation, ADRs, or team knowledge bases during code review or implementation. ```json theme={"dark"} { "command": "npx", "args": ["-y", "@aashari/mcp-server-atlassian-confluence"], "env": { "ATLASSIAN_SITE_NAME": "your-team", "ATLASSIAN_USER_EMAIL": "${CONFLUENCE_USER_EMAIL}", "ATLASSIAN_API_TOKEN": "${CONFLUENCE_API_TOKEN}" } } ``` *** ## Splitting a Server Across Agents A single MCP server often exposes both read and write tools. Rather than giving every agent full access, you can create **multiple server entries** pointing to the same underlying service, each with a different allowed tools list, and assign each one to the appropriate agent. This pattern gives you fine-grained control over what each agent can do, reducing the risk of unintended actions and keeping agents focused. **Example (Figma with read-only vs. full access):** | Server Name | Allowed Tools | Assigned To | | ------------ | ---------------------------------------- | -------------------------- | | `figma-read` | `get_file, get_comments, get_components` | Code Reviewer, Tech Writer | | `figma-full` | *(empty, all tools)* | Senior Developer | Both servers use the same Figma MCP configuration, but the Code Reviewer and Tech Writer can only read designs, while the Senior Developer has full access. This is especially important for servers that expose destructive operations (delete, update, post). Limit write access to the agents that actually need it. *** ## Best Practices ### Naming Use clear, descriptive server names that indicate the service or capability (e.g. `figma-read`, `datadog-logs`, `notion-docs`). When splitting a server across agents, include the access level in the name (e.g. `figma-read` vs. `figma-full`). ### Security * Store credentials in the [Vault](/docs/reference/vault) and reference them with `${VAR_NAME}` placeholders. Never hardcode secrets in MCP server configs. * Use allowed tools lists to limit the blast radius of agent actions, especially on servers with write or delete capabilities. * Split servers across agents to enforce least-privilege access: give each agent only the tools it needs. ### Scope * Assign only the MCP servers an agent actually needs. Fewer tools means faster bootstrap and more focused agent behavior. * Too many tools can defocus the agent and lead to slower, less accurate results. When in doubt, use an allowed tools list to narrow the set. *** ## Next Steps * **[Vault](/docs/reference/vault)**: Store and manage the secrets referenced in MCP server configurations * **[Workspace Library](/docs/reference/workspace-library)**: Share an MCP server with every project * **[Agent Run Action](/docs/workflows/agent-run)**: Execute a single agent with MCP tools * **[Agent Session Action](/docs/workflows/agent-session)**: Coordinate multiple agents, each with their own MCP servers * **[MCP Catalog](/docs/quick-starts/mcp-catalog)**: Browse and install pre-configured servers from the open-source catalog * **[Core Building Blocks](/docs/building-blocks)**: Understand how agents, actions, and triggers connect # Scratchpad Tools Source: https://docs.overcut.ai/docs/reference/scratchpad-tools Collect, organize, and share agent notes using named scratchpads. Scratchpad tools give agents a shared workspace for collecting notes, drafting content, and coordinating findings before taking action. Instead of writing a comment or review immediately, agents can accumulate results in a scratchpad and publish only when ready. ## Available tools | Tool | Parameters | Description | | ------------------- | ----------------- | ------------------------------------------------------- | | `write_scratchpad` | `name`, `content` | Create or overwrite a scratchpad. | | `append_scratchpad` | `name`, `content` | Append to a scratchpad. Creates it if it doesn't exist. | | `read_scratchpad` | `name` | Read the full content of a scratchpad. | | `list_scratchpads` | *(none)* | List all scratchpad names in the current workspace. | ### Naming rules Names support letters, numbers, hyphens, and underscores only. No slashes or spaces. Examples: `findings`, `review-summary`, `security_notes`, `chunk-1` ## Collecting results before publishing Agents often need to gather information across multiple files, tests, or analysis steps before producing a final output. Scratchpads act as a staging area: agents write findings as they go, then read the scratchpad to compose a polished comment, review, or ticket update. ```yaml theme={"dark"} steps: - id: "code-review" name: "Code Review" action: "agent.run" params: agentId: "code-reviewer" instruction: | Review the PR changes. As you analyze each file, append your findings to the scratchpad "review-notes" using append_scratchpad. When done, read the scratchpad and post a single, organized review comment on the PR. ``` This pattern avoids scattered, incremental comments. The agent builds up a complete picture first, then publishes once. ## Multi-agent collaboration In an `agent.session`, multiple agents share the same scratchpads. Each agent can append its findings independently, and the coordinator can read everything to produce a consolidated result. Use `append_scratchpad` when multiple agents contribute: it prevents agents from overwriting each other's work. ```yaml theme={"dark"} steps: - id: "review-session" name: "Review Session" action: "agent.session" params: goal: "Review the PR for security, performance, and correctness" agentIds: ["security-expert", "performance-expert", "code-reviewer"] instruction: | Each agent: append your findings to the scratchpad "review-findings". When all reviews are done, read the scratchpad and post a combined review comment. ``` ## Passing context between workflow steps Scratchpads persist across steps within a workflow run. An agent in one step can write a scratchpad that agents in later steps read, without relying on `{{outputs}}` templates. This is useful when: * The data is too large or structured for step output templates * Multiple steps need to build up a shared document incrementally * You want a later step to consume structured content directly ```yaml theme={"dark"} steps: - id: "analyze" name: "Analyze Codebase" action: "agent.run" params: agentId: "senior-developer" instruction: | Analyze the repository structure and write a summary to the scratchpad "analysis". Include key components, dependencies, and areas of concern. - id: "review" name: "Review Session" action: "agent.session" params: goal: "Review the code based on the analysis" agentIds: ["code-reviewer", "security-expert"] instruction: | Read the scratchpad "analysis" to understand the codebase context. Append your findings to "review-findings". When done, read "review-findings" and post a summary comment on the PR. ``` ## Content format Scratchpads store plain text, but you control the format by instructing the agent what to write. You can use Markdown, JSON, JSONL, or any other text format that fits your workflow. For example, instruct an agent to append one JSON line per finding to make it easy for a later step to parse, or use Markdown for a human-readable draft. ## When to use scratchpads vs step outputs | | Scratchpads | Step outputs (`{{outputs}}`) | | -------------------- | --------------------------------------------------------------------- | ------------------------------------- | | **Best for** | Drafting content, multi-agent collaboration, large or structured data | Simple values passed to the next step | | **Format** | Any text (Markdown, JSON, JSONL, plain text) | String from agent response | | **Multiple writers** | Yes, via `append_scratchpad` | No: one step, one output | | **Readable by** | Any agent in any step | Template expressions in step params | # Skills Source: https://docs.overcut.ai/docs/reference/skills Discover repository-backed skills, add them to your project, and assign them to the right agents. Agent Skills help your team reuse guidance from your repositories instead of repeating the same instructions across multiple agents. You can browse available skills from connected repositories, preview a skill before adding it, manage all registered skills in one place, and assign the right skills to the right agents. This page covers repository-backed project skills. When you task Overcut via chat, it can also load built-in task skills on its own during the conversation; see [Chat with Overcut](/docs/how-to/chat-with-overcut). Overcut is compatible with the open [Agent Skills spec](https://github.com/anthropics/skills), so you can bring any existing `SKILL.md`-formatted skills straight from your connected code repositories or from a skills marketplace. No rewriting or re-authoring required. Skills are discovered from repositories that are already connected to your workspace. If you do not see the repository you need, start with the [Repositories guide](/docs/get-started/repositories). ## What Agent Skills are A skill is a reusable set of instructions stored in one of your connected repositories. After you add a skill to a project, it can be assigned to that project's agents. A skill added to the [Workspace Library](/docs/reference/workspace-library) can be assigned to agents in every project. Skills are useful when you want to: * Reuse team standards without copying the same instructions into multiple agents * Keep guidance close to the repository or codebase it supports * Give agents focused expertise for specific frameworks, services, or workflows * Maintain one list of approved skills per project, or one shared list in the Workspace Library ## Discover skills from connected repositories Overcut shows available skills from repositories that are connected to your workspace. This gives your team a single place to find reusable guidance that is already packaged in the repositories you use every day. The Skills page with a left rail of project skills and a selected PR Description skill showing General, Source, Metadata, and SKILL.md Content sections. In your project, go to **Skills** to view the project-level list of registered skills and discover new ones. Select **Add Skill** to open **Add Skills from Repository**, where you can browse skills from your connected repositories. In **Search**, use **Repository** to choose the repository that contains the skills you want to use. Select **Scan for skills**. Overcut checks the selected repository and shows discovered skills in **Results**. Use **Select Skills** to choose the skills you want to add. You can add one skill or multiple skills in the same flow. Overcut hides skills that are already added to the project, so you cannot add duplicates. If every discovered skill is already in the project, the **Results** area tells you so. If your team manages many repositories, skills discovery helps you find reusable guidance without manually searching each repository. ## Preview a skill before adding it Before you register a skill in the project, you can preview its instructions to confirm that it matches your team's needs. When you open a skill preview, you can review: * The skill name * The connected repository it comes from * The repository path for the skill * The skill instructions from `SKILL.md` When you select multiple skills, **Skill Details** shows one skill at a time and indicates how many are selected, so you can review each skill without losing your selection. Previewing skills helps you validate each skill's purpose, scope, and wording before making it available to agents. ## Add one or more skills to the project Once you find skills you want to use, add them to the project's **Skills** area. This creates a shared project-level list that your team can review and manage over time. Use **Skill Details** to confirm the selected skills are the right fit for the project before you add them. Select **Add Skill** when one skill is selected. When more than one skill is selected, the primary action changes to **Add N Skills**. After you add multiple skills, Overcut returns you to the project **Skills** list. Use the list to review the saved skills and check where each skill comes from, including its connected repository, source path, and any pinned reference if one is shown. The project-level **Skills** list gives your team a central place to review which reusable instructions the project owns. Skills from the Workspace Library do not appear here; they appear in the agent's skill picker with a **Library** badge. To share a project skill with every project, select **Promote to library** on its page. ## Enable, disable, and remove skills You can manage each project skill without editing the source repository directly. Keep a skill available for assignment to agents when your team wants to use it. Temporarily prevent a skill from being assigned while keeping it in the project list for later use. Delete a skill from the project's **Skills** area when it is no longer needed. Disabling a skill is useful when you want to pause its availability without losing track of it. Removing a skill is better when you want to clean up the project list entirely. Only enabled project and Library skills are available when you assign skills to an agent. A Library skill cannot be deleted while an agent still uses it. ## Assign skills to agents After a skill has been added to the project or the Workspace Library and left enabled, you can assign it to individual agents. This lets each agent use the specific guidance it needs without overloading every agent with the same instructions. Go to the agent you want to update in your project configuration. In the agent's **Skills** section, choose from the enabled project skills. Update the agent later to remove skills that are no longer relevant. This workflow works well alongside your agent's base role and other configuration. To learn more about agent setup, see [Base Agent Types](/docs/reference/base-agents). ## Related documentation * [Workspace Library](/docs/reference/workspace-library) * [Repositories](/docs/get-started/repositories) * [Product Overview](/docs/get-started/product-overview) * [Base Agent Types](/docs/reference/base-agents) # Agent Tools Reference Source: https://docs.overcut.ai/docs/reference/tools Complete reference for all built-in agent tools, organized by category. Built-in tools give agents a unified, provider-agnostic interface for interacting with your connected systems. You write agent instructions using generic language ("create a ticket", "open a pull request", "read the file") and Overcut routes each operation to the correct provider based on your workspace integrations. **Provider-agnostic by design.** A tool like **Create Ticket** works across Jira, Linear, ClickUp, GitHub Issues, and GitLab Issues without any changes to your agent instructions. Overcut handles the provider-specific details automatically. Built-in tools work through your connected workspace integrations for supported providers. If you are deciding how to connect a system, start with the Integrations overview. If you need external tools or third-party systems beyond native integrations, use MCP Servers. Each [base agent type](/docs/reference/base-agents) ships with a default set of tools. You can extend any agent by selecting additional tools, and with the **Custom** base type you choose every tool from scratch. Tools are assigned per agent in **Agent Roles** → agent settings. The **Name** column shows the tool's identifier as the agent knows it. You can reference it directly in instructions when needed. For example: *"use `read_file` to inspect the config before making changes"*. Beyond the tools listed here, agents also receive [scratchpad tools](/docs/reference/scratchpad-tools) and memory tools automatically. These are injected at runtime and are not part of the per-agent tool selection. *** ## Attachment content Ticket and pull request attachment tools can return usable content from supported files. Agents can read that content as part of the tool result, then use it as context for planning, answering questions, drafting changes, or reviewing work. ### Supported attachment content | Attachment type | What agents can use | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Text files | Readable text content when the file can be decoded. | | Images | Image attachments are available as images for workflows that can use image input. If image text is needed, provide a text-based source when possible. | | `.docx` files | Readable extracted text or markdown-like content from the document. | | `.xlsx` files | CSV-like text for each included sheet. | | `.pdf` files | Native document input for eligible Anthropic-backed workflows. Other providers and fallback cases use extracted text when available. | | Unsupported files | A notice that the file type is not supported instead of useful extracted text. | | Unreadable files | A notice when the file cannot be read or is malformed. | | No-text files | A notice when no useful text can be extracted, including scanned or image-only PDFs. | Attach focused source documents when possible. Smaller, text-based files help agents receive the most relevant attachment context within extraction limits and reduce the chance that content is truncated or omitted. ### Extraction limits and notices Attachment content is subject to limits so tool results stay usable: * Up to 50,000 extracted characters are included per attachment. * Up to 150,000 extracted attachment characters are included per tool result. * `.xlsx` files include up to 20 sheets and 500 rows per sheet. * Anthropic native PDF handling supports up to 3 native PDFs or 15 MB of raw PDF bytes per tool result. After that, PDFs fall back to extracted text when available. If extracted content is too large, the tool result may truncate or omit some attachment content. Agents still receive notices that explain why content was unavailable when a file is scanned or image-only, malformed, unsupported, unreadable, or has no useful text. UTF-8 filenames are preserved in attachment results, including filenames written in Hebrew. *** ## File System File system tools operate on repositories that have been cloned via the [`git.clone`](/docs/workflows/git-clone) action. | Tool | Name | Description | | -------------------- | ------------------ | ------------------------------------------------------------------------- | | **Read File** | `read_file` | Reads the content of a file. | | **Write File** | `write_file` | Creates or overwrites a file with new content. | | **Edit File** | `edit_file` | Applies targeted edits to an existing file without rewriting it entirely. | | **Append File** | `append_file` | Appends content to the end of an existing file. | | **Delete File** | `delete_file` | Deletes a file from the repository. | | **Create Directory** | `create_directory` | Creates a new directory in the repository. | | **List Directory** | `list_dir` | Lists the files and directories at a given path. | *** ## Code Utilities Code utility tools help agents understand and navigate codebases. They operate on cloned repositories. | Tool | Name | Description | | ----------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Search Code** | `code_search` | Searches for an exact string or pattern across all files in the repository. | | **Semantic Code Search** | `semantic_code_search` | Searches code by meaning rather than exact text, useful for finding relevant logic even when the wording varies. Requires [repository indexing](/docs/repositories/repository-indexing) to be enabled for the repository. | | **Execute Terminal Commands** | `run_terminal_cmd` | Runs terminal commands in the cloned repository (e.g., build scripts, test runners, linters). | | **Explore Codebase** | `explore_codebase` | Runs an internal exploration sub-agent to deeply analyze a specific aspect of the codebase, returning a structured summary. Useful for understanding unfamiliar areas of a large repository. | *** ## Tickets and Issues Ticket tools connect to your issue tracking integrations. The same instructions work across **Jira**, **Linear**, **ClickUp**, **GitHub Issues**, **GitLab Issues**, and **Azure DevOps**: the agent uses generic ticket language and Overcut maps it to the active provider. | Tool | Name | Description | | ---------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **Create Ticket** | `create_ticket` | Creates a new ticket or issue with title, description, and metadata. | | **Update Ticket** | `update_ticket` | Updates an existing ticket's fields (title, description, status, assignee, etc.). | | **Read Ticket** | `read_ticket` | Reads the full details of a specific ticket, including linked relationships when the provider exposes them. | | **List Tickets** | `list_tickets` | Lists tickets matching a query or filter (project, status, assignee, label, etc.). | | **Add Comment to Ticket** | `add_comment_to_ticket` | Adds a new comment to a ticket. | | **Update Comment on Ticket** | `update_comment_on_ticket` | Edits an existing comment on a ticket. | | **Get Ticket Attachments** | `get_ticket_attachments` | Retrieves file attachments from a ticket, including supported [attachment content](#attachment-content) when available. | | **Link Tickets** | `link_tickets` | Creates a typed link between two tickets on the same provider (for example, blocks or relates to). | | **Unlink Tickets** | `unlink_tickets` | Removes an existing link from a ticket. | | **Get Ticket Metadata** | `get_ticket_metadata` | Discovers provider-defined options such as available relationship (link) types, labels, and statuses before creating a link. | ### Linked ticket relationships On supported ticket providers, agents can work with linked relationships between tickets as part of normal ticket operations. This helps agents connect related bugs, follow-up work, blockers, and dependencies without leaving Overcut. Agents can: * Create linked relationships between tickets on providers that support them * Remove linked relationships when they are no longer accurate * Read existing linked relationships from tickets and use them as context when reasoning about related work * Inspect the relationship types a provider offers before attempting to create a link Relationship types are **provider-specific**. Overcut does not apply one universal set of relationship names across every integration. Before creating a linked relationship, agents can inspect the available relationship types for the connected provider and use one that matches that provider's rules. Cross-project linking also depends on the connected provider. If the provider allows tickets in different projects, spaces, or teams to be linked, agents can create those links through Overcut. If the provider restricts linking to the same project or repository, Overcut follows that behavior. See the [integration overview](/docs/integrations/overview) for the full ticket provider list, then review your provider page for setup details and support expectations such as project scope, status behavior, and link availability. ### Provider support expectations Typed ticket relationships are available only on providers that expose them through Overcut's native ticketing surface. Support differs by integration: * **Jira**: supports provider-defined relationship types, linked ticket reads, and cross-project linking when Jira allows it * **Linear**: supports provider-defined relationship types and linked ticket reads * **ClickUp**: supports link creation, link removal, and linked ticket reads. ClickUp uses a single provider-defined link option rather than a broader set of typed relationships * **GitLab**: supports provider-defined relationship types, linked ticket reads, and cross-project linking when GitLab allows it * **Azure DevOps**: supports provider-defined relationship types, linked ticket reads, and cross-project linking when Azure DevOps allows it * **GitHub Issues**: does not support typed ticket links through Overcut's native ticketing surface * **Bitbucket**: does not support typed ticket links through Overcut's native ticketing surface For provider-specific guidance, see [Jira](/docs/integrations/jira), [Linear](/docs/integrations/linear), [ClickUp](/docs/integrations/clickup), [GitLab](/docs/integrations/gitlab), [Azure DevOps](/docs/integrations/azure-devops), [GitHub](/docs/integrations/github), and [Bitbucket](/docs/integrations/bitbucket). *** ## Pull Requests Pull request tools connect to your source control integrations. They work across **GitHub**, **GitLab**, **Bitbucket**, and **Azure DevOps** through the same unified interface. | Tool | Name | Description | | ---------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Create Pull Request** | `create_pull_request` | Opens a new pull request with title, description, and branch information. | | **Read Pull Request** | `read_pull_request` | Reads the full details of a pull request including description, status, and labels. | | **Update Pull Request** | `update_pull_request` | Updates a pull request's title, description, labels, or other metadata. | | **List Pull Requests** | `list_pull_requests` | Lists pull requests matching a filter (status, author, branch, label, etc.). | | **Merge Pull Request** | `merge_pull_request` | Merges an approved pull request. | | **Close Pull Request** | `close_pull_request` | Closes a pull request without merging. | | **Add Comment to Pull Request** | `add_comment_to_pull_request` | Posts a general comment on a pull request. | | **Update Comment on Pull Request** | `update_comment_on_pull_request` | Edits an existing general comment on a pull request. | | **Get Pull Request Attachments** | `get_pull_request_attachments` | Retrieves file attachments from a pull request, including supported [attachment content](#attachment-content) when available. | *** ## Code Review Code review tools enable structured, line-level review feedback on pull requests. They are supported on **GitHub**, **GitLab**, **Bitbucket**, and **Azure DevOps**. | Tool | Name | Description | | -------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------- | | **Get Pull Request Diff** | `get_pull_request_diff` | Fetches the full code diff for a pull request. | | **Get Pull Request Diff Line Numbers** | `get_pull_request_diff_line_numbers` | Fetches the diff with explicit line number annotations, used for precise inline review placement. | | **Add Review Comment** | `add_pull_request_review_thread` | Adds an inline review comment on a specific line or hunk in a pull request diff. | | **Reply to Review Comment** | `add_pull_request_review_thread_reply` | Replies to an existing inline review thread. | | **Submit Review** | `submit_review` | Submits a completed review with an overall verdict (approve, request changes, or comment). | *** ## CI/CD CI/CD tools let agents monitor and interact with your continuous integration pipelines. They work with **GitHub Actions**, **GitLab CI**, **Bitbucket Pipelines**, and **Azure Pipelines**. | Tool | Name | Description | | ---------------------- | -------------------- | ----------------------------------------------------------------- | | **List PR CI Runs** | `list_pr_ci_runs` | Lists all CI workflow runs associated with a pull request. | | **Get CI Run Details** | `get_ci_run_details` | Retrieves details about a specific CI run: status, steps, timing. | | **Get CI Run Logs** | `get_ci_run_logs` | Fetches the full log output for a CI run. | | **Get CI Job Logs** | `get_ci_job_logs` | Fetches the log output for a specific job within a CI run. | | **Retry CI Workflow** | `retry_ci_workflow` | Triggers a retry of a failed CI workflow run. | *** ## Chat Channels Slack messaging tools let agents post, read, edit, and react in any active Slack channel registered to the current project, on any run: message-triggered, scheduled, manual, or Git-triggered. Tools are assigned per agent. For channel registration and how the agent picks a destination channel and thread, see [Slack integration](/docs/integrations/slack#what-agents-can-do-in-a-slack-channel). | Tool | Name | Description | | ------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------ | | **Post Channel Message** | `post_channel_message` | Posts a message in a registered channel, either at the channel root or in a thread. | | **Read Channel Messages** | `read_channel_messages` | Reads recent messages from a registered channel so the agent can understand context before responding. | | **Edit Channel Message** | `edit_channel_message` | Edits a message the agent (or workflow) previously posted. | | **Add Reaction** | `add_channel_message_reaction` | Adds an emoji reaction to a message in a registered channel. | | **Remove Reaction** | `remove_channel_message_reaction` | Removes an emoji reaction the agent previously added. | *** ## Automatically Injected Tools The following tools are automatically available to every agent regardless of which tools are selected. They cannot be added or removed manually. | Tool | Name | Description | | --------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Write Scratchpad** | `write_scratchpad` | Creates or overwrites a named scratchpad. | | **Append Scratchpad** | `append_scratchpad` | Appends content to a named scratchpad. | | **Read Scratchpad** | `read_scratchpad` | Reads the content of a named scratchpad. | | **List Scratchpads** | `list_scratchpads` | Lists all scratchpad names in the current run. | | **Memory Write** | `memory_write` | Writes a persistent memory entry, available in future runs. | | **Memory Recall** | `memory_recall` | Fetches the full content of a memory by ID. Agents see memory titles injected into their prompt and call `memory_recall` to pull in the ones that look relevant. Calls to this tool count toward the memory's use count, which feeds back into how the memory is weighted over time. | | **Update Status** | `update_status` | Sends a real-time status update visible in the Overcut UI during execution. | See [Scratchpad Tools](/docs/reference/scratchpad-tools) for full scratchpad documentation. *** ## Extending agents with MCP tools In addition to the built-in tools above, you can connect [MCP Servers](/docs/reference/mcp-servers) to give agents access to external tools: web search, databases, third-party APIs, and more. MCP extends agent capabilities with third-party systems and custom tools. For first-class providers that Overcut supports through workspace integrations, MCP is a supplemental or fallback option rather than a replacement for the native connection path. MCP tools appear alongside built-in tools in the agent tool list and are configured per agent in the MCP Servers section. Browse pre-configured servers in the [MCP Catalog](/docs/quick-starts/mcp-catalog). # Advanced Trigger Execution Source: https://docs.overcut.ai/docs/reference/trigger-execution Understanding multiple triggers, event merging, priority queuing, and slash command behavior in Overcut workflows. Advanced reference for how Overcut manages multiple triggers, prevents conflicts, and handles complex execution scenarios. For basic trigger setup, see [Triggers](/docs/workflows/triggers) and [Workflow Execution Control](/docs/workflows/workflow-execution-control). *** ## Multiple Trigger Behavior Any `@overcut` mention triggers ALL workflows with mention trigger type. Each slash command triggers only its specific workflow and can terminate active agent steps. All workflows for the same PR/issue run one at a time, ordered by priority. Multiple triggers of the same queued workflow merge into a single execution. ## Key Concepts ### **Trigger Specificity** * **Mention (`@overcut`)**: Triggers ALL mention workflows regardless of text after mention * **Slash Command (`/review`)**: Triggers only the specific workflow registered for that command * **Event Triggers**: Each workflow has one primary trigger type (e.g., `pull_request_opened`) ### **Slash Command Termination** Slash commands have special power to interrupt active work: Active agent steps (both `agent.run` and `agent.session`) receive termination signal Agents get 5 minutes to complete current operation before stopping Active sessions are cleared immediately and stop receiving new comments Slash command workflow queues or starts normally **Example:** ``` User: "@overcut help with this bug" → Session starts User: "Can you explain line 45?" → Routes to session User: "/review" → Terminates session, starts review ``` *** ## Parallel Execution & Locking ### **Resource-Based Locking** Overcut ensures workflows don't conflict by locking execution per resource: Only one workflow runs per issue/PR at a time to prevent conflicts Different issues/PRs can run workflows simultaneously ### **How Locking Works** **Same Resource = Sequential Execution:** ```yaml theme={"dark"} # All workflows for PR #123 run one at a time PR #123 opened → Starts immediately Comment on PR #123 → Queued (waits for first to finish) Label on PR #123 → Queued (waits in line) Review on PR #123 → Queued (waits in line) ``` **Different Resources = Parallel Execution:** ```yaml theme={"dark"} # These run simultaneously PR #123 workflow ✅ Running Issue #456 workflow ✅ Running PR #789 workflow ✅ Running ``` *** ## Queue Management & Deduplication ### **Intelligent Event Merging** When the same workflow is triggered multiple times while queued, events automatically merge to prevent redundant executions: System checks if the same workflow is already queued for the same lock key New trigger merges with existing queued workflow instead of creating duplicate ### **Priority-Based Processing** Queued workflows are processed by priority, then first-in-first-out: | Priority | Description | Processing Order | | ------------- | ------------------ | ---------------- | | `1` (High) | Critical workflows | Processed first | | `5` (Default) | Standard workflows | Default priority | | `10` (Low) | Background tasks | Processed last | ### **Automatic Deduplication** When the same workflow is triggered multiple times while queued, events automatically merge: ```yaml theme={"dark"} # Example: Auto-triage workflow with issue_labeled trigger 10:01 - Label "bug" added → Execution starts (running) 10:02 - Label "critical" added → Queued (first still running) 10:03 - Label "security" added → Merged with queued execution 10:05 - First completes → Queued execution runs with all labels ``` *** ## Advanced Queue Features ### **Delayed Execution** Workflows can be configured with delays to batch rapid events: ```yaml theme={"dark"} name: "Batch Comment Analysis" trigger: type: "issue_commented" settings: delaySeconds: 30 # Wait 30 seconds before processing steps: - name: "analyze-comments" type: "agent" instruction: "Analyze recent comment activity" ``` **Benefits:** * Batches rapid-fire events (multiple comments, labels) * Reduces redundant executions * Allows time for related events to merge ### Priority Configuration Control execution order with priority settings (1-100 scale): | Priority | Use Case | Example | | --------- | ------------------ | --------------------------------- | | **1-3** | Critical workflows | Security scans, incident response | | **4-6** | Normal workflows | Code reviews, standard automation | | **7-100** | Background tasks | Documentation, metrics collection | ```yaml theme={"dark"} name: "Security Scan" priority: 1 # Runs first trigger: type: "pull_request_opened" ``` ### Multiple Mention Workflows If you have multiple workflows with `mention` trigger, **all** will be triggered by any `@overcut` mention: ```yaml theme={"dark"} # Both triggered by "@overcut help me" - name: "Quick Help" (priority: 5) - name: "Full Analysis" (priority: 8) ``` **Solution**: Use slash commands for specificity: * `/help` → triggers only Quick Help * `/analyze` → triggers only Full Analysis ### Event Sequence Example ``` 10:01 - PR opened → "Initial Review" starts (priority: 5) 10:02 - Label "security" → "Security Scan" queued (priority: 1) 10:03 - Comment "@overcut" → "Help" queued (priority: 5) 10:05 - Initial Review done → Security Scan starts (highest priority) 10:07 - Security Scan done → Help starts ``` *** ## Custom Event Lock Keys [Custom Events](/docs/integrations/custom-events) share the same dispatcher queue and merging behavior as built-in triggers, but the caller controls the lock scope via the optional `?lockKey=` query parameter. | Caller URL | Lock key the dispatcher uses | | ----------------------------- | -------------------------------------------------------------- | | No `lockKey` | `custom::` (unique per call, never merges) | | `?lockKey=X` | `custom::X` | | `?projectId=P&lockKey=X` | `custom::P:X` | | `?projectId=P` (no `lockKey`) | `custom::P:` | Two implications: * Two calls to **different** projects with the same `lockKey` run in parallel: the project ID is folded into the key. * When `projectId` is omitted (workspace-wide fan-out from a single inbound call), the matched workflows across all allowed projects serialize together under the shared scope, because they represent a single real-world occurrence. `lockKey` must match `^[A-Za-z0-9_.\-:]{1,128}$`. Invalid values return `400 lockkey_invalid` from the dispatcher. *** ## Best Practices Reserve 1-3 for critical workflows, use default (5) for most cases. Expect users to use slash commands to change direction mid-workflow. Trust automatic event merging to reduce redundant executions. Use slash commands for specific actions, mentions for general help. *** ## FAQ Yes! Sequential execution only applies to the same PR or issue. Different resources can have workflows running simultaneously. Only when a workflow is **queued** (waiting to run), not while it's **running**. If workflow A is running and triggered twice more, the second trigger queues and the third merges with it. You can terminate agent steps using either comments or UI controls: **Via Comments:** * **`/done`**: Completes the current agent session step and continues to the next workflow step * **`/quit`**: Terminates the entire workflow immediately **Via UI (Execution Logs):** * **Complete Step** button: Requests the agent to complete and return results ASAP * **Quit Workflow** button: Terminates all running steps and marks the workflow as canceled Comment commands are processed immediately before the agent receives them, while UI buttons send termination requests to the running agent. * **Mentions (`@overcut`)**: Trigger all mention workflows, route to active sessions * **Slash commands (`/review`)**: Trigger specific workflow, terminate active agent steps *** ## Related Documentation Session behavior and comment routing mechanics Setting up and using slash command triggers Trigger types and basic configuration Resource locking and queue management # Vault Source: https://docs.overcut.ai/docs/reference/vault Store project and Library secrets like API keys, tokens, and credentials for use in workflows, agents, and MCP servers. The Vault is Overcut's built-in secrets manager for credentials: API keys, tokens, passwords, and connection strings used by workflows, agents, and MCP servers. Values are encrypted at rest and injected as environment variables when workflows execute. Secrets are never exposed to the LLM, only to the agent's sandbox environment. Each project has its own **Project Vault** at `Project → Project Settings → Project Vault`. The [Workspace Library](/docs/reference/workspace-library) has a **Library Vault** for secrets that several projects share. LLM provider keys are not vault secrets; configure them on each model under [LLM Models](/docs/reference/llm-models). *** ## Overview Secret values are encrypted before being stored. They cannot be read back through the UI or API, only updated or deleted. Assign secrets to specific workflows, agents, and MCP servers, or make them available globally for all executions. Secrets are injected as environment variables at runtime. Reference them in MCP server configs using syntax. Secret values are never sent to the AI model. They exist only in the execution sandbox as environment variables. *** ## Creating a Secret Open the project, then go to Project Settings → Project Vault. Click New Secret and enter a name and value. Secret names must start with an uppercase letter and contain only uppercase letters, numbers, and underscores. For example: API\_KEY, GITHUB\_TOKEN, DB\_PASSWORD\_PROD. Toggle Available for All Executions to make the secret accessible to every workflow and agent automatically. When disabled, you must explicitly assign the secret to specific workflows or agents. Secret values have a maximum size of 10KB. Once created, the name cannot be changed, only the value can be updated. *** ## Assigning Secrets Secrets can be scoped in two ways: ### Global Availability Toggle **Available for All Executions** on a secret to inject it into every workflow run in the project automatically. Use this for shared credentials that most workflows need, such as a third-party API key used across multiple MCP servers. On a Library secret the same toggle applies to every run in every project, and its tag reads **Available for All Executions in All Projects**. ### Per-Workflow, Per-Agent, and Per-MCP Server For secrets that should only be available to specific workflows, agents, or MCP servers: Open the workflow settings, scroll to the Secrets section, and add the secrets this workflow needs. Open the agent settings, scroll to the Secrets section, and add the secrets this agent needs. Open the MCP server settings, scroll to the Secrets section, and attach the secrets this server needs. At runtime, Overcut merges secrets from all four sources (global secrets, workflow-assigned secrets, agent-assigned secrets, and MCP server-assigned secrets) and injects them into the execution environment. *** ## Referencing Secrets Use the `${VAR_NAME}` syntax to reference vault secrets in MCP server configurations. At runtime, Overcut replaces each placeholder with the actual secret value. **Example MCP server config referencing vault secrets:** ```json theme={"dark"} { "command": "npx", "args": ["-y", "figma-developer-mcp", "--stdio"], "env": { "FIGMA_API_KEY": "${FIGMA_API_KEY}" } } ``` When this MCP server starts, `${FIGMA_API_KEY}` is replaced with the decrypted value from the vault. The LLM never sees the actual key, only the tool interface exposed by the MCP server. Make sure the secret is either set to Available for All Executions or explicitly assigned to the MCP server (or the workflow/agent that uses it). Otherwise the placeholder will not resolve. *** ## Project Vault and Library Vault A project's agents, MCP servers, and workflows can attach secrets from the Project Vault and from the Library Vault; Library secrets carry a **Library** badge in the picker. A Library MCP server or agent can attach Library secrets only. At run time Overcut collects secrets from both vaults, and a project secret with the same name as a Library secret wins in that project's runs. The project secret's row shows **Overrides the library value in this project's runs**. To share a project secret with every project, select **Promote to library** on its row. The value is not re-entered and existing assignments keep working. See [Workspace Library](/docs/reference/workspace-library#library-vault-and-shared-secrets) for promotion order and the all-executions warning. *** ## Context parameters and Vault secrets Use a [context parameter](/docs/reference/context-parameters) for visible, reusable plain-text configuration such as a base branch, a reviewer list, or naming conventions. Context parameter values appear in prompts and run logs. Use the Vault for anything that must stay hidden. Never place a credential in a context parameter, a prompt, or script output. Vault values are hidden from the model, but printing an environment variable from a script writes it to the run log. *** ## Security Model ### Encryption at Rest All secret values are encrypted before being written to the database. Decryption only happens at execution time through an internal, authenticated endpoint. ### No Read-Back Secret values cannot be read back through the UI or API. The vault only tells you whether a value exists (`hasValue`). To change a secret, you enter the new value; you cannot view the current one. ### Audit Trail Every vault operation (create, update, delete, toggle availability) is logged with the secret name (never the value), project ID, and the user who performed the action. Use [Audit Trail](/docs/reference/audit-trail) to review secret-change events and understand why sensitive values may be redacted or omitted from event details. ### LLM Isolation Secrets are injected as environment variables into the agent's sandbox process. The AI model interacts with tools and APIs through those processes but never receives the secret values in its prompt or context. ### Output Filtering Secret values are automatically filtered from tool outputs before they reach the model. If a tool accidentally returns a response containing a secret value, Overcut redacts it so the secret is never exposed in the conversation or logs. *** ## Best Practices * **Use the vault for all credentials**: never place API keys, tokens, or passwords in MCP server configs, agent instructions, or context parameters. * **Prefer per-workflow/per-agent assignment** over global availability when a secret is only needed by a few workflows. This follows the principle of least privilege. * **Use descriptive names** that make it clear what the secret is for: `DATADOG_API_KEY` is better than `KEY_1`. * **Rotate secrets** by updating the value in the vault. All workflows and MCP servers referencing that secret will pick up the new value on their next execution. No config changes needed. *** ## Next Steps * **[Multi-Project Workspaces](/docs/concepts/multi-project-workspaces)**: where the Project Vault fits in the workspace-vs-project boundary. * **[MCP Servers](/docs/reference/mcp-servers)**: connect external tools to your agents and reference vault secrets in their configuration. * **[Workspace Library](/docs/reference/workspace-library)**: the Library Vault and how shared secrets resolve. * **[Context Parameters](/docs/reference/context-parameters)**: plain-text values that are safe to show in prompts. * **[Core Building Blocks](/docs/building-blocks)**: understand how agents, actions, and triggers connect. # Workflow Version History Source: https://docs.overcut.ai/docs/reference/workflow-history Review published versions and drafts, compare changes side-by-side, and restore earlier definitions into your working copy. ## Overview The Version History viewer lets you explore every change ever made to a workflow. It lists **published versions** (the definitions that power automated and manual executions) alongside your **current draft**, the auto-saved working copy that has not yet been published. From the viewer you can: * See when each version and draft was created, and who saved it. * Switch between versions to inspect their full YAML definitions. * Compare any two versions (or the draft) using the **Compare** toggles: Previous vs. Selected, Latest vs. Selected, or Draft vs. Selected. * Restore a previous version into your working copy. * Publish the draft when you are ready, or discard it if the changes are no longer needed. ## Viewing drafts and versions 1. Open the workflow in **Workflow Builder**. 2. Click **View Version History** in the action bar. 3. The list shows: * **Draft**: your auto-saved, unpublished edits. Appears at the top with a "Draft" badge and a relative timestamp so you can confirm when the last auto-save occurred. * **Published versions**: ordered chronologically with the most recent at the top. Each entry displays the commit message, author, and timestamp. Selecting any row opens its metadata panel and preview on the right, so you always know which version the diff viewer is referencing before you compare or restore. Drafts remain local to the workflow until you publish. They do not impact scheduled or trigger-based runs. ## Comparing versions with diff The viewer supports interactive diffs so you can see exactly what changed between any two versions. Use the **Compare** dropdown to pick **Previous vs. Selected**, **Latest vs. Selected**, or **Draft vs. Selected**. The default highlights changes between the selected version and its immediate predecessor so you can step through history quickly. The diff viewer uses synchronized scrolling so both panes stay aligned. Added lines appear highlighted in green; removed lines appear in red, making it easy to spot prompt tweaks, parameter changes, or connector updates. The diff viewer is read-only. To make additional edits, close Version History and continue working in the builder; your changes will update the Draft entry automatically. ## Restoring previous versions If a recently published change introduces issues, or if you simply prefer an older definition, you can restore it into the working copy. Click the version in the list to load its details. Confirm the action in the modal. The chosen version becomes the new Draft while leaving the original published entry intact for future reference and audit trails. After restoration, return to the builder to validate, tweak if necessary, and **Publish** to make it the active version. Restoring does not automatically publish the version. Automated executions will **continue using the last published version** until you publish the new draft. ## Best practices * **Review before you run.** Always verify the draft's diff against the latest published version to confirm expected changes. * **Publish intentionally.** Provide clear commit messages when publishing so teammates understand why a change was made. * **Discard stale drafts.** If a draft lingers and is no longer relevant, discard it to avoid confusion. * **Use restore for quick rollbacks.** Instead of re-editing, restore a known-good version and publish it to roll back fast. ## Related documentation * [Workflow Versioning](/docs/workflows/workflow-versioning): draft lifecycle, finding unpublished changes, and publish/discard flow * [Workflow Metadata](/docs/how-to/workflow-builder): configure workflow settings in the builder # Workspace Library Source: https://docs.overcut.ai/docs/reference/workspace-library Share agents, MCP servers, skills, and secrets across every project, and install workflow and orchestration templates as project-owned copies. Every workspace has one **Workspace Library**: a shared place for the agents, MCP servers, skills, and secrets that more than one project needs, and for the workflow and orchestration templates that projects install. Projects attach Library resources by reference, so a change in the Library reaches every project at once. Templates are copied, so each project owns what it installs. Open the Library from the sidebar project picker. It sits below the project list, next to **New project**. Inside, the sidebar shows **MCP Servers**, **Skills**, **Agent Roles**, **Workflow Templates**, **Orchestration Templates**, and **Vault**. The Library is not a project. Nothing runs there: it has no Playground, no runs, no repositories, no channels, no context parameters, and no team access of its own. It cannot be deleted, only renamed or recolored, and it does not count toward your project limit. The typical path is to promote a resource from the project that built it, attach it from the projects that need it, and install templates into the projects that will run them. ## Shared by reference or installed as a copy | Library resource | How a project uses it | After reuse | | ---------------------- | ----------------------------------------------------- | ------------------------------------------------------------- | | Agent | Select it in an Agent Run or Agent Session step | Stays in the Library; edits apply everywhere it runs | | MCP server | Attach it to a project agent | Stays in the Library; edits apply to every agent that uses it | | Skill | Attach it to a project agent | Stays in the Library | | Secret | Attach it to a project agent, MCP server, or workflow | Stays in the Library; the value is never copied | | Workflow template | **Install from Library** | An independent, project-owned draft | | Orchestration template | **Install from Library** | An independent, project-owned draft | A Library resource can depend only on other Library resources. A Library agent attaches Library MCP servers, skills, and secrets; a Library MCP server uses Library secrets. Project resources can mix both: a project agent can use a Library MCP server alongside a project one. ## Use a Library resource from a project Library resources do not appear in a project's own **MCP Servers**, **Skills**, or **Project Vault** lists. Those pages show what the project owns. Library resources appear where you attach them: * In an agent's **Add MCP Server**, **Add Skill**, and **Add Secret** dialogs, Library items carry a **Library** badge. Attached Library items show the same badge in the agent's panels. * In a workflow's **Secrets** panel and an MCP server's secrets picker, Library secrets carry the **Library** badge. * In the agent picker of an Agent Run or Agent Session step, agents are grouped under **Project** and **Workspace library**. To edit a Library resource, switch to the Workspace Library. Attached items in a project are read-only there. ## Promote a resource Promotion moves a project-owned MCP server, skill, secret, or agent into the Workspace Library. It is a move, not a copy: the resource keeps its identity, every existing link keeps working, and there is no way to move it back. Workflows and orchestrations are not promoted; author templates in the Library directly. Select **Promote to library** on the MCP server, skill, or agent page, or on the secret's row in **Project Vault**. A dialog titled `Promote '' to the workspace library?` explains what changes: * **MCP server**: every project can attach it, it is edited from the Library after promotion, and its linked secrets must already be Library secrets. * **Skill**: every project can attach it, and it is edited from the Library after promotion. * **Agent**: every project can run it in workflows, it is edited from the Library after promotion, and its MCP servers, skills, and secrets must already be Library items. * **Secret**: every project can link it, and it is edited from the Library Vault after promotion. If the secret is available for all executions, the dialog also warns that it will be injected into every run in the workspace. Confirm with **Promote**. Overcut opens the resource at its new location in the Library, or, for a secret, shows **Secret promoted to the workspace library**. Promote dependencies first, from the bottom up: Promote the secrets that the MCP server or agent links. No value re-entry is needed. Promote MCP servers once their secrets are in the Library. Otherwise promotion stops with `Promote these secrets to the workspace library first: `. Promote the agent last. If it still links a project MCP server, skill, or secret, promotion stops with `Promote these to the workspace library first: `. Skills have no dependencies and can be promoted at any time. A promoted resource keeps its name, and names must be unique within the Library. If a Library MCP server, agent, or secret with the same name already exists, or a Library skill already points at the same repository path, promotion stops and names the conflict. ## Library Vault and shared secrets The Library's **Vault** page is titled **Library Vault**. Secrets there work like project secrets: encrypted, never shown to the model, and injected as environment variables. Two things differ: * **Reach.** A Library secret can be linked by agents, MCP servers, and workflows in every project. A Library secret with **Available for All Executions** turned on is injected into every run in the workspace, and its tag reads **Available for All Executions in All Projects**. * **Precedence.** A project secret with the same name as a Library secret wins in that project's runs. The project secret's row shows **Overrides the library value in this project's runs**. Use this when one project needs its own credential for a shared MCP server. At run time Overcut collects secrets from both the project and the Library: secrets available for all executions, secrets linked to the workflow, secrets linked to each agent in the step, and secrets linked to those agents' MCP servers. See [Vault](/docs/reference/vault) for creating, assigning, and referencing secrets. Promoting a secret that is available for all executions expands it from every run in one project to every run in the workspace. Restrict it first if that is not what you want. ## Author a Library template A template is a workflow or orchestration created inside the Workspace Library, in the same builder you use in a project. The **Workflow Templates** page notes that templates never run, and the **Orchestration Templates** page has no active state. Each template has **Builder** and **History** tabs only. You can start a template from a Playbook: **Add from Playbook** works inside the Library and adds the Playbook as an inactive template. Publish the template before anyone installs it. Installing copies the last committed version, never the draft, and the install pickers list only templates with a committed version. ## Install a workflow template In a project, open **Workflows** and select **Install from Library**. The **Workflow Templates** dialog lists every committed template. The **Install Workflow Template** dialog prefills the **Workflow Name** from the template. Map each project-owned agent the template references to an agent this project can use. Agents that live in the Library need no mapping. Select **Install**. Overcut confirms with **Template installed as a draft workflow!** and offers **Open Workflow**. Review agents, conditions, and repository references, then publish the workflow. The copy belongs to the project. Later changes to the template do not reach it, and changes to the copy do not reach the template. If the template references a context parameter, that parameter must be a workspace parameter, or publishing the copy fails until you define it. See [Context Parameters](/docs/reference/context-parameters#lifecycle-and-governance). For a JSON file instead of a Library template, see [Import & Export Workflows](/docs/workflows/workflow-import-export). ## Install an orchestration template In a project, open **Orchestrations** and select **Install from Library**. The **Orchestration Templates** dialog lists every committed template. In the **Install Orchestration Template** dialog, set the **Orchestration Name**, then map each workflow the template references. Choose an existing workflow in this project, or select **Install a copy** to install the template's workflow into the project and use it here. Every row needs a mapping. Select **Install**. Overcut confirms with **Template installed as a draft orchestration!** and offers **Open Orchestration**. The copy is an inactive draft. Review the mapped workflows, triggers, gates, and limits, then publish and activate it. See the [Orchestration Builder](/docs/orchestrations/builder) for the publish and activation flow. ## Delete safeguards A Library MCP server, skill, secret, or agent cannot be deleted while something still uses it. The delete fails with a message in this form: ```text theme={"dark"} Cannot delete agent 'Reviewer': it is still used by workflow "PR Review" in project "Web". Detach it there first. ``` Usage means an agent linking the MCP server or skill; an agent, MCP server, or workflow linking the secret; or a workflow in any project whose draft or committed version references the agent. Uses inside the Library count too. The message is the only list of usages, so detach or replace the references it names, then delete. Templates are never protected. Deleting a workflow or orchestration template does not affect the copies projects installed. ## Permissions Access to the Library is controlled by two workspace-level permissions on a role: viewing the Library, and editing it. Editing includes creating and changing Library resources and promoting resources into the Library. Workspace admins have both. The built-in non-admin roles can view the Library but not edit it; create a custom role to let a team maintain shared resources. Members without view access do not see the Library in the project picker and cannot install templates. If a non-admin member cannot find the Library, check that their role grants view access. ## Troubleshooting | Symptom | Cause | Fix | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | **Install from Library** shows `No committed workflow templates yet` | The template has only a draft. | Publish the template in the Library, then install. | | Promotion stops with `Promote these ... first` | The resource links a project-owned secret, MCP server, or skill. | Promote the named dependencies, then retry. | | Deleting a Library resource fails with `Cannot delete ...` | A project or Library resource still references it. | Detach the references the message names, then delete. | | An installed workflow does not publish, citing an unknown context parameter | The template references a project parameter that this project cannot see. | Promote that parameter to the workspace, or define it at the workspace level. | | A workflow in the Library shows no **Run** button | Templates never run. | Install the template into a project and run the copy. | ## Chat Overcut chat can list and create Library resources, promote a project resource after you confirm, and install a template into a project you choose; the copy stays a draft until you approve publishing it. Chat can create a secret entry but never accepts its value; enter that in the **Library Vault**. Inside the Library, chat cannot run, activate, or inspect runs, because nothing runs there. See [Chat with Overcut](/docs/how-to/chat-with-overcut). ## Related * [Reuse Across Projects](/docs/concepts/reuse-across-projects): when to share, copy, or scope. * [Context Parameters](/docs/reference/context-parameters): values that differ per project, repository, workflow, orchestration, or agent. * [Vault](/docs/reference/vault): creating, assigning, and referencing secrets. * [Import & Export Workflows](/docs/workflows/workflow-import-export): JSON snapshots of a workflow. * [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces): the workspace and project boundary. # Workspace Settings Source: https://docs.overcut.ai/docs/reference/workspace-settings Configure the workspace profile and the defaults that every project in the workspace inherits. Workspace-level configuration covers the things that apply to the entire workspace and every project inside it: the workspace profile, default LLM models, integrations, team membership, the [Workspace Library](/docs/reference/workspace-library), and [context parameter](/docs/reference/context-parameters) definitions. Project-specific configuration (workflows, agents, repositories, project vault, project permissions) lives inside each project under [Project Settings](/docs/concepts/multi-project-workspaces#project-settings). This page covers the workspace **Settings** page. For review and audit workflows, see [Audit Trail](/docs/reference/audit-trail) to understand workspace activity, filtering, event details, and redaction behavior. ## Settings The **Settings** page (`Account → Settings` in the sidebar) contains the workspace profile and the workspace-wide defaults that projects inherit. All fields are saved together when you click Save Changes. From the global workspace switcher, choose the workspace you want to configure. Click Settings in the workspace sidebar. The current workspace settings are displayed. Update any of the fields. See the sections below for details on each field. Click Save Changes. A confirmation message appears when your changes are saved successfully. ### Workspace Name The workspace name identifies your workspace throughout the application. It appears in workspace switchers, breadcrumbs, and other UI elements. * **Required**: Yes ### Timezone The timezone selector determines when scheduled workflows execute. The field displays a curated list of major world timezones, sorted by UTC offset and showing current offset information (e.g., "(UTC-8) America Los Angeles (PST)"). * **Default**: UTC * **Description**: Timezone used for scheduled workflows. All workflows will run according to this timezone. The timezone options automatically account for daylight saving time changes and are sorted from west to east by UTC offset. ### Default LLM Model The **Default LLM Model** selector sets the main workspace default. Workflows and agents inherit it when their higher-priority model settings use the default model placeholder. * **Default**: Falls back to the system default if not set * **Description**: Default model used by agents in this workspace when no other model is specified The selector displays active models from **LLM Models**. Inactive models remain visible on the **LLM Models** management page, but they do not appear in the **Default LLM Model** picker. For steps that use the **Overcut** engine, model resolution can continue from this setting to the system default. The **Claude** engine has a separate workspace default and cannot use a system model as a fallback. Leave workflow and agent model pickers at their default model placeholder when you want them to inherit workspace settings. A specific selection overrides the applicable workspace default. #### How existing vs. new workflows behave * **Existing workflows** keep their current model selections. Steps that use the default model placeholder inherit the saved workspace value on their next execution. * **New workflows** and newly created agents start with the default model placeholder. For the Overcut engine, an execution can use the system default until you set a main workspace default. * **No retroactive edits** occur. Changing a workspace default does not rewrite workflow or agent definitions. ### Default Claude Engine Model The **Default Claude Engine Model** selector sets a workspace default only for steps that use the **Claude** engine. It does not change **Default LLM Model** or the default used by the Overcut engine. The selector includes active Anthropic and AWS Bedrock models from the current workspace. You can clear the selection. When it is clear, a Claude-engine step can continue to the main **Default LLM Model**, but only if that model is compatible with the Claude engine. See [LLM Models](/docs/reference/llm-models#overcut-vs-claude) for supported providers, credential options, and engine compatibility. #### Model resolution order A Claude-engine step checks these sources in order and uses the first configured model: | Priority | Source | | -------- | ------------------------------------------------------------------ | | 1 | Coordinator override | | 2 | Agent model | | 3 | Workflow default | | 4 | Workspace Claude default, set with **Default Claude Engine Model** | | 5 | Main workspace default, set with **Default LLM Model** | A default model placeholder is skipped so the next source can provide a model. The first resolved model must be active, owned by the current workspace, non-system, and provided by Anthropic or AWS Bedrock. If it does not meet these requirements, or if no model is configured, the step fails. The Claude engine does not continue to a system default. This differs from the Overcut engine cascade, which can use its system default after the main workspace default. See [LLM Models](/docs/reference/llm-models#model-cascade) for the Overcut engine order. ### Auto-Improve Workflows The **Auto-Improve Workflows** toggle controls whether workflows in the workspace can use self-improvement features. Turn it on when you want workflow dashboards to expose the **Self-Improvement** panel and let each workflow run retrospective analysis. * **Description**: Enables automatic retrospective analysis of workflow runs to generate improvement suggestions This workspace setting is a prerequisite for workflow-level self-improvement. If the toggle is off, workflow dashboards show a prompt directing you to enable it here first. Once enabled, each workflow dashboard exposes a **Self-Improvement** panel where you configure retrospective cadence, sample size, and view retrospective activity. See [Workflow Self-Improvement](/docs/how-to/workflows/workflow-self-improvement) for the full walkthrough on configuring cadence, sample size, validation limits, and viewing retrospective results. ## Where credentials live There is no workspace-wide secret store. Credentials live in three places, by what they are for: * **LLM provider keys** (Anthropic, AWS Bedrock, OpenAI, and others) are configured on each model under **LLM Models**. See [LLM Models](/docs/reference/llm-models). * **Secrets that several projects share**, such as a Sentry token used by a shared MCP server, live in the **Library Vault** of the [Workspace Library](/docs/reference/workspace-library). * **Secrets used by one project** live in that project's [Project Vault](/docs/reference/vault). If **LLM Models** lists a **Claude (migrated)** Anthropic model, Overcut created it from the workspace-wide Claude API key that older workspaces stored and set it as the workspace **Default Claude Engine Model**. It needs no action. ## Custom Events **Custom Events** is a workspace-level surface for defining your own event types that any third-party system can fire via a public webhook URL. Each event has a unique URL, an optional Bearer or custom-header secret, and an allowlist controlling which projects can react to it. Open it from the workspace sidebar under **Custom Events**. The page lists every event defined in the workspace, with filters for category, scope, and search. Four permissions, all workspace-scoped and granted to workspace admins by default: | Permission | Allows | | -------------------- | ------------------------------------------------------------------------- | | `customEvent.view` | List events, see webhook URLs | | `customEvent.create` | Create a new event | | `customEvent.edit` | Edit fields, change allowed projects, rotate the URL token or auth secret | | `customEvent.delete` | Delete an event | Holding `customEvent.edit` lets a user add any project in the workspace to an event's allowlist. Project admins cannot add their own project to an event's allowlist on their own. For setup, auth modes, and recipes for common SDLC tools, see [Custom Events (Integrations)](/docs/integrations/custom-events). For the dispatcher contract, see the [Custom Events API reference](/docs/reference/custom-events-api). ## Related references * [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces): workspace-level vs project-level configuration boundary. * [Workspace Library](/docs/reference/workspace-library): shared agents, MCP servers, skills, secrets, and templates. * [Context Parameters](/docs/reference/context-parameters): workspace-level definitions and per-scope values. * [Vault](/docs/reference/vault): project and Library secrets. * [Claude Agent SDK Integration](/docs/integrations/claude-agent-sdk): learn how to use Claude as an execution engine in your workflows. * [Workflow Metadata defaults](/docs/building-blocks): covers per-workflow model overrides. * [Agent builder](/docs/workflows/agent-run): describes per-agent model choices and when to use the default model. * [Custom Events](/docs/integrations/custom-events): workspace-defined webhook events that any third-party system can fire to trigger workflows. # Repository Agent Image Source: https://docs.overcut.ai/docs/repositories/agent-image Choose the container environment your agents run in for each repository so builds and tests use the right language toolchain. Every workflow runs your agents inside a container that provides the languages, SDKs, and build tools needed to clone, build, test, and analyze your code. The **Agent Image** setting controls which environment a repository uses. Most repositories work with the default image. Select a different one when your codebase needs a newer toolchain, or a custom image your workspace registered when it needs tools the system images lack. ## Available images The **Agent Image** picker in repository settings offers three groups. | Option | Environment | Best for | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | **Default Image** | The standard Overcut agent image (currently **Universal 2**), with common languages and runtimes preinstalled, including Python, Node.js, Java, Go, Ruby, PHP, and .NET. | Most repositories. | | **System images** | **Universal 2** and **Universal 6**, maintained by Overcut. Universal 6 is a newer build of the same environment on Ubuntu 24.04, with up-to-date versions across every included language and runtime. | Repositories that need a more recent toolchain than the default provides. | | **Workspace images** | Custom images your workspace registered on the [Agent Images](/docs/reference/agent-images) page, pulled from your own registry. | Repositories that need a toolchain the system images do not ship: Rust, Bazel, a pinned SDK, an internal CLI. | Both system images are based on Microsoft's [dev container universal image](https://github.com/devcontainers/images/tree/main/src/universal), which bundles many languages and runtimes in one environment. They differ by version: Universal 6 is the newer build. ### Default Image The standard Overcut agent environment. It covers the most common stacks and is the right choice unless your project needs a newer toolchain version than it provides. Selecting **Default Image** is the same as leaving the setting unset. ### Universal 6 A newer, modern build of the universal environment on Ubuntu 24.04. It refreshes the whole toolchain, bringing more recent versions of every included language and runtime (Python, Node.js, Java, Go, Ruby, PHP, C/C++, and .NET). Choose it when your repository depends on a language or SDK version that the default image predates, for example a newer Python interpreter, an updated Node.js LTS, or a recent .NET release. If your project requires a language or runtime version newer than the default image provides, agents in the default image can still write and commit code, but their build and test checks fail. Selecting **Universal 6** gives agents the matching versions to validate their changes. ### Workspace images When neither system image fits, register your own image on the workspace **Agent Images** page. Overcut copies it from your registry, checks it for compatibility, and pins it by digest. Once its status is **Ready**, it appears in this picker under **Workspace images** for every repository in the workspace. Registration requirements, credentials for private registries, and troubleshooting are covered in [Agent Images](/docs/reference/agent-images). Overcut maintains the system images and adds newer universal images as they become available, so repositories on a system image get updated toolchains without any maintenance on your side. ## Selecting an image The Agent Image is set per repository. Other repositories keep the default image. Go to the repository's configuration panel under Repositories, or the integration that connected it. Open the **Agent Image** dropdown and select **Default Image**, a system image, or one of your workspace images. Workspace images appear only once they are Ready. Save the configuration. New runs for this repository use the selected image. ## How Overcut selects the image for a run Overcut resolves the agent image once, when a run starts, and uses it for the whole run. It checks, in order: 1. **The trigger repository.** If the repository that triggered the run has an Agent Image set, that image is used. 2. **Linked code repositories.** If the trigger repository has no image set, Overcut checks the code repositories linked to it and uses the first one that does. This is common for ticket repositories in Jira or Azure DevOps, where the ticket has no code to build and the image belongs to the linked code repository. 3. **Default image.** If none of the above set an image, the run uses the default image. This is why, for ticket-triggered workflows, you set the image on the linked **code** repository: the agent builds and tests there, so its image is the one that applies. See [Repository Mapping](/docs/repositories/repository-mapping). ### Handling conflicts If a run involves several linked code repositories that set **different** images, Overcut uses the first one by the order above and records a warning so you can spot the mismatch. To keep the outcome predictable, set the same image across the related repositories, or set it on the trigger repository so it takes precedence. The image is chosen when the run starts, so a code repository must be the trigger repository or already linked to it for its image to apply. A repository discovered only later in the run, during [repository identification](/docs/workflows/repo-identify), cannot change the image for that run. A run fails at preparation if the repository selects a workspace image that is no longer Ready, for example one that was deactivated or whose refresh failed. Activate or retry the image on the Agent Images page, or switch the repository to another image. ## Related * [Agent Images](/docs/reference/agent-images) * [Repositories](/docs/get-started/repositories) * [Repository Mapping](/docs/repositories/repository-mapping) * [Repository Caching](/docs/repositories/repository-caching) # Context Map Source: https://docs.overcut.ai/docs/repositories/context-map Visualize and manage repository correlations across your workspace using the interactive Context Map. The Context Map is an interactive visual graph that shows every repository in your workspace and how they relate to each other. Use it to explore correlations between code repositories and ticket projects, create or remove links, and edit repository properties, all without leaving the map. ## Accessing the Context Map Navigate to **Context Map** in the workspace sidebar (under **Configuration**). The Context Map is a **workspace-level** view: it shows every repository connected to the workspace, regardless of project boundaries. The Context Map is distinct from the **Project Map**. Project Map (`Project → Project Map`) is a project-scoped orchestration view that shows the workflows, agents, and resources inside a single project. Context Map shows the cross-workspace repository graph. See [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces) for the workspace-vs-project boundary. ## Reading the Visualization The map uses a two-column layout powered by a graph canvas: * **Left column**: code repositories (marked with a green **Code** tag) * **Right column**: ticket projects (marked with a blue **Tickets** tag) * **Edges**: directed arrows from code repositories to their correlated ticket projects Repositories are grouped by organization, with the provider logo (GitHub, GitLab, Bitbucket, Azure DevOps, Jira) displayed on each group header. If a repository is configured for both code and tickets, it appears in both columns with a mirror node. ### Node Details Each repository node shows: * Repository name and provider logo * Role tags (**Code**, **Tickets**, or both) * Feature indicators for enabled capabilities such as Repo Hints, Cache, Code Indexing, and Custom Instructions * Active or inactive state (inactive nodes appear dimmed) ### Special Edges * **Self-correlation**: repositories marked for both code and tickets display a dashed edge that cannot be deleted. * **Implicit Azure DevOps correlations**: repositories under the same Azure DevOps project are linked automatically. ### Canvas Controls Use standard canvas interactions to navigate the map: * **Pan**: click and drag the background * **Zoom**: scroll wheel or pinch gesture * **Fit to view**: use the controls overlay to reset the viewport * **Minimap**: a small overview in the corner shows your current position in the graph *** ## Filters and Focus Tools When your workspace contains many repositories the filter bar and focus tools help you narrow the view. ### Filter Bar The top bar provides two filter types: | Filter | Description | | ----------------- | ------------------------------------------------------------------------------------ | | **Organization** | Show only repositories belonging to selected organizations. Multi-select supported. | | **Feature flags** | Filter by enabled features: Repo Hints, Cache, Cache Dependencies, or Code Indexing. | When filters are active the map shows only matching repositories and their edges. Clear filters to return to the full view. ### Highlight and Pin Hover over a repository node to reveal two focus controls: * **Highlight**: click to highlight the selected node and all directly connected nodes and edges. Unrelated nodes dim to reduce visual noise. * **Hide unrelated**: after highlighting, toggle this option to hide all unconnected nodes entirely, isolating the subgraph you care about. Click the background or clear the selection to restore the full map. For large graphs, combine an organization filter with highlight to quickly isolate the repositories that matter for a specific team or project. *** ## Creating and Deleting Correlations You can manage correlations directly on the canvas without opening repository settings. ### Create a Correlation 1. Hover over a code repository node to reveal the connection handle. 2. Drag from the handle to a ticket project node. 3. Release to create the correlation. The system validates that the source is a code repository and the target is a ticket project. Invalid connections are rejected. ### Delete a Correlation 1. Click an edge to select it. 2. Confirm the deletion in the dialog that appears. Implicit correlations (self-correlations and Azure DevOps project-based links) cannot be deleted from the map. Adjust the underlying repository configuration instead. *** ## Properties Panel Click any repository node to open the **Properties Panel** on the right side of the screen. The panel displays the full repository configuration form, letting you review and edit fields without navigating away from the map. ### What You Can Edit The properties panel exposes the same fields available in repository settings: * Repository purpose (**Use for Code**, **Use for Tickets**) * Related Ticket Projects and Related Code Repositories * Identification hints * Cache and indexing configuration * Custom instructions ### Saving Changes Edits save when you click **Save** inside the panel. The map refreshes automatically to reflect updated correlations, purposes, or feature flags. Close the panel by clicking the background or the close button. *** ## Best Practices * **Start with correlations**: set up explicit links between your most important code repos and ticket projects before relying on AI-powered identification. * **Use filters for large workspaces**: narrow by organization first, then highlight specific nodes to trace relationships. * **Audit regularly**: open the Context Map periodically to verify that correlations still reflect your team structure and project boundaries. * **Combine with Repository Mapping**: correlations created on the Context Map feed directly into the [repo.identify](/docs/workflows/repo-identify) step for automatic repository selection in workflows. ## See Also * [Repository Mapping](/docs/repositories/repository-mapping): configure correlations and use AI-powered repository identification * [Repository Selector](/docs/repositories/repository-selector): filter repositories for scheduled workflows # Repository Caching Source: https://docs.overcut.ai/docs/repositories/repository-caching Speed up your automation workflows with intelligent repository caching that saves time on repeated operations. Repository caching is a powerful feature that dramatically speeds up your Overcut automation workflows by storing and reusing repository content and dependencies. Instead of cloning repositories and installing dependencies from scratch every time, Overcut intelligently caches this information to reduce wait times and improve efficiency. ## What is Repository Caching? Repository caching works by storing a snapshot of your repository (including code, dependencies, and build artifacts) after the first run. On subsequent runs, Overcut can use this cached version to skip the time-consuming steps of cloning and installing dependencies. Repository is cloned, dependencies are installed, and everything is cached for future use. Cache is used to skip cloning and dependency installation, dramatically reducing startup time. **Dependency Caching is Key**: While caching repository code provides some speed benefits, caching installed dependencies can save significantly more time. Installing dependencies (npm install, pip install, etc.) often takes much longer than cloning the repository itself. Enabling "Pre install and cache dependencies" in your repository settings can reduce workflow execution time by 70-90% in many cases. ## Benefits * **Faster Workflow Execution**: Skip repository cloning and dependency installation * **Reduced Resource Usage**: Less network bandwidth and storage operations * **Improved Reliability**: Consistent environment across multiple runs * **Better User Experience**: Faster response times for your automation workflows ## How It Works ### Automatic Cache Management Overcut automatically manages your repository caches: 1. **Cache Creation**: On the first run, Overcut creates a cache containing your repository and dependencies 2. **Cache Usage**: Subsequent runs use the cached version for faster execution 3. **Cache Refresh**: Caches are automatically refreshed in the background to keep them up-to-date 4. **Cache Invalidation**: Old caches are automatically cleaned up to save disk space ### Cache Scope Each cache is isolated by: * **Workspace**: Different workspaces never share cache content * **Repository**: Each repository has its own cache * **Provider**: GitHub, GitLab, Bitbucket, etc. are cached separately For detailed information about security measures, data isolation, and privacy practices, see our [Privacy and Security](/docs/privacy-and-security) documentation. This ensures that your workspace data remains private and secure. ### How Overcut Updates Cached Repositories When using a cached repository, Overcut doesn't just restore the old version - it intelligently updates it to get the latest changes: Overcut extracts the cached repository to your working directory, including all files, Git history, and dependencies. The system switches to your target branch (or the default branch if none specified) and ensures it's up-to-date. Finally, Overcut pulls the latest changes to ensure your working directory contains the most recent code. This process ensures that while you benefit from the speed of cached dependencies and repository structure, you always get the latest code changes for your workflow execution. **Smart Branch Handling**: Overcut automatically detects whether the target branch exists in the cached version and either checks it out or creates it from the remote, ensuring seamless branch switching. Even if the cache was created from a different branch, Overcut will fetch and checkout the requested branch automatically. ## Configuration ### Enabling Cache for a Repository You can control caching on a per-repository basis: Go to your repository in the Overcut dashboard and click on the repository name to access settings. In the repository configuration, toggle "Enable Cache" to turn on caching for this repository. Optionally enable "Pre install and cache dependencies" to cache installed packages and reduce installation time. ### Cache Settings Master toggle to enable or disable caching for the repository. When enabled, dependencies are pre-installed and cached, further reducing setup time. **Maximize Your Time Savings**: The "Include Dependencies" option is where you'll see the biggest performance gains. A typical Node.js project might take 2-3 minutes to clone but 5-15 minutes to install dependencies. With dependency caching enabled, subsequent runs can skip the entire installation process, making your workflows dramatically faster. ### Required: Dependency Installation Commands To enable dependency caching, you must provide the command that installs dependencies for your project. This is configured in the **Tools** section of your repository settings: In your repository configuration, scroll down to the "Tools" section below the cache settings. Look for the "Install dependencies" tool and provide the appropriate command for your project: * **Node.js**: `npm install` or `yarn install` * **Python**: `pip install -r requirements.txt` or `poetry install` * **Ruby**: `bundle install` * **Go**: `go mod download` * **Custom**: Any command that installs your project dependencies Once the install command is configured, you can enable "Pre install and cache dependencies" in the cache settings. **Built-in Tools**: Overcut provides several built-in tools including "Install dependencies" with a placeholder command. You must customize this command to match your project's dependency management system for caching to work properly. ## Advanced Features ### Smart Cache Eligibility Overcut intelligently determines when cache can be used based on your workflow configuration: * **Standard Clones**: Cache is used for normal repository cloning * **Sparse Checkouts**: Cache is bypassed when using sparse checkout (as it changes repository structure) * **Partial Clones**: Cache is used with partial clone filters (blob limits, tree depth) * **Force Fresh Clone**: Use the `ignoreCache` option on the `git.clone` step to bypass cache when needed ### Automatic Cache Refresh Caches are automatically refreshed in the background: * **Refresh Trigger**: Caches older than 10 days trigger a background refresh * **Invalidation**: Caches older than 20 days are considered stale and won't be used * **Non-blocking**: Cache refresh never blocks your workflow execution ### Automatic Code Indexing after Cache Refresh Repository Caching is a **prerequisite for Code Indexing**. The code indexer relies on the cached repository snapshot to process files efficiently. When repository caching finishes a background refresh and Code Indexing is enabled, Overcut automatically triggers an indexing workflow t detect changes since the last indexed commit and only re-processes modified files (incremental update). The indexing workflow runs like any other workflow execution and can be monitored in **Monitor** > **Logs**. This automatic update keeps the semantic index aligned with the latest code without manual intervention. Code Indexing is disabled by default. To enable automatic indexing after cache refreshes, you must explicitly turn on both the **Repository Caching** and **Code Indexing** toggles in repository settings. The next cache refresh will then automatically queue an indexing job. ## Best Practices ### When to Use Cache * **Frequently accessed repositories**: Repositories used in multiple workflows * **Stable dependencies**: Projects with consistent dependency requirements * **Regular automation**: Workflows that run multiple times per day ### When to Bypass Cache * **Debugging**: Use `ignoreCache` when investigating cache-related issues * **Dependency changes**: When you need to test with fresh dependencies * **Sparse checkouts**: When using sparse checkout features ### Dependency Management * **Use lockfiles**: Ensure your project has package-lock.json, yarn.lock, or similar * **Consistent versions**: Keep dependency versions consistent across environments * **Regular updates**: Periodically refresh caches to get latest dependency updates ## Troubleshooting ### Common Issues Check that caching is enabled in repository settings and the repository is active. Dependencies may be outdated. Trigger a manual cache refresh or wait for automatic refresh. Large repositories may take longer to cache. This is normal for the first run. Ensure your repository has proper access permissions configured. ### Updating Dependencies To update dependencies in your cached repository, you can instruct the agent to run the dependency installation command before starting their main task: In your workflow, add a step that runs your dependency installation command before the main agent task. Reference the "Install dependencies" tool you configured in your repository settings. For example: * **Node.js**: `npm install` (updates to latest compatible versions) * **Python**: `pip install -r requirements.txt --upgrade` * **Ruby**: `bundle update` The agent will then proceed with the updated dependencies for their main task. **Smart Dependency Updates**: When you instruct the agent to run dependency installation, Overcut will use the updated dependencies for that run. However, the cache itself is only updated during explicit cache refresh cycles, not after normal agent runs. This means the next run will start with the cached dependencies, but the agent can update them as needed for the current task. ## Integration with Workflows Repository caching works seamlessly with the `git.clone` step. ## Getting Started To start using repository caching: 1. **Enable for a Repository**: Go to repository settings and toggle caching on 2. **Run Your Workflow**: The first run will create the cache 3. **Enjoy Faster Runs**: Subsequent executions will use the cached version 4. **Monitor Performance**: Check execution logs to see cache usage Repository caching is disabled by default for repositories. # Repository Code Indexing Source: https://docs.overcut.ai/docs/repositories/repository-indexing Enable semantic code search to help agents find relevant context faster. Learn how to set up, trigger, and monitor code indexing. ## Overview Code Indexing creates a semantic index of your repository, allowing agents to search code by meaning rather than just keywords. When enabled, agents can find relevant APIs, understand code relationships, and locate files more efficiently. Once enabled, indexing runs automatically whenever your repository cache is refreshed. The system detects changes since the last update and only re-indexes modified files, keeping the index current with minimal overhead. You can also trigger indexing manually at any time from the repository settings page. **Semantic search is optional.** Agents work effectively without code indexing by using standard file searches, grep, and glob patterns. Code indexing provides an additional search capability that can help agents find context more efficiently, but it is not required. ### How agents use semantic search When Code Indexing is enabled, agents automatically gain access to a semantic search tool alongside their standard search capabilities (file search, grep, glob). Agents intelligently choose the best tool for each situation: using semantic search when looking for conceptually related code and standard searches for exact matches. **No configuration required.** You don't need to instruct agents to use semantic search or modify your workflows. Once indexing is enabled, agents transparently leverage the semantic index when it's helpful, falling back to standard searches when the index isn't available or when exact matching is more appropriate. Code Indexing is **disabled by default**. To use this feature, you must enable it in repository settings. Additionally, **Repository Caching must be enabled first**. The indexer uses the cached repository snapshot to process files. ## Prerequisites Before enabling Code Indexing, ensure you have: 1. **Repository Caching enabled** – Code Indexing requires caching to be enabled first. See [Repository Caching](/docs/repositories/repository-caching) for setup instructions. ## Enabling Code Indexing Navigate to **Integrations → \[Your Organization] → \[Your Repo]** and open the repository settings. If not already enabled, turn on **Repository Caching** first. This is a prerequisite for code indexing. Turn on the **Code Indexing** toggle. The first indexing job will queue automatically once the cache is ready. ## How indexing works ### Automatic updates Once Code Indexing is enabled, the system keeps your index up to date automatically: * **After cache refresh** – Whenever the repository cache is refreshed, indexing runs automatically * **Incremental updates** – The indexer compares the current code to the last indexed version and only re-processes changed files * **Branch coverage** – By default, Overcut indexes the repository's default branch ### Manual triggers Use the **Index Now** button in repository settings to trigger indexing immediately. This is useful when: * You've made large refactors and want the index updated right away * You're switching default branches * Agents are referencing outdated code and you don't want to wait for the next automatic update Go to **Integrations → \[Your Organization] → \[Your Repo] → Code Indexing**. Click the **Index Now** button. For non-default branches, expand **Advanced options** and specify the branch. A success message confirms the indexing job has been queued. You can monitor progress in **Monitor** > **Logs**. ## Monitoring indexing runs ### Workspace Runs Indexing jobs appear in **Monitor** > **Logs** alongside your other workflow executions. You can: * View real-time progress as files are processed * See detailed logs for each stage (clone, analysis, indexing) * Compare current runs with historical performance * Diagnose issues if a run fails # Repository Mapping Source: https://docs.overcut.ai/docs/repositories/repository-mapping Learn how to map ticket projects to code repositories and use the identify-repo step to automatically identify the most relevant repositories for your tickets. ## Overview In multi-repository workspaces, Overcut can automatically identify which code repositories are most relevant to a specific ticket or issue. This feature uses intelligent correlation mapping and AI-powered analysis to determine the best repositories to work with, eliminating the need for manual repository selection in your workflows. ## How Repository Mapping Works Repository mapping in Overcut operates on two levels: 1. **Related Correlations**: Direct links between ticket projects and code repositories 2. **Automatic Identification**: AI-powered analysis that considers correlations, repository hints, and ticket context ### Repository Types * **Ticket Projects**: Project management systems like Jira, GitHub Issues, Azure DevOps, Linear, or ClickUp that contain tickets, issues, and project information * **Code Repositories**: Git repositories containing source code, typically linked to one or more ticket projects ### Correlation System The correlation system connects repositories using the **Related Ticket Projects** and **Related Code Repositories** fields: * Each code repository can be linked to multiple ticket projects * Each ticket project can be linked to multiple code repositories * Selected repositories appear as colored tags beneath the selector to confirm the relationship * These correlations are used as the primary signal for repository identification Correlations are the most reliable way to ensure accurate repository identification. Always set up explicit correlations when possible. ## Setting Up Repository Correlations ### Step 1: Configure Repository Purposes First, ensure your repositories are properly configured for their intended use: Go to **Settings → Integrations → Git** and select the repository you want to configure. In the repository configuration form, set the appropriate checkboxes: * **Use for Code**: Enable for repositories containing source code * **Use for Tickets**: Enable for project management systems (Jira, GitHub Issues, ClickUp Spaces, etc.) Click **Save** to apply your configuration. ### Step 2: Link Related Ticket Projects to Code Repositories You can establish correlations from either side of the mapping. Use whichever entry point matches your workflow. Choose a repository that has **Use for Code** enabled. In the **Related Ticket Projects** field, select the ticket projects this code repository should be linked to. Review the colored ticket project tags displayed under the selector to verify the relationship. Click **Save** to establish the links. ### Ticket-Side Linking Ticket projects can also link to code repositories from the ticket configuration view using **Related Code Repositories**. Choose a repository that has **Use for Tickets** enabled. In the **Related Code Repositories** field, select the code repositories you want to associate with the ticket project. Confirm the selected repositories appear as colored tags beneath the selector. Click **Save** to apply the links. ### Step 3: Add Repository Identification Hints For even better identification accuracy, add hints to your code repositories: Select a code repository in your workspace settings. In the **Identify Repo Hints** field, add high-level context that helps the system recognize when this repository is relevant: * Key domains or components (e.g., "backend", "frontend", "mobile app") * Service names (e.g., "user-service", "payment-gateway") * Technology keywords (e.g., "React", "Python", "Kubernetes") * Business domain terms (e.g., "billing", "authentication", "reporting") Click **Save** to apply your hints. **Example Hints:** * For a backend API: "REST API, user management, authentication, database" * For a frontend app: "React, user interface, dashboard, forms" * For a mobile app: "iOS, Android, mobile, user experience" ## Using the Identify Repository Step The `repo.identify` action automatically determines which repositories are most relevant to a ticket context. This step runs early in workflows that originate from ticket triggers. ### Adding the Identify Repository Step Navigate to **Workflows** and open or create a workflow. From the action palette, drag **Identify Repositories** to your workflow canvas. Set the following parameters: * **Max Results**: Maximum number of repositories to return (default: 1, range: 1-20) * **Min Confidence**: Minimum confidence threshold (default: 0.2, range: 0-1) * **Identification Hints**: Additional context to guide identification (optional) Connect this step after your trigger and before any repository-dependent actions. ### Step Parameters Explained * **Max Results**: Controls how many candidate repositories are returned. Use 1 for single-repo workflows, higher values for multi-repo scenarios. * **Min Confidence**: Filters out low-confidence matches. Higher values (0.7+) ensure only strong matches are returned. * **Identification Hints**: Additional context that can help the AI make better decisions, especially when correlations are unclear. ## How Identification Works The identification process follows this logic: 1. **Correlation Check**: First, looks for explicitly correlated repositories 2. **Context Analysis**: Analyzes ticket content (title, description, labels, components) 3. **Repository Hints**: Considers repository-level identification hints 4. **Scoring**: Combines all signals to produce confidence scores 5. **Filtering**: Applies minimum confidence threshold 6. **Ranking**: Sorts by confidence, with tie-breaking by repository name ## Using Identified Repositories in Downstream Steps Once repositories are identified, you can reference them in subsequent workflow steps using templating expressions. ### Referencing Repository Information The identify step returns an array of candidates with the following structure: ```json theme={"dark"} { "repoFullName": "organization/repository-name", "confidence": 0.85, "reasoning": "Strong correlation with ticket repository and matching component labels" } ``` ### Template Examples **Basic Repository Reference:** ```yaml theme={"dark"} repoFullName: "{{outputs.identify-repos.[0].repoFullName}}" ``` **Conditional Fallback:** ```yaml theme={"dark"} repoFullName: "{{#if outputs.identify-repos.[0]}}{{outputs.identify-repos.[0].repoFullName}}{{else}}{{trigger.repository.fullName}}{{/if}}" ``` **Coming Soon**: Currently, the `git.clone` action supports cloning a single repository at a time. In a future release, it will support cloning multiple top repositories in a single step, making multi-repository workflows more efficient. **Important**: If your step ID contains hyphens (e.g., `identify-repos`), use bracket notation: `{{outputs.[identify-repos].[0].repoFullName}}` [Context parameter](/docs/reference/context-parameters) values set on a repository come from the repository that triggered the run, or the one selected for a manual run. Identifying a different repository in this step does not change the values the run already resolved. ## Best Practices ### 1. Set Up Explicit Correlations * Always create explicit correlations between ticket projects and code repositories * This provides the most reliable identification results * Correlations take precedence over AI-based heuristics ### 2. Use Descriptive Repository Hints * Include key technologies, domains, and components * Use consistent terminology across related repositories * Update hints when repository scope changes ### 3. Configure Appropriate Confidence Thresholds * Use 0.7+ for production workflows requiring high accuracy * Use 0.4-0.6 for exploratory or development workflows * Monitor identification accuracy and adjust thresholds accordingly ### 4. Handle Multiple Repository Scenarios * Set `maxResults` appropriately for your use case * Consider whether you need to process all identified repositories * Use conditional logic for different repository counts ### 5. Test Your Workflows * Test with various ticket types and contexts * Verify repository identification accuracy * Check that downstream steps receive the expected repository information ## Troubleshooting ### Common Issues **No repositories identified:** * Check that correlations are properly set up * Verify repository purposes are correctly configured * Lower the confidence threshold temporarily * Add more descriptive repository hints **Wrong repository identified:** * Review and update repository correlations * Check repository hints for accuracy * Verify ticket context is being passed correctly * Consider adding more specific identification hints **Multiple repositories when expecting one:** * Review correlation setup for the ticket project * Check if multiple code repositories should actually be linked * Adjust `maxResults` parameter if needed ### Debugging Tips * Check the workflow execution logs for identification details * Review the confidence scores and reasoning provided * Verify that repository hints are being used correctly * Test with different ticket contexts to understand identification patterns ## Summary Repository mapping and automatic identification in Overcut provides: * **Explicit correlations** between ticket projects and code repositories * **AI-powered identification** using context and hints * **Configurable confidence thresholds** for accuracy control * **Flexible templating** for downstream workflow steps * **Scalable architecture** that works with any number of repositories By properly configuring correlations, adding descriptive hints, and using the identify repository step, you can create workflows that automatically work with the most relevant repositories for each ticket, significantly improving automation efficiency and accuracy. Start with explicit correlations for your most important repositories, then gradually add identification hints to improve accuracy for edge cases and new repositories. **ClickUp users**: Each ClickUp Space you connect appears as a separate ticket repository. Link Spaces to code repositories just like you would with Jira projects or Linear teams. See the [ClickUp integration guide](/docs/integrations/clickup) for setup details. ## How Repository Mapping Powers Multi-Repository Workflows ### **Dynamic Repository Selection** Repository mapping enables the `repo.identify` action to automatically select relevant repositories, which then seamlessly chain with `git.clone`: ```yaml theme={"dark"} steps: # Step 1: Identify repositories using mapping correlations - id: "identify-repos" name: "Identify Relevant Repositories" action: "repo.identify" params: maxResults: 3 minConfidence: 0.7 # Step 2: Clone the top identified repository - id: "clone-repo" name: "Clone Top Repository" action: "git.clone" params: repoFullName: "{{outputs.[identify-repos].[0].repoFullName}}" branch: "main" # Step 3: Process across identified repositories - id: "analyze-issue" name: "Multi-Repository Analysis" action: "agent.session" params: goal: "Analyze the issue across all relevant codebases" instruction: | Identified repositories based on correlations: {{#each outputs.[identify-repos]}} - {{this.repoFullName}} (confidence: {{this.confidence}}) Reasoning: {{this.reasoning}} {{/each}} ``` ### **Correlation-Based Confidence** Well-configured repository mappings provide the highest confidence scores in identification results: * **Explicit correlations**: 0.9-1.0 confidence (highest priority) * **AI analysis with hints**: 0.6-0.9 confidence * **AI analysis without hints**: 0.3-0.7 confidence This means properly mapped repositories will always be selected first in multi-repository workflows. ### **Multi-Repository Correlation Scenarios** Configure correlations to support different multi-repository patterns: **Microservices Architecture:** ``` Jira Project: "ECOM" (E-commerce) Correlated Repositories: - ecom/frontend (User interface) - ecom/api-gateway (API routing) - ecom/user-service (User management) - ecom/payment-service (Payment processing) - ecom/inventory-service (Inventory management) ``` **Full-Stack Application:** ``` Jira Project: "WEBAPP" (Web Application) Correlated Repositories: - webapp/client (React frontend) - webapp/server (Node.js backend) - webapp/shared (Shared utilities) - webapp/database (Schema and migrations) ``` **Cross-Platform Product:** ``` Jira Project: "MOBILE" (Mobile App) Correlated Repositories: - mobile/ios (iOS application) - mobile/android (Android application) - mobile/api (Backend API) - mobile/shared-components (Shared UI components) ``` When a ticket is created in any of these projects, `repo.identify` will automatically find the relevant repositories based on the correlations. Use the top match for cloning (for example, `repoFullName: "{{outputs.[identify-repos].[0].repoFullName}}"`), or loop through the results in separate steps if you need to work with multiple repositories. **Pro Tip**: Start by correlating your most critical repositories first. You can always add more correlations later as your workflow needs evolve. The system will fall back to AI analysis for repositories without explicit correlations. # Repository Selector Source: https://docs.overcut.ai/docs/repositories/repository-selector Learn how to precisely target which repositories a scheduled workflow should run against using provider filters, regex name patterns, and purpose flags. Includes concepts, UI guide, YAML examples, and best-practice tips. The **Repository Selector** is a powerful filtering mechanism that tells Overcut **which Git repositories or projects a scheduled workflow should operate on**. The repository selector can be used to select both code repositories and ticket projects/ repositories. See the [Scheduled Workflows guide](/docs/workflows/scheduled-workflows) for an end-to-end walkthrough of cron triggers and execution modes. ## Field Reference | Field | Type | Description | | ------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Name Pattern** | String (regex) | Regular expression to match against the **full repository name** (e.g., `myorg/my-repo`). For example, `^myorg/backend-.*` matches all repos in `myorg` starting with `backend-`. Leave empty to match all repositories. | | **Exclude Pattern** | String (regex) | Regular expression to exclude repositories by **full name**. For example, `^.*-archived$` excludes repos ending with `-archived`. Exclusions run *after* inclusions. | | **Provider** | String | Filter by a specific Git provider. Options: `Github`, `Gitlab`, `Bitbucket`, `AzureDevOps`, `Jira`. Leave empty to match *any* provider. | | **Use For Code** | Boolean | If ON, only repositories marked **Use for Code** in *Repository Settings* are considered. | | **Use For Tickets** | Boolean | If ON, only repositories marked **Use for Tickets** are considered. Useful for selecting ticket projects (Jira, GitHub Issues). | Overcut applies an upper bound of **100 repositories per evaluation** to protect your workspace from accidental fan-out. If your selector matches more than 100 repos, only the first 100 (sorted alphabetically) will be used and a warning appears in the UI and execution logs. *** ## Authoring Selectors in the UI 1. **Open Workflow Builder** and add/edit a Trigger or Action that supports selectors (e.g., a *Scheduled* trigger in *Per-Repository* mode). 2. In the **Repository Selector** panel, fill in the fields described above.\\ Repository selector panel 3. Click **Save**. The selector definition is now embedded in the workflow version and will be evaluated at runtime. `namePattern` matches the **full repository name** including the organization (e.g., `acme/web-app`) Use regex alternation `(pattern1|pattern2)` to match multiple patterns ## Real-World Selector Examples | Goal | Example Selector | | --------------------------------------------------------------- | --------------------------------------------------------------- | | **Run on all GitHub repos in *acme* org** | provider: `Github`, namePattern: `^acme/.*`, useForCode: `true` | | **Run on repos starting with `infra-` in any org** | namePattern: `"/infra-"` | | **Skip archived or deprecated repos** | excludePattern: `(-archive\|-deprecated)$` | | **Operate on ticket projects only (Jira & GitHub Issues)** | useForTickets: `true` | | **Multiple orgs: match repos in *acme* or *beta* orgs** | namePattern: `^(acme\|beta)/.*` | | **Complex pattern: backend or API repos, excluding test repos** | namePattern: `/(backend\|api)-`, excludePattern: `-test$` | *** ## Best Practices & Gotchas 1. **Patterns Match Full Names** – Remember that `namePattern` and `excludePattern` match against the full repository name (e.g., `myorg/my-repo`), not just the repo name. To filter by organization, use `^orgname/` in your pattern. 2. **Use Regex Alternation for Multiple Patterns** – To match multiple patterns, use regex alternation syntax: `^(pattern1|pattern2|pattern3)`. For example: `^acme/(web-.*|api-.*)` matches repos in the `acme` org starting with `web-` or `api-`. 3. **Start Narrow, Then Broaden** – Begin with tight patterns, verify run counts, then relax filters if needed. 4. **Avoid Overly Broad Selectors** – Matching *every* repo can create hundreds of workflow runs. Use specific patterns and purpose flags to limit scope. 5. **Monitor Execution Volume** – Check *Execution History* after enabling a new schedule to confirm expected run counts. 6. **Combine with Repository Mapping** – For ticket-triggered workflows, prefer [Repository Mapping](/docs/repositories/repository-mapping) and [`repo.identify`](/docs/workflows/repo-identify) over broad selectors. *** ## Further Reading * [Scheduled Workflows](/docs/workflows/scheduled-workflows) * [Workflow Execution Control](/docs/workflows/workflow-execution-control) * [Repository Mapping](/docs/repositories/repository-mapping) # Vulnerability Management & Version Lifecycle Source: https://docs.overcut.ai/docs/vulnerability-management How Overcut identifies, triages, remediates, and ships security and stability fixes, and how long each release is supported for customer-managed deployments. This policy describes Overcut's vulnerability management practices, release process, and version support lifecycle for customer-managed deployments. It provides transparency into how Overcut identifies, remediates, and delivers security and stability updates. This policy applies to customer-managed deployments that you run in your own environment: private cloud, on-premises, and air-gapped installations. It does not cover the Overcut-hosted (SaaS) offering, which Overcut patches and operates directly. ## 1. Purpose & Scope This policy defines how Overcut identifies, triages, remediates, and ships fixes for security vulnerabilities in the Overcut platform, and the support commitments for released versions. It applies to customer-managed deployments, including private cloud, on-premises, and air-gapped environments, and covers Overcut-developed application code and its dependencies. This policy does not cover vulnerabilities in customer-managed infrastructure, including databases, message buses, object storage, Kubernetes clusters, operating systems, networking components, or third-party systems integrated by the customer. ## 2. Vulnerability Detection Overcut continuously performs automated security analysis throughout the software development lifecycle. | Control | Coverage | Frequency | | ------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------ | | Static application security testing (SAST) | Overcut-developed source code | Every pull request, primary branch push, and scheduled scans | | Software composition analysis (SCA) | Open-source dependencies | Continuous | | Infrastructure and configuration scanning | Infrastructure-as-Code and deployment configurations | Continuous | | Dependency monitoring | Third-party dependencies and container images | Continuous | Security findings are reviewed and triaged according to their severity and potential impact on customer environments. Overcut supplements automated scanning with manual security reviews, external security assessments, and customer-reported findings. ## 3. Security Reporting Security concerns, vulnerability disclosures, and suspected security issues may be reported to `support@overcut.ai`. All reports are reviewed and processed through Overcut's vulnerability management workflow. ## 4. Severity Classification Vulnerabilities are classified using CVSS v3.1 base scores, adjusted where appropriate for exploitability, exposure, and impact within the Overcut platform. | Severity | CVSS Range | Typical Characteristics | | -------- | ---------- | ---------------------------------------------------------------------------------------------- | | Critical | 9.0 - 10.0 | Remote code execution, authentication bypass, or significant data exposure with low complexity | | High | 7.0 - 8.9 | Significant impact requiring specific preconditions or attack paths | | Medium | 4.0 - 6.9 | Limited impact or increased attack complexity | | Low | 0.1 - 3.9 | Minimal impact or defense-in-depth improvements | ## 5. Remediation Timeframes Remediation time is measured from the point a vulnerability is confirmed and triaged to the point a fix is made available in a released version. | Severity | Target Remediation Timeframe | | -------- | ---------------------------- | | Critical | Within 7 days | | High | Within 30 days | | Medium | Within 90 days | | Low | Next scheduled release | Critical and High severity fixes may be released outside the regular release cycle and are backported to all supported versions within their support window. ## 6. Release Cadence Overcut follows Semantic Versioning (MAJOR.MINOR.PATCH). * Feature (minor) releases are typically published every one to three months. * Patch releases are published as needed to address defects and non-critical issues. * Security releases may be published independently of the regular release schedule whenever a validated security fix is available. Prior to general availability, releases may undergo internal validation and testing through release candidate versions. In exceptional circumstances involving actively exploited Critical vulnerabilities, Overcut may issue emergency hotfix releases outside normal release processes. ## 7. Version Support & End-of-Life Each Overcut release is supported for six months from its General Availability (GA) date. During the support period, Overcut provides: * Security patches * Critical bug fixes * Backported Critical and High severity security fixes Versions that have exceeded their six-month support period are considered End-of-Life (EOL) and no longer receive updates, patches, or backported fixes. Customers running EOL versions may be required to upgrade to a supported version before receiving newly released fixes or security updates. All previously released versions, including container images and Helm charts, are retained and remain available for installation or rollback purposes. Retention of release artifacts does not imply continued support or patch availability for EOL versions. Response times, support availability, and support service levels are governed by the applicable customer agreement or support plan and are outside the scope of this policy. ## 8. Patch Delivery Fixes are delivered as versioned, immutable release artifacts. ### Kubernetes / Helm deployments Customers apply updates using the corresponding released Helm chart version. Rollback can be performed by redeploying a previously released version. ### Docker Compose / standalone deployments Customers apply updates by pulling and deploying the released container image versions associated with the target release. ### Air-gapped deployments Customers may download released container images and deployment artifacts, transfer them into their internal environment, and publish them to their private registry. Updates and security patches can therefore be applied entirely within the customer network without requiring direct access to Overcut-hosted registries. ## 9. Customer Notification For security-relevant releases affecting customer-managed deployments, Overcut will: * Publish release notes describing relevant fixes and changes. * Notify affected customers through established customer communication channels. * Provide direct notification for Critical security issues together with recommended upgrade guidance where appropriate. Overcut manages externally reported vulnerabilities in accordance with responsible disclosure practices. ## 10. Policy Review This policy is reviewed periodically and updated as Overcut's products, security practices, and release processes evolve. This document describes Overcut's current practices and version lifecycle commitments. Unless explicitly incorporated into a customer agreement, order form, or support agreement, it does not create contractual obligations and may be updated from time to time. # Welcome to Overcut Source: https://docs.overcut.ai/docs/welcome The control plane for your self-improving software factory. Run agents that work in your Git, tickets, and CI with durable state, approvals, observability, audit trails, and sandboxed execution built in. Overcut is the control plane for a software factory: a delivery system where an event in your Git, tickets, or CI triggers a workflow, agents do the work, humans hold the approval gates, and the outcome writes back to the tools you already use. Retrospectives review completed runs and feed what they learned into the next ones, so the factory improves on its own. Pick a pillar below to read about that capability, or jump straight to the [Quick Start guides](/docs/quick-starts) to build your first workflow. Production-grade automation rather than scripts that drift. Trigger workflows from PR creation, issue labels, slash commands, mentions, or a schedule. Act on **GitHub**, **GitLab**, **Azure DevOps**, **Bitbucket**, **Jira**, **Linear**, and **ClickUp** through a single normalized event model. Managed cloud or on-prem. Your code stays in your environment, with role-based access, scoped tokens, and a full audit trail. [Read the security overview](/docs/privacy-and-security). Start from pre-configured agent types (Senior Developer, Code Reviewer, Tech Writer, Product Manager) or build a Custom agent with hand-picked tools. [See base agents](/docs/reference/base-agents). ## What you can build Overcut lets you build any agent that works inside your Git, tickets, or CI, connected to the rest of your ecosystem (logs, metrics, data warehouses, internal APIs). Every workflow runs with sandboxed execution, runtime governance, monitoring, and self-improvement built in. * **Automated SRE**: triage alerts, correlate logs and metrics, and open incident tickets with root cause analysis and a proposed fix. * **Always-current documentation**: keep docs, API references, and changelogs aligned with the code as PRs merge. * **Engineering standards enforcement**: hold every change to your framework versions, naming conventions, and architectural patterns. * **Security and performance governance**: scan PRs for vulnerabilities, regressions, and policy violations before they reach main. * **Codebase modernization**: run large-scale migrations across services, from framework upgrades to library swaps and deprecations. Browse the [Overcut Playbooks repository](https://github.com/overcut-ai/overcut-playbooks) for ready-to-use examples you can fork into your workspace. A Code Review run in progress: step list on the left, Code Reviewer agent reading the diff and reasoning about it in the log stream on the right. This is what makes the factory self-improving. As runs accumulate, Overcut runs a [retrospective](/docs/how-to/workflows/workflow-self-improvement) that reviews them and writes [workflow memories](/docs/how-to/workflows/workflow-memory) back to the agent, so it stops repeating mistakes and picks up the patterns specific to your team. Procedures your team wants every agent to follow live in [skills](/docs/reference/skills), versioned with the code they describe. ## Get started Step-by-step setups for the most common automations. Sign in to Overcut and connect your first repository. # Agent Run vs Multi-Agent Session Source: https://docs.overcut.ai/docs/workflows/agent-differences Understand the key differences between agent.run and agent.session actions to choose the right approach for your workflow needs. Understanding the differences between `agent.run` and `agent.session` is crucial for designing effective Overcut workflows. Each action type serves different purposes and has distinct characteristics that make them suitable for specific scenarios. *** ## Overview Overcut provides two distinct agent action types that serve different workflow needs: * **`agent.run`**: Single-agent execution for straightforward, non-interactive tasks * **`agent.session`**: Multi-agent coordination for complex, interactive workflows The choice between them depends on your task complexity, need for coordination, and whether you require ongoing interaction or iteration. Single agent, focused execution, quick completion Multiple agents, coordination, ongoing interaction *** ## Key Differences ### **Execution Model** #### Agent Run * **Single agent execution**: One specific agent handles the entire task * **Direct execution**: Agent works independently without coordination * **Linear workflow**: Task is completed in a single pass * **Background operation**: No ongoing conversation or user interaction #### Multi-Agent Session * **Multi-agent coordination**: Multiple agents work together under a coordinator * **Coordinated execution**: Coordinator agent orchestrates the workflow * **Iterative process**: Tasks can be refined and repeated * **Interactive session**: Maintains ongoing conversation and user feedback ### **Agent Behavior** #### Agent Run * **Works independently** without delegation capabilities * **Executes tools directly** to complete the assigned task * **Reports completion** when the task is finished * **Cannot coordinate** with other agents * **Operates in background** without user interaction #### Multi-Agent Session * **Breaks down complex tasks** into smaller, manageable pieces * **Delegates subtasks** to specialized agents * **Reviews results** and provides feedback to agents * **Manages iteration** and refinement cycles * **Communicates progress** to users throughout the process ### **Task Complexity** #### Agent Run * **Simple, focused tasks**: Single objective with clear requirements * **No iteration needed**: Task can be completed in one attempt * **Independent execution**: No coordination between different aspects * **Quick completion**: Designed for fast, straightforward operations #### Multi-Agent Session * **Complex, multi-faceted tasks**: Multiple objectives requiring different expertise * **Iteration and refinement**: Plans can be adjusted based on results * **Coordinated execution**: Different agents handle different aspects * **Extended duration**: Designed for longer, more complex workflows *** ## When to Use Each Action ### **Choose Agent Run When** * **Task is straightforward** and can be completed by one agent * **No coordination needed** between different areas of expertise * **Quick execution** is required without ongoing interaction * **Single output** is needed for downstream workflow steps * **Preparation tasks** that provide input for more complex workflows **Examples:** * Code analysis and preparation * Data extraction and parsing * Simple validation tasks * Generating plans or summaries * Single-purpose operations ### **Choose Multi-Agent Session When** * **Task requires multiple perspectives** or areas of expertise * **Coordination is essential** between different aspects * **Iteration and refinement** are needed * **User interaction** would be beneficial * **Complex problem-solving** that benefits from collaboration **Examples:** * Comprehensive code reviews * Architecture design and planning * Multi-repository analysis * Incident investigation and resolution * Feature implementation planning *** ## Workflow Design Patterns ### **Pattern 1: Preparation → Execution** Use `agent.run` to prepare input for complex `agent.session` workflows: ```yaml theme={"dark"} steps: - id: "prepare-analysis" name: "Prepare Analysis" action: "agent.run" params: agentId: "senior-developer" instruction: "Analyze the code changes and create a structured review plan" - id: "execute-review" name: "Execute Code Review" action: "agent.session" params: goal: "Perform comprehensive code review based on the prepared plan" agentIds: ["code-reviewer", "security-expert"] instruction: "Follow this review plan: {{outputs.prepare-analysis.message}}" ``` ### **Pattern 2: Multi-Stage Processing** Chain multiple `agent.run` steps for data processing pipelines: ```yaml theme={"dark"} steps: - id: "extract-data" name: "Extract Data" action: "agent.run" params: agentId: "data-analyst" instruction: "Extract key metrics from the repository analysis" - id: "analyze-trends" name: "Analyze Trends" action: "agent.run" params: agentId: "data-scientist" instruction: "Analyze trends in the extracted data: {{outputs.extract-data.message}}" - id: "generate-report" name: "Generate Report" action: "agent.run" params: agentId: "technical-writer" instruction: "Create a comprehensive report based on the trend analysis: {{outputs.analyze-trends.message}}" ``` ### **Pattern 3: Complex Coordination** Use `agent.session` for tasks requiring multiple perspectives: ```yaml theme={"dark"} steps: - id: "architecture-design" name: "Architecture Design Session" action: "agent.session" params: goal: "Design the system architecture for the new microservices platform" agentIds: ["architect", "senior-developer", "security-expert", "devops-engineer"] exitCriteria: timeLimit: maxDurationMinutes: 120 userSignals: explicit: ["/design-complete", "/architecture-ready"] ``` *** ## Performance and Resource Considerations ### **Agent Run** **Advantages:** * **Faster execution**: Single agent, no coordination overhead * **Lower resource usage**: No session management or ongoing conversation * **Predictable timing**: Linear execution with known completion time * **Easier debugging**: Single execution path to trace **Limitations:** * **Single perspective**: Limited to one agent's expertise * **No iteration**: Cannot refine approach based on results * **Limited complexity**: Not suitable for multi-faceted tasks ### **Multi-Agent Session** **Advantages:** * **Multiple perspectives**: Leverages different areas of expertise * **Iterative improvement**: Can refine and adjust approach * **User interaction**: Supports ongoing feedback and guidance * **Complex problem-solving**: Handles multi-faceted challenges **Limitations:** * **Longer execution time**: Coordination and iteration add overhead * **Higher resource usage**: Session management and ongoing conversation * **Complex debugging**: Multiple execution paths and agent interactions * **Potential for coordination issues**: Depends on coordinator effectiveness *** ## Decision Framework ### **Step-by-Step Decision Process** 1. **Assess Task Complexity** * Is this a single, focused task? * Does it require multiple areas of expertise? * Is coordination between different aspects needed? 2. **Consider Iteration Needs** * Can the task be completed in one attempt? * Would refinement and adjustment be beneficial? * Is ongoing user feedback valuable? 3. **Evaluate Resource Constraints** * What's the acceptable execution time? * Are there resource limitations? * What's the priority of the task? 4. **Determine User Interaction** * Is ongoing user guidance needed? * Would real-time feedback improve results? * Is this a collaborative or autonomous task? *** ## Best Practices ### **For Agent Run** 1. **Keep tasks focused**: Single objective with clear requirements 2. **Provide clear instructions**: Detailed, actionable guidance 3. **Choose appropriate agents**: Match agent skills to task requirements 4. **Optimize output**: Structure output for downstream consumption 5. **Handle errors gracefully**: Plan for potential failures ### **For Multi-Agent Session** 1. **Define clear goals**: Specific, measurable objectives 2. **Choose complementary agents**: Diverse expertise without overlap 3. **Set appropriate exit criteria**: Time limits and user signals 4. **Enable user interaction**: Use comment listening and session persistence 5. **Monitor coordination**: Ensure effective delegation and feedback *** ## Next Steps Now that you understand the differences between `agent.run` and `agent.session`, explore these related topics: * **[Agent Run Action](/docs/workflows/agent-run)**: Learn about single-agent execution * **[Multi-Agent Session Action](/docs/workflows/agent-session)**: Learn about multi-agent coordination * **[Building Blocks](/docs/building-blocks)**: Explore other workflow actions and components * **[Quick Starts](/docs/quick-starts)**: See complete workflow examples Ready to design your workflows? Start with `agent.run` for simple tasks, then evolve to `agent.session` when you need coordination and collaboration. The key is matching the action type to your specific requirements and constraints. # Agent Run Action Source: https://docs.overcut.ai/docs/workflows/agent-run Learn how to use the agent.run action to execute single AI agents for straightforward, non-interactive tasks in your Overcut workflows. The `agent.run` action executes a single AI agent to perform a specific, straightforward task within your workflow. It's designed for simple, non-interactive operations that don't require iteration or user feedback, making it perfect for preparation steps, analysis tasks, and single-purpose operations. *** ## Overview The `agent.run` action is ideal for tasks where you need a single agent to complete a specific job and provide output that can be used by subsequent workflow steps. Unlike `agent.session`, it doesn't maintain an ongoing conversation or coordinate multiple agents - it simply runs the specified agent with your instructions and completes the task. Runs one specific agent with focused instructions for a single task. Completes the task without waiting for user input or maintaining a session. Optimized for quick, straightforward tasks that don't require iteration. Provides structured output that can be referenced by subsequent workflow steps. *** ## When to Use Agent Run ### **Perfect For** * **Preparation tasks**: Analyzing code, generating plans, extracting information * **Simple analysis**: Code review preparation, dependency analysis, configuration parsing * **Data extraction**: Parsing logs, extracting metrics, summarizing content * **Single-purpose operations**: Formatting, validation, transformation tasks * **Quick decisions**: Simple classification, routing, or decision-making ### **Not Suitable For** * **Complex, multi-step tasks** that require coordination between multiple agents * **Interactive workflows** that need user feedback or ongoing conversation * **Tasks requiring iteration** or multiple rounds of refinement * **Multi-agent collaboration** where different agents need to work together *** ## Basic Usage ### Simple Agent Execution The most basic usage runs a single agent: ```yaml theme={"dark"} steps: - id: "analyze-code" name: "Analyze Code" action: "agent.run" params: agentId: "senior-developer" ``` ### With Instructions Provide specific instructions for the agent: ```yaml theme={"dark"} steps: - id: "prepare-review" name: "Prepare Code Review Plan" action: "agent.run" params: agentId: "senior-developer" instruction: "Analyze the code changes and create a structured review plan with priority items" ``` ### Using Dynamic Values Reference values from previous steps, triggers, or context parameters: ```yaml theme={"dark"} steps: - id: "analyze-issue" name: "Analyze Issue" action: "agent.run" params: agentId: "product-manager" instruction: "Analyze the issue '{{trigger.issue.title}}' at {{params.review_depth}} depth and provide technical recommendations" ``` In Workflow Builder, type `{{params.` in **Instructions** to pick a [context parameter](/docs/reference/context-parameters) visible to the project. The agent picker lists the project's own agents under **Project** and shared agents from the [Workspace Library](/docs/reference/workspace-library) under **Workspace library**. *** ## Parameters ### Required Parameters The unique identifier of the agent to execute. This agent will be responsible for completing the specified task. Specific instructions for the agent to follow. This should be clear, actionable guidance for the task at hand. Trigger data, step outputs, and `{{params.}}` references are rendered before the agent starts. A value set on the agent itself changes what this step receives, while other steps in the same run keep the less specific value. See [Context Parameters](/docs/reference/context-parameters#how-values-resolve). *** ## How It Works ### 1. Agent Selection The system loads the specified agent configuration, including: * **Selected agent** (e.g., Senior Developer, Product Manager) * **Available tools** and capabilities * **Custom instructions** and configuration ### 2. Task Execution The agent executes the task by: * **Processing instructions** and understanding the requirements * **Using available tools** to gather information and perform actions * **Generating output** based on the task requirements * **Completing execution** when the task is finished ### 3. Output Generation The agent provides structured output that can include: * **Text responses** with analysis, recommendations, or results * **Structured data** in JSON format for downstream processing * **Tool outputs** from any tools used during execution * **Status information** about task completion ### 4. Workflow Continuation The workflow continues to the next step with: * **Agent output** available for reference * **Context preserved** for subsequent steps * **No ongoing session** to maintain *** ## Complete Examples ### Code Review Preparation Prepare a structured review plan for a pull request: ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "{{trigger.repository.fullName}}" branch: "{{trigger.pullRequest.headBranch}}" - id: "prepare-review-plan" name: "Prepare Review Plan" action: "agent.run" params: agentId: "senior-developer" instruction: "Analyze the code changes and create a numbered list of review items, prioritizing security, performance, and maintainability concerns" - id: "execute-review" name: "Execute Code Review" action: "agent.session" params: goal: "Perform comprehensive code review based on the prepared plan" agentIds: ["code-reviewer", "security-expert"] instruction: "Follow the review plan: {{outputs.prepare-review-plan}}" ``` ### Issue Analysis Analyze a Jira issue and provide technical context: ```yaml theme={"dark"} steps: - id: "analyze-issue" name: "Analyze Issue" action: "agent.run" params: agentId: "product-manager" instruction: "Analyze the issue '{{trigger.issue.title}}' and provide: 1) Technical complexity assessment, 2) Recommended approach, 3) Potential risks" - id: "plan-implementation" name: "Plan Implementation" action: "agent.session" params: goal: "Create detailed implementation plan based on issue analysis" agentIds: ["senior-developer", "architect"] instruction: "Use this analysis to create the plan: {{outputs.analyze-issue}}" ``` ### Dependency Analysis Analyze project dependencies and identify updates: ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "{{trigger.repository.fullName}}" - id: "analyze-dependencies" name: "Analyze Dependencies" action: "agent.run" params: agentId: "senior-developer" instruction: "Analyze package.json and identify outdated dependencies, security vulnerabilities, and recommended updates" - id: "create-update-plan" name: "Create Update Plan" action: "agent.run" params: agentId: "product-manager" instruction: "Based on the dependency analysis, create a prioritized update plan with risk assessment" ``` *** ## Output and Context ### Step Output The `agent.run` action provides output that can be used by subsequent steps: The main output content from the agent, typically containing the task results, analysis, or generated content. ### Available Variables Use these variables in subsequent steps: * **`{{outputs.analyze-code.message}}`**: Main output from the agent ### Template Examples **Basic Output Reference:** ```yaml theme={"dark"} instruction: "Use this analysis: {{outputs.analyze-code.message}}" ``` *** ## Integration with Other Actions ### Following with Multi-Agent Session Use `agent.run` to prepare input for more complex `agent.session` workflows: ```yaml theme={"dark"} steps: - id: "prepare-plan" name: "Prepare Plan" action: "agent.run" params: agentId: "senior-developer" instruction: "Create a structured plan for implementing the feature described in the issue" - id: "execute-implementation" name: "Execute Implementation" action: "agent.session" params: goal: "Implement the feature according to the prepared plan" agentIds: ["frontend-developer", "backend-developer", "qa-engineer"] instruction: "Follow this implementation plan: {{outputs.prepare-plan.message}}" ``` ### Data Processing Pipeline Chain multiple `agent.run` steps for data processing: ```yaml theme={"dark"} steps: - id: "extract-data" name: "Extract Data" action: "agent.run" params: agentId: "data-analyst" instruction: "Extract key metrics from the repository analysis" - id: "analyze-trends" name: "Analyze Trends" action: "agent.run" params: agentId: "data-scientist" instruction: "Analyze trends in the extracted data: {{outputs.extract-data.message}}" - id: "generate-report" name: "Generate Report" action: "agent.run" params: agentId: "technical-writer" instruction: "Create a comprehensive report based on the trend analysis: {{outputs.analyze-trends.message}}" ``` *** ## Best Practices ### 1. Keep Instructions Clear and Focused * **Single purpose**: Each `agent.run` step should have one clear objective * **Specific guidance**: Provide detailed, actionable instructions * **Expected output**: Clarify what format or structure you expect * **Context**: Include relevant information from previous steps ### 2. Choose the Right Agent * **Match skills**: Select agents with appropriate expertise for the task * **Consider tools**: Ensure the agent has access to necessary tools * **Base agent type**: Use built-in agent types that match your needs * **Custom agents**: Leverage specialized agents for domain-specific tasks ### 3. Optimize for Output Reusability * **Structured output**: Request output in formats that downstream steps can use * **Clear formatting**: Ask for numbered lists, JSON, or other structured formats * **Key information**: Focus on actionable insights and data * **Error handling**: Consider what happens if the agent fails ### 4. Position in Workflow * **Early steps**: Use for preparation and analysis tasks * **Data processing**: Chain multiple steps for complex data workflows * **Input preparation**: Prepare data for more complex `agent.session` steps * **Validation**: Use for checking and validating workflow state *** ## Next Steps Now that you understand the `agent.run` action, explore these related topics: * **[Multi-Agent Session Action](/docs/workflows/agent-session)**: Learn about multi-agent, interactive workflows * **[Agent Differences](/docs/workflows/agent-differences)**: Understand when to use each agent action type * **[Base Agent Types](/docs/reference/base-agents)**: Compare base agent types and their default toolsets * **[Agent Tools Reference](/docs/reference/tools)**: See all available tools and which agents include them * **[Context Parameters](/docs/reference/context-parameters)**: Reuse values across projects, repositories, and agents * **[Building Blocks](/docs/building-blocks)**: Explore other workflow actions and components * **[Execute CI Workflow](/docs/workflows/ci-execute-workflow)**: Learn how to trigger external CI pipelines directly from Overcut * **[Quick Starts](/docs/quick-starts)**: See complete workflow examples Ready to automate simple tasks? Start with `agent.run` for straightforward operations, then combine it with other actions to build powerful, automated workflows. # Multi-Agent Session Action Source: https://docs.overcut.ai/docs/workflows/agent-session Learn how to use the agent.session action to create interactive, multi-agent workflows with coordination, iteration, and user feedback capabilities. The `agent.session` action creates an interactive, multi-agent session where multiple AI agents collaborate to achieve complex goals. It features a coordinator agent that orchestrates the work, delegates tasks to specialized agents, and maintains an ongoing conversation that can include user feedback and iteration. *** ## Overview The `agent.session` action is designed for complex, multi-step tasks that require coordination between different agents, iteration, and ongoing user interaction. Unlike `agent.run`, it maintains an active session where agents can work together, break down complex problems, and adapt their approach based on feedback and results. Multiple agents work together with a coordinator orchestrating the workflow. Maintains ongoing conversation with options for user feedback and iteration. Breaks down complex problems into smaller, manageable chunks. Supports iteration, refinement, and adaptive problem-solving approaches. *** ## When to Use Multi-Agent Session ### **Perfect For** * **Complex, multi-step tasks** that require different types of expertise * **Interactive workflows** that benefit from user feedback and iteration * **Collaborative problem-solving** where multiple agents need to work together * **Tasks requiring coordination** between different aspects (frontend, backend, testing) * **Iterative development** where plans need to be refined based on results ### **Not Suitable For** * **Simple, single-purpose tasks** that can be completed by one agent * **Quick, straightforward operations** that don't require coordination * **Tasks with clear, linear execution** paths *** ## Basic Usage ### Simple Multi-Agent Session The most basic usage creates a session with multiple agents: ```yaml theme={"dark"} steps: - id: "collaborative-task" name: "Collaborative Task" action: "agent.session" params: goal: "Complete the specified task using multiple agents" agentIds: ["senior-developer", "product-manager"] ``` ### With Exit Criteria Define when the session should complete: ```yaml theme={"dark"} steps: - id: "code-review-session" name: "Code Review Session" action: "agent.session" params: goal: "Perform comprehensive code review" agentIds: ["code-reviewer", "security-expert", "performance-expert"] exitCriteria: timeLimit: maxDurationMinutes: 30 userSignals: explicit: ["/done", "review-complete"] ``` ### With Session Management Options Control session behavior and user interaction: ```yaml theme={"dark"} steps: - id: "feature-planning" name: "Feature Planning Session" action: "agent.session" params: goal: "Plan and design the new feature implementation" agentIds: ["product-manager", "senior-developer", "architect"] keepSessionOpenForComments: true listenToComments: true ``` *** ## Parameters ### Required Parameters The main objective or goal for the session. This should clearly describe what the agents are trying to accomplish together. Array of agent IDs that will participate in the session. These agents will collaborate under the coordination of a coordinator agent. Specific instructions for the coordinator agent to follow. This can include instructions on how to break down the goal into smaller tasks, how to delegate tasks to the other agents, how to handle user comments, and how to handle the session overall. You can include a [context parameter](/docs/reference/context-parameters) as `{{params.}}`; the **Instructions** editor offers completion, the **Session Goal** field does not. Participating agents can come from the project or from the [Workspace Library](/docs/reference/workspace-library). Each agent's own instructions resolve context parameters with that agent's values, so two agents in one session can receive different values for the same key. ### Optional Parameters Maximum session duration in minutes. Default: 10 minutes. Array of explicit user commands that will complete the session (e.g., \["/done", "/complete", "thanks"]). Whether the session should listen for and respond to user comments. Default: true. Whether to keep the session open for comments after completion. Default: false. *** ## Exit Criteria Configuration ### Time Limits Set maximum session duration: ```yaml theme={"dark"} exitCriteria: timeLimit: maxDurationMinutes: 45 # Session will complete after 45 minutes ``` ### User Signals Define explicit commands that complete the session. These commands can be added to a comment on the issue or PR, to signal to the coordinator agent that the session is complete, or to complete the session. ```yaml theme={"dark"} exitCriteria: userSignals: explicit: ["/done", "/complete", "thanks", "good job"] ``` ### Combined Criteria Use both time and user signals: ```yaml theme={"dark"} exitCriteria: timeLimit: maxDurationMinutes: 60 userSignals: explicit: ["/done", "/finish", "complete"] ``` *** ## How It Works ### 1. Session Initialization The system creates a multi-agent session with: * **Coordinator agent** that manages the overall workflow * **Specialized agents** with different skills and expertise * **Session context** that maintains state and conversation history ### 2. Goal Analysis and Planning The coordinator agent: * **Analyzes the goal** and breaks it down into manageable tasks * **Identifies which agents** are best suited for each task * **Creates an execution plan** with clear steps and dependencies ### 3. Task Delegation and Execution The coordinator: * **Delegates specific tasks** to appropriate agents * **Manages task dependencies** and execution order * **Coordinates results** between different agents * **Handles task failures** and retries ### 4. Iteration and Refinement The session supports: * **Iterative execution** where plans are refined based on results * **User feedback** that can influence the approach * **Adaptive problem-solving** that adjusts to new information ### 5. Session Completion The session completes when: * **All tasks are finished** and the goal is achieved * **Time limit is reached** (if configured) * **User signals completion** (if configured) * **Exit criteria are met** *** ## Complete Examples ### Code Review Workflow Multi-agent code review with different expertise areas: ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "{{trigger.repository.fullName}}" branch: "{{trigger.pullRequest.headBranch}}" - id: "code-review-session" name: "Code Review Session" action: "agent.session" params: goal: "Perform comprehensive code review covering security, performance, maintainability, and testing" agentIds: ["code-reviewer", "security-expert", "performance-expert", "qa-engineer"] exitCriteria: timeLimit: maxDurationMinutes: 45 userSignals: explicit: ["/done", "review-complete", "thanks"] keepSessionOpenForComments: true listenToComments: true ``` ### Feature Implementation Planning Collaborative feature planning across multiple domains: ```yaml theme={"dark"} steps: - id: "feature-planning-session" name: "Feature Planning Session" action: "agent.session" params: goal: "Plan and design the new user authentication feature, including frontend, backend, database, and security considerations" agentIds: ["product-manager", "frontend-developer", "backend-developer", "security-expert", "database-architect"] exitCriteria: timeLimit: maxDurationMinutes: 90 userSignals: explicit: ["/complete", "plan-ready", "done"] keepSessionOpenForComments: true listenToComments: true ``` ### Bug Investigation and Resolution Multi-agent bug investigation with different perspectives: ```yaml theme={"dark"} steps: - id: "bug-investigation" name: "Bug Investigation Session" action: "agent.session" params: goal: "Investigate the reported bug, identify root cause, and create a comprehensive fix plan" agentIds: ["debugging-expert", "frontend-developer", "backend-developer", "qa-engineer", "senior-developer"] exitCriteria: timeLimit: maxDurationMinutes: 60 userSignals: explicit: ["/resolved", "investigation-complete", "fix-ready"] ``` ## Integration with Other Actions ### Following Repository Identification Use `repo.identify` to determine which repositories to work with: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Repositories" action: "repo.identify" params: maxResults: 3 minConfidence: 0.7 - id: "multi-repo-analysis" name: "Multi-Repository Analysis" action: "agent.session" params: goal: "Analyze the identified repositories for cross-dependencies and integration points" agentIds: ["architect", "senior-developer", "devops-engineer"] instruction: "Focus on repositories: {{outputs.identify-repos.[0].repoFullName}}, {{outputs.identify-repos.[1].repoFullName}}" ``` ### Preparation with Agent Run Use `agent.run` to prepare input for complex sessions: ```yaml theme={"dark"} steps: - id: "prepare-analysis" name: "Prepare Analysis" action: "agent.run" params: agentId: "senior-developer" instruction: "Analyze the code changes and create a structured review plan" - id: "execute-review" name: "Execute Code Review" action: "agent.session" params: goal: "Perform comprehensive code review based on the prepared plan" agentIds: ["code-reviewer", "security-expert"] instruction: "Follow this review plan: {{outputs.prepare-analysis.message}}" ``` *** ## Best Practices ### 1. Choose the Right Agent Mix * **Diverse expertise**: Include agents with different skills and perspectives * **Role clarity**: Ensure each agent has a clear, distinct role * **Complementary skills**: Agents should work together, not duplicate each other * **Specialized knowledge**: Use domain-specific agents for technical areas ### 2. Define Clear Goals * **Specific objectives**: Make goals concrete and measurable * **Scope boundaries**: Define what's included and what's not * **Success criteria**: Clarify how you'll know when the goal is achieved * **Context information**: Provide relevant background and constraints ### 3. Configure Appropriate Exit Criteria * **Time limits**: Set realistic timeframes for complex tasks * **User signals**: Define clear commands for manual completion * **Progress indicators**: Consider how to track completion progress * **Fallback mechanisms**: Plan for unexpected completion scenarios ### 4. Optimize Session Management * **User interaction**: Enable comment listening for better collaboration * **Session persistence**: Use keepSessionOpenForComments for post-completion feedback * **Iteration support**: Allow for refinement and improvement cycles * **Error handling**: Plan for agent failures and session recovery *** ## Next Steps Now that you understand the `agent.session` action, explore these related topics: * **[Interactive Sessions Reference](/docs/reference/interactive-sessions)**: Deep dive into session behavior, comment routing, and configuration options * **[Agent Run Action](/docs/workflows/agent-run)**: Learn about single-agent, non-interactive execution * **[Agent Differences](/docs/workflows/agent-differences)**: Understand when to use each agent action type * **[Context Parameters](/docs/reference/context-parameters)**: Reuse values and understand per-agent resolution * **[Building Blocks](/docs/building-blocks)**: Explore other workflow actions and components * **[Execute CI Workflow](/docs/workflows/ci-execute-workflow)**: Trigger external CI jobs as part of multi-agent sessions * **[Quick Starts](/docs/quick-starts)**: See complete workflow examples Ready to create collaborative workflows? Start with `agent.session` for complex, multi-agent tasks that require coordination, iteration, and user interaction. # Execute CI Workflow Action Source: https://docs.overcut.ai/docs/workflows/ci-execute-workflow Trigger external CI/CD pipelines, such as GitHub Actions, directly from your Overcut workflows using the `ci.executeWorkflow` action. The `ci.executeWorkflow` action lets an Overcut workflow fire an **external CI/CD workflow** (starting with GitHub Actions support, more providers coming soon). You can kick-off builds, tests, deployments or any custom pipeline, either *fire-and-forget* or while **waiting for completion** and capturing the result. *** ## Overview When your automation needs to interact with an existing CI process (for example, to run an integration-test suite before continuing) you can add a `ci.executeWorkflow` step. The step calls the CI provider's API, passes parameters and (optionally) pauses execution until the external workflow finishes. Provide repository, workflow file and ref; Overcut handles authentication. Choose to block the workflow until success/failure, or continue immediately. Pass trigger data or previous step outputs as inputs to the CI job. Step status is *Waiting for External* while the CI job is running. *** ## Parameters ### Required Parameters Repository owning the CI workflow, in `owner/repo` format. File name (e.g., `.github/workflows/test.yml`) **or** numeric workflow ID of the job to run. ### Optional Parameters Git reference (branch, tag or SHA) to use when triggering the workflow.
Defaults to the repository's default branch. If `true`, the Overcut step waits until the external workflow completes and sets its final status accordingly. When enabled, the step enters **Waiting for External** state until completion. Key/value map of input parameters defined by the target workflow. Supports string, number and boolean values. String values can use template expressions, including a [context parameter](/docs/reference/context-parameters) such as `{{params.deploy_environment}}`.
If the target workflow defines a `correlation_id` input, pass a unique value (for example `{{stepId}}`) so Overcut can reliably identify the triggered run. See [Identifying the Triggered Run](#identifying-the-triggered-run). *** ## Identifying the Triggered Run GitHub's workflow dispatch API does not return a run ID by default. After triggering, Overcut searches recent runs to find the one it just started so it can track its status. For guaranteed identification, declare a `correlation_id` input in your GitHub Actions workflow: ```yaml theme={"dark"} # .github/workflows/integration.yml on: workflow_dispatch: inputs: correlation_id: required: false type: string ``` Then pass a unique value from the Overcut step. The `{{stepId}}` expression resolves to a unique identifier for the current step execution: ```yaml theme={"dark"} inputs: correlation_id: "{{stepId}}" ``` Overcut matches the triggered run by its `correlation_id` input and tracks exactly that run. The Correlation ID also appears in the step logs. If the target workflow does not define a `correlation_id` input, Overcut falls back to the most recent run triggered on the same branch by the connected account. This works for occasional triggers, but it can attach to the wrong run when the same workflow is triggered concurrently. Use `correlation_id` whenever concurrent triggers are possible. *** ## Step Configuration In the Workflow Builder: 1. Add a new **Action** step and select **Execute CI Workflow**. 2. Enter the **repository** and **workflow file**. 3. (Optional) Specify **ref**, **inputs** and **wait for completion**. 4. Connect subsequent steps. If you enabled **wait for completion**, downstream steps will run only after the CI job succeeds (or fails based on your on-failure policy). Execute CI Workflow form *** ## Example ```yaml theme={"dark"} steps: - id: "run-tests" name: "Run Integration Tests" action: "ci.executeWorkflow" params: repoFullName: "acme/monolith" workflowId: ".github/workflows/integration.yml" ref: "{{trigger.pullRequest.headSha}}" waitForCompletion: true inputs: environment: "staging" runE2E: true correlation_id: "{{stepId}}" ``` The step triggers the specified GitHub Actions workflow on the PR's commit and pauses execution. While the CI job runs, the step status shows **Waiting for External**. Once finished, Overcut records the result and continues the workflow. *** ## Related Status | Status | When It Appears | | ------------------------ | ------------------------------------------------------------------------------------------- | | **Waiting for External** | The step is waiting for an external system (e.g., CI workflow) to finish before proceeding. | Downstream steps see `{{outputs.run-tests.status}}` reflecting `success`, `failure` or `cancelled` (when `waitForCompletion: true`). *** ## See Also * [Triggers](/docs/workflows/triggers) – start workflows from PR events or slash commands * [Git Clone](/docs/workflows/git-clone) – provide code to your CI workflows * [Integrations: GitHub](/docs/integrations/github) – configuring repository access tokens * [Context Parameters](/docs/reference/context-parameters): reusable values for inputs such as the target environment # Custom Events in Workflows Source: https://docs.overcut.ai/docs/workflows/custom-events Trigger workflows from a workspace Custom Event, filter on the incoming payload, and access event data in downstream steps. Once a workspace admin has [defined a Custom Event](/docs/integrations/custom-events) and the event's allowlist includes your project, the event is available in your workflow's trigger picker exactly like any built-in trigger. This page covers the workflow-author side: picking the event, filtering on payload fields, and reading event data in agents and actions. For setup, authentication, and the webhook contract, see [Custom Events (Integrations)](/docs/integrations/custom-events) and the [API reference](/docs/reference/custom-events-api). ## Pick a Custom Event in the trigger picker Open any workflow in the current project and select its Trigger container. Click Add trigger (or select an existing trigger card) to open the Properties panel. Open the Trigger event dropdown. Below the built-in groups (Issue, Pull Request, CI Workflow, Mention, Channel Message, Schedule, Slash Command, Manual), Custom Events appear grouped by their Category. Pick the event slug you want (for example, deployment\_completed under Deployments). Use the conditions builder to filter on payload fields. See Filter on payload fields below. Only Custom Events whose allowlist includes the current project appear in that project's picker. If you expect an event to be available and it isn't, ask a workspace admin to add the project to the event's allowlist on the [Custom Events page](/docs/integrations/custom-events#change-scope-or-rename). ## Filter on payload fields The webhook body and any query-string parameters are exposed to trigger conditions under `payload.*`. Use dot notation for nested keys. The `payload.*` scope is specific to Custom Events. Built-in event triggers (issue, pull request, CI workflow, etc.) match on `context.*` fields like `context.actor.type` or `context.repository.name` instead. The dispatcher also mirrors the body at `context.payload.*`, so `context.payload.environment` and `payload.environment` resolve to the same value. For a payload like: ```json theme={"dark"} { "environment": "production", "status": "success", "service": { "name": "api", "region": "us-east-1" } } ``` You can write conditions like: | Field | Operator | Value | Matches | | ------------------------ | ------------ | ------------ | ------------------------- | | `payload.environment` | `equals` | `production` | only production | | `payload.status` | `notEquals` | `cancelled` | anything except cancelled | | `payload.service.name` | `equals` | `api` | only the api service | | `payload.service.region` | `startsWith` | `us-` | any US region | Combine multiple conditions with `and` / `or` groups. The four well-known meta fields (`objectName`, `objectNumber`, `objectUrl`, `actor`) are also readable from `payload.*` even though Overcut also uses them for the run-list display. Comparisons are case-insensitive: `payload.status == "Success"` matches `"SUCCESS"` and `"success"`. Missing fields short-circuit to a non-match: a condition on `payload.service.region` against a payload that has no `service` object simply does not fire. The full list of operators (`equals`, `notEquals`, `contains`, `notContains`, `startsWith`, `endsWith`, `matches`, `in`, `notIn`) is documented in the [Trigger Execution reference](/docs/reference/trigger-execution). ## Improve the run's appearance Without any payload hints, a Custom Event run shows the event's slug as its label (for example, `deployment_completed`) and has no click-through link. To make runs scannable, ask the sender to include the four well-known meta fields: | Caller field | Sets | Example | | -------------- | -------------------------------- | ------------------------------ | | `objectName` | Run label in the runs list | `"Deploy #1234 to production"` | | `objectNumber` | Object number badge | `"1234"` | | `objectUrl` | Click-through link from the run | URL back to the source system | | `actor` | The run's actor (shown as a Bot) | `"deploy-bot"` | These are read by Overcut **and** still available to your conditions, so a single field like `objectName: "Deploy #1234 to production"` controls both the display and any rule that filters on it. See [Improve how runs appear in Overcut](/docs/integrations/custom-events#improve-how-runs-appear-in-overcut) for the sender-side details. ## Access event data in downstream steps Once a trigger fires, the standard `trigger.*` template variables are populated from the well-known meta fields: ```handlebars theme={"dark"} {{trigger.eventType}} → "custom_event" {{trigger.triggerObjectName}} → "Deploy #1234 to production" {{trigger.triggerObjectNumber}} → "1234" {{trigger.triggerObjectUrl}} → "https://github.com/..." {{trigger.actor.login}} → "deploy-bot" ``` The full payload is available under `trigger.payload.*`: ```handlebars theme={"dark"} {{trigger.payload.environment}} → "production" {{trigger.payload.service.name}} → "api" ``` Use these in agent prompts, action parameters, conditional steps, and step outputs exactly like any other trigger variable. See the [Event Context Reference](/docs/reference/event-context#custom-event-properties) for the full list of fields available to a Custom Event workflow. ## One event, many workflows The same Custom Event slug can drive any number of workflows in any allowed project. Each workflow evaluates its own trigger conditions independently against the same incoming payload. This is the standard pattern: define one `deployment_completed` event in the workspace, then have a "post to Slack" workflow, an "open changelog draft" workflow, and a "run smoke tests" workflow each filter for the deployments they care about. ## Concurrency: avoid duplicate runs By default, every webhook call produces its own workflow execution: ten POSTs in a second produce ten runs (and ten parallel queued events per matching workflow). When that is wrong, the sender can pass `?lockKey=` to serialize: * Requests sharing the same `(event, lockKey)` run one at a time. * Within a short dedupe window, repeats collapse into a single queued execution per workflow. * Different `lockKey` values run in parallel. This is configured on the **sender** side, not in the workflow. See [Serialize concurrent calls with lockKey](/docs/integrations/custom-events#serialize-concurrent-calls-with-lockkey). ## Related Create an event, get a webhook URL, pick an auth mode, and wire your third-party tools. Full request and response contract: every header, query param, error code, and limit. All `trigger.*` template variables, including the Custom Event fields. Operator list, event merging, priority queuing, and the Custom Event lock-key formula. # Git Clone Action Source: https://docs.overcut.ai/docs/workflows/git-clone Learn how to use the git.clone action to clone repositories in your Overcut workflows with advanced options for performance and customization, including multi-repository support and dynamic chaining. The `git.clone` action is one of the most fundamental building blocks in Overcut workflows. It allows you to clone Git repositories into the workflow execution environment, providing agents and subsequent steps with access to your source code for analysis, modification, or review. With advanced multi-repository support, you can dynamically clone multiple repositories based on intelligent identification or clone them explicitly. *** ## Overview The `git.clone` action performs Git clone operations with intelligent caching, branch management, and advanced clone options. It supports both single and multi-repository workflows, with seamless integration with the `repo.identify` action for dynamic repository selection. Clone multiple repositories in a single step, either from dynamic identification or explicit specification. Seamlessly chain with repo.identify to automatically clone all relevant repositories for your workflow context. Automatically uses cached repositories when possible, dramatically reducing clone time for subsequent runs. Support for shallow clones, sparse checkouts, partial clones, and more Git optimization features. *** ## Multi-Repository Workflows ### Dynamic Repository Cloning The most powerful pattern combines `repo.identify` with `git.clone` to automatically clone all relevant repositories: ```yaml theme={"dark"} steps: # Step 1: Identify relevant repositories - id: "identify-repos" name: "Identify Relevant Repositories" action: "repo.identify" params: maxResults: 3 minConfidence: 0.7 identificationHints: "Focus on frontend, backend, and shared libraries" # Step 2: Clone all identified repositories - id: "clone-repos" name: "Clone All Relevant Repositories" action: "git.clone" params: repoFullName: "{{outputs.identify-repos}}" branch: "main" # Step 3: Analyze across all repositories - id: "analyze-code" name: "Multi-Repository Analysis" action: "agent.session" params: goal: "Analyze the issue across all relevant codebases" instruction: "Review the code in all cloned repositories: {{outputs.identify-repos}}" ``` ### Single Repository from Identification Clone only the top-ranked repository from identification: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Primary Repository" action: "repo.identify" params: maxResults: 1 minConfidence: 0.8 - id: "clone-primary" name: "Clone Primary Repository" action: "git.clone" params: repoFullName: "{{outputs.identify-repos.[0].repoFullName}}" branch: "{{trigger.pullRequest.headBranch}}" ``` *** ## Basic Usage ### Simple Repository Clone The most basic usage clones a repository using its default branch: ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "owner/repository-name" ``` ### Clone Specific Branch Clone a specific branch instead of the default: ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "owner/repository-name" branch: "feature/new-feature" ``` ### Using Dynamic Values Reference values from the trigger or previous steps: ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "{{trigger.repository.fullName}}" branch: "{{trigger.pullRequest.headBranch}}" ``` *** ## Parameters ### Required Parameters Repository specification that can be: * **Single repository**: `"owner/repo"` * **Dynamic from identification**: `"{\{outputs.identify-repos\}}"` (clones all identified repositories) * **Specific from identification**: `"{\{outputs.identify-repos.[0].repoFullName\}}"` (clones first identified repository) * **Trigger-based**: `"{\{trigger.repository.fullName\}}"` ### Optional Parameters Specific branch to checkout. If not specified, the repository's default branch will be used. Can use template expressions like `"{{trigger.pullRequest.headBranch}}"`. Advanced Git clone configuration options for fine-grained control over the clone operation. *** ## Clone Options The `cloneOptions` parameter provides fine-grained control over the clone operation: ### Depth Control Limit the clone depth for faster downloads: ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "{{outputs.identify-repos}}" cloneOptions: depth: 1 # Clone only the latest commit ``` **Available depth values:** * `1`: Latest commit only (fastest, minimal history) * `0`: Full history (slowest, most disk usage) * Any positive integer for custom depth ### Single Branch Clone Clone only the specified branch to reduce download size: ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "{{outputs.identify-repos}}" branch: "main" cloneOptions: singleBranch: true ``` ### Sparse Checkout Clone only specific directories or files: ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "{{outputs.identify-repos.[0].repoFullName}}" cloneOptions: sparseCheckout: enabled: true paths: - "src/frontend" - "docs" - "package.json" ``` **Cache Incompatibility**: Sparse checkout forces a full clone and cannot use repository caching, as it fundamentally changes the repository structure. This means every run will perform a fresh clone, which may be slower but ensures the correct file structure for your workflow. **Benefits of sparse checkout:** * Faster downloads for large repositories * Reduced disk space usage * Focus on relevant code sections * Ideal for monorepos or large projects ### Partial Clone Filters Use Git's partial clone feature to skip large files: ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "{{outputs.identify-repos}}" cloneOptions: filter: type: "blob:none" # Skip all file contents ``` **Available filter types:** * `"blob:none"`: Skip all file contents (fastest, metadata only) * `"blob:limit=100M"`: Skip files larger than 100MB * `"combine"`: Apply multiple filters together ### Force Fresh Clone Bypass cache and force a fresh clone: ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "{{outputs.identify-repos}}" cloneOptions: ignoreCache: true ``` **When to use `ignoreCache`:** * Debugging cache-related issues * Testing with fresh dependencies * Ensuring latest code changes * Troubleshooting workflow problems ### Submodule Clone Options Workflow Builder includes explicit **Clone Submodules Recursively** and **Shallow Clone Submodules** toggles inside the Git Clone step. Enable these controls whenever the target repository depends on nested Git modules so your workflow can hydrate the entire dependency tree. **Where to find the toggle**: 1. In Workflow Builder, add or edit a **Git Clone** action. 2. Expand **Clone Options** and switch on **Clone Submodules Recursively** to attach `--recurse-submodules` to the clone. 3. (Optional) Enable **Shallow Clone Submodules** when you only need the most recent commits from nested repositories (adds `--shallow-submodules`). ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository With Submodules" action: "git.clone" params: repoFullName: "owner/repository-with-submodules" cloneOptions: submodules: enabled: true # Mirrors the Clone Submodules Recursively toggle shallow: false # Set true to apply shallow depth to submodules ``` Set `submodules.enabled` to `true` any time your workflow needs library repos, infrastructure manifests, or shared assets that live in nested Git repositories. Combine it with `submodules.shallow` when you want faster fetches yet still need the submodule directory structure. **Access and runtime considerations**: * The repository token configured for the Git Clone step must have read access to every private submodule (including organization-scoped deploy keys). * Fetching and updating submodules adds several seconds per nested repo, so expect longer execution time for workflows that enable this option. Cache restores respect your submodule selections. When a cached repository is extracted, Overcut replays the same submodule settings, syncing and updating nested repositories during refresh. See the [Repository Caching guide](/docs/repositories/repository-caching) for deeper details on how cache refresh honors this behavior. *** ## Complete Examples ### Code Review Workflow Clone a repository for code review with optimization: ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "{{trigger.repository.fullName}}" branch: "{{trigger.pullRequest.headBranch}}" cloneOptions: depth: 10 singleBranch: true - id: "review-changes" name: "Multi-Repository Code Review" action: "agent.session" params: goal: "Review changes across all affected repositories" agentIds: ["senior-developer"] instruction: "Analyze the pull request changes in context of all affected repositories" ``` ### Cross-Repository Bug Investigation Investigate a bug that might span multiple repositories: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Related Repositories" action: "repo.identify" params: maxResults: 4 minConfidence: 0.6 identificationHints: "Include frontend, backend, shared libraries, and database schemas" - id: "clone-repos" name: "Clone Investigation Repositories" action: "git.clone" params: repoFullName: "{{outputs.identify-repos}}" cloneOptions: depth: 50 # More history for bug investigation filter: type: "blob:limit=50M" - id: "investigate-bug" name: "Cross-Repository Bug Investigation" action: "agent.session" params: goal: "Investigate the reported bug across all relevant codebases" agentIds: ["debugging-agent", "senior-developer"] instruction: "Analyze the bug report in context of these repositories: {{outputs.identify-repos}}" ``` ### Documentation Generation Across Repositories Generate documentation from multiple related repositories: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Documentation Repositories" action: "repo.identify" params: maxResults: 5 minConfidence: 0.5 identificationHints: "Focus on repositories with user-facing features and APIs" - id: "clone-docs" name: "Clone Documentation Sources" action: "git.clone" params: repoFullName: "{{outputs.identify-repos}}" cloneOptions: sparseCheckout: enabled: true paths: - "docs/" - "README.md" - "CHANGELOG.md" - "*.md" - "src/**/*.ts" # For API documentation - id: "generate-docs" name: "Generate Cross-Repository Documentation" action: "agent.session" params: goal: "Generate comprehensive documentation across all repositories" instruction: "Create unified documentation from all cloned repositories" ``` *** ## Output and Context ### Single Repository Output For single repository clones, the output structure is: Full path to the cloned repository in the workspace. Whether the repository was loaded from cache (true) or freshly cloned (false). Whether dependencies are already installed in the cached repository. ### Multi-Repository Output For multi-repository clones (when using `{{outputs.identify-repos}}`), the output structure includes: Overall success status. True if all repositories cloned successfully, false if any failed. Array of individual repository clone results. Full name of the repository that was cloned. Full path to this repository in the workspace. Whether this repository was loaded from cache. Whether this specific repository clone was successful. Error message if the repository clone failed. Summary statistics for the multi-repository clone operation. Total number of repositories attempted. Number of repositories successfully cloned. Number of repositories that failed to clone. Number of repositories loaded from cache. ### Available Variables Use these variables in subsequent steps: **Single Repository:** * **`{{outputs.clone-repo.workspacePath}}`**: Full path to the cloned repository * **`{{outputs.clone-repo.fromCache}}`**: Whether cache was used * **`{{outputs.clone-repo.dependenciesInstalledOnCache}}`**: Whether dependencies are already installed **Multi-Repository:** * **`{{outputs.clone-repos.success}}`**: Overall clone success status * **`{{outputs.clone-repos.repositories}}`**: Array of all repository results * **`{{outputs.clone-repos.summary.successful}}`**: Count of successful clones * **`{{outputs.clone-repos.summary.failed}}`**: Count of failed clones ### Repository Context All cloned repositories are automatically added to the workflow context and available to agents: * **Repository Information**: Name, provider, organization * **File System Access**: Full read/write access to repository contents * **Git Operations**: Access to commit history, branches, and Git metadata * **Dependency Management**: Automatic detection and installation of dependencies (when caching is enabled) *** ## Error Handling ### Partial Success in Multi-Repository Clones When cloning multiple repositories, some may succeed while others fail. The action handles this gracefully: ```yaml theme={"dark"} # Example output for partial success { "success": false, # Overall false because some repos failed "repositories": [ { "repoFullName": "owner/frontend", "workspacePath": "/workspace/frontend", "success": true, "fromCache": true }, { "repoFullName": "owner/backend", "workspacePath": "", "success": false, "error": "Repository not found or access denied" } ], "summary": { "total": 2, "successful": 1, "failed": 1, "fromCache": 1 } } ``` ### Workflow Continuation Strategies Handle clone failures gracefully in your workflows: ```yaml theme={"dark"} steps: - id: "clone-repos" name: "Clone Repositories" action: "git.clone" params: repoFullName: "{{outputs.identify-repos}}" - id: "analyze-available" name: "Analyze Available Repositories" action: "agent.session" params: goal: "Analyze the issue using available repositories" instruction: | Clone summary: {{outputs.clone-repos.summary.successful}} of {{outputs.clone-repos.summary.total}} repositories available. Focus your analysis on the successfully cloned repositories. If critical repositories failed to clone, mention this limitation in your analysis. ``` *** ## Caching Behavior ### Automatic Cache Usage Overcut automatically uses cached repositories when possible: * **Cache Eligibility**: Determined by clone options and repository configuration * **Cache Refresh**: Automatic background refresh every 10 days * **Cache Invalidation**: Stale caches (20+ days) are ignored * **Non-blocking**: Cache operations never block workflow execution * **Multi-Repository**: Each repository in a multi-repo clone is cached independently When the Git Clone step enables the submodule toggles, cached clones keep every nested repository in sync during refresh. Overcut replays `git submodule sync --recursive && git submodule update --recursive` with the same depth settings used at clone time so cache restores match fresh clones. See [Repository Caching](/docs/repositories/repository-caching#how-overcut-updates-cached-repositories) for the full refresh flow. ### Cache Compatibility | Clone Option | Cache Compatible | | ------------------- | ---------------- | | `depth` | ✅ Yes | | `singleBranch` | ✅ Yes | | `filter` | ✅ Yes | | `sparseCheckout` | ❌ No | | `ignoreCache: true` | ❌ No | ### Cache Performance * **First Run**: Normal clone time (creates cache for each repository) * **Subsequent Runs**: 90%+ faster using cache * **Cache Hit Rate**: Typically 95%+ for active repositories * **Multi-Repository**: Cache hits are independent per repository * **Background Refresh**: Automatic updates without blocking workflows *** ## Best Practices ### Dynamic Repository Selection 1. **Use `repo.identify` first**: Always identify repositories dynamically rather than hardcoding 2. **Set appropriate confidence thresholds**: Use `minConfidence: 0.7+` for critical operations 3. **Provide identification hints**: Help the AI make better repository selections 4. **Handle partial failures**: Design workflows to continue even if some repositories fail to clone ### Performance Optimization 1. **Use shallow clones**: Set `depth: 1` for faster clones when full history isn't needed 2. **Enable single branch**: Use `singleBranch: true` to reduce download size 3. **Leverage caching**: Avoid `ignoreCache: true` unless necessary 4. **Filter large files**: Use `filter` options for repositories with large binary files ### Multi-Repository Workflows 1. **Clone in parallel**: The action automatically clones multiple repositories in parallel for better performance 2. **Check success status**: Always verify `{{outputs.clone-repos.success}}` before proceeding 3. **Use summary statistics**: Leverage `{{outputs.clone-repos.summary}}` for workflow decisions 4. **Handle individual failures**: Design agents to work with partial repository sets ### Template Usage 1. **Use full output for multi-repo**: `{{outputs.identify-repos}}` for all identified repositories 2. **Use indexed access for single repo**: `{{outputs.identify-repos.[0].repoFullName}}` for just the top result 3. **Combine with conditionals**: Use template logic to handle different scenarios 4. **Pass context to agents**: Include repository information in agent instructions # Repository Identify Action Source: https://docs.overcut.ai/docs/workflows/repo-identify Learn how to use the repo.identify action to automatically determine the most relevant code repositories for your workflow context using AI-powered analysis and repository correlations. The `repo.identify` action is a **critical automation tool** that intelligently determines which code repositories are most relevant to your workflow context. In multi-repository workspaces where tickets (Jira, GitHub Issues) are managed separately from code repositories, this action is essential for bridging the gap and ensuring your automation workflows target the correct codebases. *** ## Why This Action is Critical ### **The Multi-Repository Challenge** In modern development environments, you often have: * **Ticket Systems**: Jira projects, GitHub Issues, Linear tickets * **Code Repositories**: Multiple Git repositories across different providers (GitHub, GitLab, Azure DevOps) * **Complex Relationships**: One ticket might affect code in 3-5 different repositories Without `repo.identify`, you'd need to: * Manually specify repository names in every workflow * Update workflows when repository structures change * Risk targeting the wrong repositories for critical operations * Maintain complex mapping logic across multiple systems ### **The Solution** The `repo.identify` action automatically bridges this gap by: * **Analyzing ticket context** to understand what needs to be done * **Mapping to code repositories** using AI and explicit correlations * **Providing confidence scores** to ensure accuracy * **Enabling dynamic workflows** that adapt to your repository structure *** ## Overview The `repo.identify` action analyzes your workflow context and automatically determines which code repositories are most relevant to the current task. It's particularly useful in multi-repository workspaces where you need to dynamically select the appropriate repositories based on ticket content, labels, and explicit correlations. Uses intelligent analysis of ticket content, labels, and context to identify relevant repositories. Leverages explicit correlations between ticket repositories and code repositories for reliable identification. Automatically selects the most appropriate repositories without manual configuration. Can identify multiple repositories for complex workflows that span multiple codebases. *** ## Chaining with Git Clone The `repo.identify` action output is designed to work seamlessly with `git.clone` for dynamic multi-repository workflows: ### **Basic Chaining Pattern** ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Relevant Repositories" action: "repo.identify" params: maxResults: 3 minConfidence: 0.7 - id: "clone-repos" name: "Clone Identified Repositories" action: "git.clone" params: repoFullName: "{{outputs.identify-repos}}" branch: "main" ``` ### **Single Repository Selection** ```yaml theme={"dark"} steps: - id: "identify-repos" action: "repo.identify" params: maxResults: 1 minConfidence: 0.8 - id: "clone-primary" action: "git.clone" params: repoFullName: "{{outputs.identify-repos.[0].repoFullName}}" branch: "{{trigger.pullRequest.headBranch}}" ``` *** ## Critical Use Cases ### **Jira Workflow Automation** When a Jira issue is created or updated, you need to know which code repositories contain the affected code: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Affected Repositories" action: "repo.identify" params: maxResults: 3 minConfidence: 0.7 identificationHints: "Focus on repositories containing the components mentioned in the issue" - id: "clone-repos" name: "Clone Identified Repositories" action: "git.clone" params: repoFullName: "{{outputs.identify-repos}}" branch: "main" - id: "analyze-issue" name: "Analyze Issue in Code Context" action: "agent.session" params: goal: "Analyze the Jira issue and provide technical recommendations" agentIds: ["senior-developer"] instruction: "Review the issue in context of the cloned repositories" ``` ### **Cross-Repository Bug Investigation** For bugs that might span multiple repositories: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Related Repositories" action: "repo.identify" params: maxResults: 5 minConfidence: 0.5 identificationHints: "Include frontend, backend, shared libraries, and database schemas" - id: "clone-repos" name: "Clone Investigation Repositories" action: "git.clone" params: repoFullName: "{{outputs.identify-repos}}" - id: "investigate-bug" name: "Cross-Repository Bug Investigation" action: "agent.session" params: goal: "Investigate the bug across all affected repositories" agentIds: ["debugging-agent", "architect-agent"] instruction: "Analyze the bug in these repositories: {{#each outputs.identify-repos}}{{.repoFullName}} {{/each}}" ``` ### **Feature Development Planning** When planning new features that touch multiple systems: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Feature Repositories" action: "repo.identify" params: maxResults: 4 minConfidence: 0.6 identificationHints: "Include user interface, business logic, API endpoints, and data models" - id: "clone-repos" name: "Clone Feature Repositories" action: "git.clone" params: repoFullName: "{{outputs.identify-repos}}" branch: "main" - id: "plan-feature" name: "Multi-Repository Feature Planning" action: "agent.session" params: goal: "Create implementation plan across all affected repositories" agentIds: ["product-manager", "senior-developer", "architect-agent"] instruction: "Plan the feature implementation across: {{#each outputs.identify-repos}}{{.repoFullName}} {{/each}}" ``` *** ## Basic Usage ### Simple Repository Identification The most basic usage identifies a single repository: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Repositories" action: "repo.identify" params: maxResults: 1 ``` ### Multi-Repository Identification Identify multiple repositories for complex workflows: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Repositories" action: "repo.identify" params: maxResults: 3 minConfidence: 0.7 ``` ### With Identification Hints Provide additional context to guide the identification process: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Repositories" action: "repo.identify" params: maxResults: 2 minConfidence: 0.6 identificationHints: "Focus on frontend components and user interface code" ``` *** ## Parameters ### Required Parameters None - all parameters have sensible defaults. ### Optional Parameters Maximum number of repositories to return (top-K). Controls how many candidate repositories are returned. Use 1 for single-repo workflows, higher values for multi-repo scenarios. Minimum confidence threshold (0..1). Filters out low-confidence matches. Higher values (0.7+) ensure only strong matches are returned. Optional hints to bias identification. Additional context that can help the AI make better decisions, especially when correlations are unclear. *** ## How Identification Works The identification process follows a sophisticated multi-step logic: ### 1. Correlation Check First, the system looks for explicitly correlated repositories between your ticket repository and code repositories. These explicit correlations take precedence over all other identification methods. ### 2. Context Analysis The AI analyzes the ticket content including: * **Title and description**: Keywords, technologies, and domain-specific terms * **Labels and components**: Project-specific categorization * **Assignee and reporter**: Team and ownership context * **Project structure**: Related tickets and dependencies ### 3. Repository Hints Considers repository-level identification hints configured in your repository settings, such as: * Key technologies and frameworks * Domain-specific components * Team ownership and responsibilities * Project scope and boundaries ### 4. Scoring and Ranking Combines all signals to produce confidence scores: * **Correlation strength**: Explicit correlations get highest scores * **Content relevance**: AI analysis of ticket-repository alignment * **Repository activity**: Recent commits and development activity * **Team alignment**: Developer and team associations ### 5. Filtering and Selection Applies the minimum confidence threshold and returns the top-ranked repositories up to the specified `maxResults`. *** ## Output and Context ### Step Output The `repo.identify` action provides output that can be used by subsequent steps: Array of identified repositories with confidence scores and reasoning. Full repository name in "owner/repo" format. Confidence score (0-1) indicating how well the repository matches the context. Explanation of why this repository was selected, including correlation details and AI analysis. ### Available Variables Use these variables in subsequent steps: * **`{{outputs.identify-repos}}`**: Complete array for multi-repository operations (use with git.clone) * **`{{outputs.identify-repos.[0].repoFullName}}`**: First identified repository * **`{{outputs.identify-repos.[0].confidence}}`**: Confidence score for first repository * **`{{outputs.identify-repos.[0].reasoning}}`**: Reasoning for first repository selection ### Template Examples **Multi-Repository Clone:** ```yaml theme={"dark"} repoFullName: "{{outputs.identify-repos}}" ``` **Single Repository Clone:** ```yaml theme={"dark"} repoFullName: "{{outputs.identify-repos.[0].repoFullName}}" ``` **Conditional Fallback:** ```yaml theme={"dark"} repoFullName: "{{#if outputs.identify-repos.[0]}}{{outputs.identify-repos.[0].repoFullName}}{{else}}{{trigger.repository.fullName}}{{/if}}" ``` **Important**: If your step ID contains hyphens (e.g., `identify-repos`), use bracket notation: `{{outputs.[identify-repos].[0].repoFullName}}` *** ## Integration with Other Actions ### Following with Git Clone After identifying repositories, you can clone them using the `git.clone` action: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Repositories" action: "repo.identify" params: maxResults: 1 minConfidence: 0.7 - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "{{outputs.identify-repos.[0].repoFullName}}" branch: "{{trigger.pullRequest.headBranch}}" ``` ### Multi-Repository Workflows For workflows that need to work with multiple repositories: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Repositories" action: "repo.identify" params: maxResults: 3 minConfidence: 0.6 - id: "clone-repos" name: "Clone All Repositories" action: "git.clone" params: repoFullName: "{{outputs.identify-repos}}" - id: "analyze-repos" name: "Analyze Repositories" action: "agent.session" params: goal: "Analyze the identified repositories for cross-dependencies and integration points" agentIds: ["architect-agent", "senior-developer"] ``` *** ## Best Practices ### 1. Set Up Explicit Correlations * **Always create explicit correlations** between ticket repositories and code repositories * This provides the most reliable identification results * Correlations take precedence over AI-based heuristics * Use the repository mapping interface to establish these relationships ### 2. Use Descriptive Repository Hints * Include key technologies, domains, and components in repository configuration * Use consistent terminology across related repositories * Update hints when repository scope changes * Consider team ownership and project boundaries ### 3. Configure Appropriate Confidence Thresholds * **0.2-0.4**: Low threshold, includes more candidates (default) * **0.5-0.7**: Medium threshold, balanced selection * **0.8-1.0**: High threshold, only strong matches * Start with default (0.2) and adjust based on results ### 4. Position in Workflow * Place `repo.identify` early in your workflow, right after the trigger * Use identified repositories in subsequent `git.clone` or agent steps * Consider fallback logic for cases where no repositories are identified ### 5. Monitor and Refine * Review identification results regularly * Adjust correlation settings based on accuracy * Update repository hints as projects evolve * Use workflow logs to understand identification reasoning *** ## Common Use Cases ### Issue Triage Workflows Automatically identify relevant repositories for issue analysis: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Repositories" action: "repo.identify" params: maxResults: 1 minConfidence: 0.6 - id: "analyze-issue" name: "Analyze Issue" action: "agent.session" params: goal: "Analyze the issue and provide technical recommendations" agentIds: ["senior-developer"] instruction: "Review the issue in context of repository: {{outputs.identify-repos.[0].repoFullName}}" ``` ### Cross-Repository Analysis Identify multiple repositories for comprehensive analysis: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Repositories" action: "repo.identify" params: maxResults: 3 minConfidence: 0.5 identificationHints: "Include frontend, backend, and shared libraries" - id: "cross-repo-analysis" name: "Cross-Repository Analysis" action: "agent.session" params: goal: "Analyze dependencies and integration points between repositories" agentIds: ["architect-agent"] ``` ### Feature Development Identify repositories for new feature implementation: ```yaml theme={"dark"} steps: - id: "identify-repos" name: "Identify Repositories" action: "repo.identify" params: maxResults: 2 minConfidence: 0.7 identificationHints: "Focus on user interface and business logic components" - id: "plan-feature" name: "Plan Feature Implementation" action: "agent.session" params: goal: "Create implementation plan for the new feature" agentIds: ["product-manager", "senior-developer"] ``` *** ## Advanced Configuration ### Repository-Level Hints Configure identification hints in your repository settings: 1. **Access Repository Settings**: Go to repository configuration 2. **Set Identification Hints**: Add descriptive text about the repository's purpose 3. **Use Consistent Terminology**: Align with ticket labels and project terminology 4. **Update Regularly**: Keep hints current with repository evolution ### Correlation Management Manage explicit correlations between repositories: 1. **Map Ticket Repositories**: Connect Jira projects to code repositories 2. **Establish Relationships**: Define which code repositories relate to which ticket systems 3. **Review Accuracy**: Regularly validate correlation effectiveness 4. **Adjust as Needed**: Update correlations when project structure changes *** ## Next Steps Now that you understand the `repo.identify` action, explore these related topics: * **[Repository Mapping](/docs/repositories/repository-mapping)**: Learn how to set up explicit correlations * **[Git Clone Action](/docs/workflows/git-clone)**: Use identified repositories in clone operations * **[Building Blocks](/docs/building-blocks)**: Explore other workflow actions and components * **[Quick Starts](/docs/quick-starts)**: See complete workflow examples Ready to automate repository selection? Start by setting up explicit correlations and then add the `repo.identify` action to your workflows for intelligent, context-aware repository identification. # Run Script Action Source: https://docs.overcut.ai/docs/workflows/run-script Run deterministic bash scripts in workflow execution containers and pass structured results to later steps. The `script.run` action executes an inline bash script as a deterministic workflow step inside the workflow execution container. Use it when you need repeatable shell automation that does not require an AI agent or model tokens. *** ## Overview Run Script is designed for workflow steps where the command path is already known. The script runs in bash, can read environment variables, can run inside a cloned repository, and can return structured JSON for later steps. Run the script exactly as written without asking an AI agent to decide what to do. Pass trigger data and previous step outputs through environment variables. Write JSON to `$OC_OUTPUT_FILE` and reference parsed fields in downstream steps. Exit code `0` succeeds. Non-zero exits, including timeouts, fail the step. *** ## When to use Run Script Use Run Script when the work is deterministic and shell-based. | Use this action | When your workflow needs | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `script.run` | A known bash script, file inspection, validation command, formatting check, artifact preparation, or data transformation that should run the same way every time. | | `agent.run` | A single AI agent to reason about a task, choose tools, write text, inspect code, or make judgment calls. | | `agent.session` | Multiple AI agents, an interactive session, or a task that benefits from agent coordination and iteration. | | `git.clone` | Repository checkout before another step needs files from the codebase. Use `git.clone` before Run Script when the script should run inside a repository. | | `ci.executeWorkflow` | An external CI/CD pipeline, such as a GitHub Actions workflow, should run outside Overcut. | Run Script is a good fit for steps like: * Check whether generated files changed after a previous step. * Extract metadata from a cloned repository. * Convert trigger or agent output into a normalized JSON shape. * Run a lightweight command before deciding whether a later agent step should run. *** ## Add a Run Script step in Workflow Builder Open or create a workflow in Workflow Builder. Add an action step and choose **Run Script**. Set **Step ID**, **Step Name**, and **Step Timeout (minutes)**. Add your shell commands in **Bash Script**. The script body is not template-interpolated, so pass dynamic values through **Environment Variables** instead. Connect later steps and reference the Run Script result with `{{outputs....}}` expressions. *** ## Configuration fields ### General Unique identifier for this step. Use a stable ID because later steps reference outputs with this value, for example `{{outputs.run-script.exitCode}}`. Display name shown in Workflow Builder and workflow run details. Maximum time the whole step can run before Overcut stops it. Defaults to `30` minutes. This remains the outer bound even when **Timeout Seconds (optional)** is set. ### Script Inline bash script to execute. The script is required and must not be empty. Relative path inside the workflow workspace. Use this to run a script inside a repository cloned by an earlier `git.clone` step. This field can use workflow expressions, for example `{{outputs.clone-repo.workspacePath}}`. Maximum script runtime in seconds. Defaults to `1800`. The effective limit is bounded by **Step Timeout (minutes)**. ### Environment Variables Key-value pairs exposed to the script as environment variables. Names must be valid shell identifiers, such as `TICKET_TITLE` or `BUILD_ID`. Values can use dynamic workflow expressions such as `{{trigger.title}}`, `{{outputs.previous-step.field}}`, and `{{params.release_channel}}`. *** ## Pass data into scripts Do not template-interpolate dynamic workflow data directly into **Bash Script**. The script body is never rendered, and trigger titles, comments, and agent output can contain characters that have special meaning in bash. Instead, put dynamic values in **Environment Variables** and read them in the script. The same applies to [context parameters](/docs/reference/context-parameters): assign `{{params.}}` to an environment variable and read that variable. Run Script also receives every context parameter the workflow references as `OC_PARAM_`, with the key in uppercase, so `release_channel` is available as `$OC_PARAM_RELEASE_CHANNEL` without any mapping. ```yaml theme={"dark"} steps: - id: "summarize-title" name: "Summarize Trigger Title" action: "script.run" params: script: | echo "Title: $TRIGGER_TITLE" printf '{"titleLength": %d}\n' "${#TRIGGER_TITLE}" > "$OC_OUTPUT_FILE" env: TRIGGER_TITLE: "{{trigger.title}}" ``` Use standard double braces for escaped values and triple braces for raw values. Triple braces are useful when passing agent prose or other text that should arrive without escaping. ```yaml theme={"dark"} steps: - id: "inspect-agent-summary" name: "Inspect Agent Summary" action: "script.run" params: script: | echo "Agent summary length: ${#AGENT_SUMMARY}" env: ISSUE_TITLE: "{{trigger.title}}" PREVIOUS_FIELD: "{{outputs.previous-step.field}}" AGENT_SUMMARY: "{{{outputs.agent-step.message}}}" ``` Inside the script, quote environment variables like `"$ISSUE_TITLE"` so bash treats the value as data. *** ## Use secrets safely Project and Library secrets attached to the workflow are available to Run Script as environment variables. Use them for API tokens, package registry credentials, or other sensitive values needed by deterministic commands. Use context parameters for non-secret configuration only; their values appear in run logs. Do not print secrets. Run Script captures stdout and stderr in workflow run logs and stores captured output in the step result. A safer pattern is to test that a secret is present without echoing the value: ```bash theme={"dark"} if [ -z "$PACKAGE_TOKEN" ]; then echo "PACKAGE_TOKEN is missing" exit 1 fi echo "Package token is configured" ``` See [Vault](/docs/reference/vault) for project secret configuration and assignment. *** ## Return structured output with `$OC_OUTPUT_FILE` Run Script always captures `exitCode` and `stdout`. To pass structured values to later steps, write valid JSON to the file path stored in `$OC_OUTPUT_FILE`. ```yaml theme={"dark"} steps: - id: "collect-build-info" name: "Collect Build Info" action: "script.run" params: script: | BUILD_ID="build-$(date +%s)" printf '{"buildId": "%s", "ready": true}\n' "$BUILD_ID" > "$OC_OUTPUT_FILE" ``` Later steps can reference parsed fields under `output`: ```yaml theme={"dark"} steps: - id: "use-build-info" name: "Use Build Info" action: "agent.run" instruction: | The build ID is {{outputs.collect-build-info.output.buildId}}. ``` Use `{{outputs..output.}}` for values written to `$OC_OUTPUT_FILE`. Use `{{outputs..exitCode}}`, `{{outputs..stdout}}`, or `{{outputs..truncated}}` for the standard result fields. *** ## Execution results and failure behavior Run Script stores the step result under `outputs.`. Script exit code. `0` means the step succeeded. Non-zero values fail the step and workflow run. A timeout reports exit code `124`. Captured stdout and stderr from the script. The stored value may be truncated. Whether captured stdout and stderr were truncated before being stored. Parsed JSON object written to `$OC_OUTPUT_FILE`. Omitted when the output file is missing or empty. Error recorded when `$OC_OUTPUT_FILE` exists but contains invalid JSON or JSON that is too large. This does not fail an otherwise successful script. Behavior summary: | Behavior | Result | | ---------------------------------------------------- | ---------------------------------------------------------------------------- | | Script exits `0` | Step succeeds. | | Script exits non-zero | Step fails and the workflow run fails. | | Script exceeds its timeout | Step fails with `exitCode` `124`. | | Script writes to stdout or stderr | Output is captured in `stdout` and may be truncated. | | `$OC_OUTPUT_FILE` is missing or empty | Step can still succeed. `output` is omitted. | | `$OC_OUTPUT_FILE` contains invalid or too-large JSON | Step can still succeed if `exitCode` is `0`. `outputParseError` is recorded. | *** ## Validation rules Overcut validates Run Script configuration when you save the workflow. | Field | Rule | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | **Bash Script** | Required and non-empty. | | **Working Directory (optional)** | Must be a relative path inside the workspace. It cannot start with `/`, use a Windows drive prefix, or include `..` path segments. | | **Variable Name** | Must be a valid shell identifier matching letters, numbers, and underscores, and cannot start with a number. | | **Variable Name** with `OC_` prefix | Not allowed. `OC_` is reserved for Overcut runtime variables such as `OC_OUTPUT_FILE`. | | **Timeout Seconds (optional)** | Must be a positive integer with a maximum of `21600` seconds. | *** ## Examples ### Run inside a cloned repository Use `git.clone` first, then set **Working Directory (optional)** to the cloned repository folder. ```yaml theme={"dark"} steps: - id: "clone-repo" name: "Clone Repository" action: "git.clone" params: repoFullName: "{{trigger.repository.fullName}}" branch: "{{trigger.pullRequest.headBranch}}" - id: "inspect-repo" name: "Inspect Repository" action: "script.run" params: cwd: "{{outputs.clone-repo.workspacePath}}" script: | SHA=$(git log -1 --format=%H) BRANCH=$(git rev-parse --abbrev-ref HEAD) printf '{"sha": "%s", "branch": "%s"}\n' "$SHA" "$BRANCH" > "$OC_OUTPUT_FILE" ``` ### Chain script output into another script ```yaml theme={"dark"} steps: - id: "produce-output" name: "Produce Output" action: "script.run" params: script: | echo '{"buildId": "build-7788", "color": "blue"}' > "$OC_OUTPUT_FILE" - id: "consume-output" name: "Consume Output" action: "script.run" params: script: | echo "Received build $BUILD_ID with color $COLOR" printf '{"label": "%s-%s"}\n' "$BUILD_ID" "$COLOR" > "$OC_OUTPUT_FILE" env: BUILD_ID: "{{outputs.produce-output.output.buildId}}" COLOR: "{{outputs.produce-output.output.color}}" ``` ### Fail fast on a validation command ```yaml theme={"dark"} steps: - id: "check-package" name: "Check Package Metadata" action: "script.run" params: script: | test -f package.json || { echo "package.json not found"; exit 2; } node -e 'JSON.parse(require("fs").readFileSync("package.json", "utf8"))' ``` If `package.json` is missing or invalid, the script exits non-zero and the step fails. *** ## Related documentation * [Workflows](/docs/workflows/workflows): Understand workflow components and step outputs. * [Git Clone Action](/docs/workflows/git-clone): Clone repositories before running scripts against code. * [Agent Run Action](/docs/workflows/agent-run): Use an AI agent when the task requires reasoning or judgment. * [Agent Session Action](/docs/workflows/agent-session): Coordinate multi-agent or interactive work. * [Execute CI Workflow Action](/docs/workflows/ci-execute-workflow): Trigger external CI/CD pipelines from workflows. * [Event Context Reference](/docs/reference/event-context): Find trigger fields and expression examples. * [Context Parameters](/docs/reference/context-parameters): Reusable values, `OC_PARAM_`, and resolution order. * [Vault](/docs/reference/vault): Configure secrets for workflows. # Scheduled Workflows Source: https://docs.overcut.ai/docs/workflows/scheduled-workflows Run Overcut workflows automatically on a recurring schedule using cron-based triggers. Learn how to define schedules, choose execution modes, and monitor recurring runs. > Automate recurring tasks (nightly code scans, weekly backlog grooming, or monthly dependency updates) by triggering workflows on a fixed schedule instead of waiting for an external event. Scheduled Workflows let you configure cron-based triggers that launch a workflow at precise times. Rather than reacting to a webhook from GitHub or Jira, the workflow is kicked off by Overcut’s internal scheduler according to a cron expression you define. ## What Are Scheduled Workflows? A *Scheduled Workflow* is any Overcut Workflow whose trigger type is **Scheduled**. These workflows run automatically at the times you specify. Some examples are: Run a daily planning session to review the backlog, plan the day, and share the plan with the team. Scan all repos every day and for security or performance improvements and open new issues. Pick up tech-debt issues from the backlog and create PRs to fix them. Let an Agent review stale issues and propose closing or updating them. ## Defining a Schedule 1. **Create** a Workflow in the Workflow Builder. 2. Click on the trigger block and change its type to `Scheduled`. 3. Click on the **Schedule** panel to define when the workflow should run. 4. Choose an **Execution Mode** (see below) and **Save**. Each workflow can have only one scheduled trigger. However, you can use a single cron expression to schedule multiple execution times (for example, every day at 1pm and 7pm). If you need completely different schedule patterns, create separate workflows for each schedule. Scheduled trigger editor ## Execution Modes When you choose a **Scheduled** trigger you must also decide **how many times** the workflow should execute during each schedule interval. Overcut offers two modes: | Mode | What Happens at *Run Time* | Typical Use Cases | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Single** (default) | The workflow runs **exactly once** per schedule, using whatever repository (or none) you have hard-coded in the canvas. | • House-keeping tasks in a single infra repo
• Ticket triage that doesn’t touch code
• Nightly job against a mono-repo | | **Per-Repository** | Overcut first evaluates the attached [Repository Selector](/docs/repositories/repository-selector). For **each matching repository (up to 100)** it queues a separate execution. | • Dependency or security scans across many repos
• Automated issue filing in every project
• Bulk codebase migrations | Per-Repository mode fans out *N* executions where *N* is the number of repositories returned by the selector. Monitor your usage quotas and choose narrow selectors when starting out. ## Time-Zone Awareness Schedules are evaluated in the workspace timezone (default: UTC). Workspace owners can update this in **Account → Settings**. All human-readable summaries and upcoming run previews reflect the selected zone. ## Monitoring & Troubleshooting * **Execution History**: Each run appears in the *Executions* tab with start time, status, and logs. * **Failures & Retries**: Failed runs appear in red with error details. You can retry manually or configure automatic retries. * **Pausing a Schedule**: Toggle the **Enable Workflow** switch to temporarily suspend future executions. ## Limitations & Best Practices 1. **One scheduled trigger per workflow**: Each workflow can contain **only one** scheduled trigger. 2. **Minimum interval**: The shortest supported interval is **1 minute** (`* * * * *`). Use responsibly to avoid rate limits. 3. **No overlapping runs**: Overcut enforces *resource locking* per workflow execution. If a previous scheduled run is still active for the same resource (lock key), the next run is **skipped**. 4. **Version pinning**: Changes to a scheduled workflow’s definition only apply to *future* runs. Already queued executions keep the version that existed at queue time. 5. **Idempotency**: Ensure your workflow can handle being re-run without unintended side effects. ## Related Links * [Triggers](/docs/workflows/triggers) * [Repository Mapping](/docs/repositories/repository-mapping) * [Workflow Execution Control](/docs/workflows/workflow-execution-control) * [Building Blocks](/docs/building-blocks) # Session Cleanup & Timeouts Source: https://docs.overcut.ai/docs/workflows/session-cleanup How Overcut manages long-running agent sessions and automatically cleans up resources to keep your workflows running smoothly. Overcut automatically manages agent sessions to ensure your workflows continue running efficiently. When sessions run too long or get stuck, Overcut uses a **two-phase termination system** to gracefully close them while preserving your work. ## How It Works ### Phase 1: Graceful Termination When a session reaches its natural end (completes its task, hits time limits, or receives a user signal), Overcut sends a termination request and gives the agent time to: * Save any work in progress * Upload completed files or artifacts * Clean up temporary resources * Exit gracefully ### Phase 2: Forced Termination If an agent doesn't respond to the graceful termination request within the configured timeout period, Overcut forces the session to close immediately. This prevents stuck sessions from blocking your workflows. ## Session States Overcut tracks sessions through several states: * **Running**: Session is actively working on a task * **InSession**: Agent is in an interactive session (e.g., coding, debugging) * **WaitingForReply**: Session is waiting for user input or comments * **Terminating**: Session has received termination request and is shutting down * **Completed**: Session finished successfully * **Failed**: Session encountered an error or was forced to terminate ## Configuration Overcut automatically manages session timeouts to keep your workflows running smoothly. There are two types of timeouts: ### Session Termination Timeout * **Default**: 5 minutes for agents to gracefully shut down * **Purpose**: Gives agents time to save work, upload files, and clean up resources * **When it applies**: When a session is being terminated (either naturally or by user request) ### User Response Grace Period * **Default**: 10 minutes for users to respond to session requests * **Purpose**: Allows time for human review and comments before session closes * **When it applies**: When a session is waiting for user input or comments ### Workflow-Level Timeouts You can also set a maximum execution time for entire workflows: * **Range**: 30 seconds to 1 hour * **Purpose**: Prevents workflows from running indefinitely * **How to set**: Configure in your workflow definition (contact your administrator for help) ## What Happens During Termination ### Session Termination 1. Overcut sends a termination request to the agent 2. Agent receives the request and begins shutdown procedures 3. Agent has 5 minutes to complete cleanup (save files, upload artifacts, etc.) 4. If successful, session closes normally ### Forced Session Termination 1. If the agent doesn't respond within 5 minutes, Overcut forces immediate termination 2. Agent must exit immediately (no additional cleanup time) 3. Session is marked as failed 4. Workflow continues with the next step ### Workflow Execution Timeout * If a workflow exceeds its configured timeout (30 seconds to 1 hour), it's automatically marked as "Timeout" * This prevents workflows from running indefinitely and consuming resources * Timeout status is tracked separately from session termination ## Best Practices * **Set realistic timeouts**: Don't set extremely long timeouts unless necessary * **Monitor session patterns**: Watch for sessions that frequently timeout * **Use appropriate session types**: Choose between interactive sessions and task execution based on your needs ## Monitoring Overcut provides visibility into session and workflow behavior through: * **Session status updates**: Real-time status changes in the UI (Running, InSession, WaitingForReply, Terminating, Completed, Failed) * **Workflow execution status**: Track workflow progress (Running, Completed, Failed, Timeout) * **Termination events**: Logs showing when and why sessions terminate * **Execution duration**: Monitor how long workflows and individual steps take to complete # Token Usage Analytics Source: https://docs.overcut.ai/docs/workflows/token-usage-analytics Monitor LLM token consumption across dashboards, execution lists, and workflow run details so you can find high-usage workflows, models, agents, and runs. Token usage analytics help you understand how your workflows consume LLM capacity over time. Use these views to compare usage across a selected date range, find the workflows and agents that drive consumption, and open high-usage runs for a closer look. Review total, input, output, and cached input tokens for the date range you choose. Break token usage down by model, workflow, step, or agent depending on the dashboard you are viewing. Open high-usage executions from dashboards or lists to inspect run-level and step-level token counts. Use previous-period context to see whether token consumption is rising or falling for the same length of time. ## Overview Token usage analytics are available in the places where you monitor workflow activity: * The **Project Dashboard** shows project-wide LLM usage across all workflows in the project. * A **Workflow Dashboard** narrows the same kind of analysis to one workflow. * The **Executions** list helps you sort runs by token usage. * **Workflow run details** show the token totals behind a specific run and its steps. Start with the Project Dashboard when you want to understand overall consumption. Move to a workflow, execution, or step when you need to explain a spike or optimize a specific automation. ## Where token usage appears ### Project Dashboard The Project Dashboard is the best starting point for project-wide LLM usage. It aggregates token usage across the selected date range and includes: * **Total Tokens**: all provider-reported LLM tokens used by the project during the selected period. * **Input Tokens**: tokens sent to LLMs as prompts, instructions, context, and tool-related input. * **Output Tokens**: tokens generated by LLMs in responses. * **Cached Input**: the portion of input tokens served from cache when cache data is available. This is a subset of Input Tokens, not an additional amount on top of them. * **LLM Calls**: the number of LLM requests represented in the selected period. * **Previous-period comparisons**: context for how the selected period compares with the immediately preceding period of the same length. * **Token trends**: usage over time based on the selected date range and grouping. * **Token Usage Breakdown**: usage grouped by **Model**, **Workflow**, or **Agent**. * **Heaviest Executions**: a leaderboard of runs with the highest total token usage in the selected period. Use the Project Dashboard to answer questions like: * Which workflows are responsible for most token usage this week? * Did usage rise compared with the previous period? * Are specific models or agents driving the increase? * Which executions should I inspect first? ### Workflow Dashboard A Workflow Dashboard focuses token analytics on one workflow. Use it after you identify a workflow that needs closer review from the Project Dashboard. Workflow-scoped analytics include token KPI cards, token trends for the selected date range, and breakdowns by **Model**, **Step**, and **Agent**. This helps you distinguish whether usage comes from a specific model choice, a step in the workflow, or an agent assigned to the workflow. ### Executions list The Executions list includes a sortable **Tokens** column. The column shows output token usage for each run, which makes it useful for finding runs that produced unusually large LLM responses. Sort by **Tokens** when you want to move from dashboard-level trends to the specific runs behind them. ### Workflow run details Workflow run details show token usage for a single execution. The run summary includes output token usage, with expandable details for: * **Input Tokens** * **Cached Input** * **Output Tokens** * **Total Tokens** * **LLM Calls** When step-level token data is available, individual steps also show output token counts. Use these counts to identify which part of the run contributed most to the total. ## Choose a date range Dashboard analytics follow the selected **Date Range**. Available presets include: * **Today** * **Last 7 Days** * **Last 30 Days** * **Last 90 Days** * **This Month** On the Project Dashboard, use **Group By** to control how trend charts bucket the selected range: * **Day** for daily changes and short ranges. * **Week** for medium-term usage patterns. * **Month** for longer ranges and month-to-month review. Selecting **Last 7 Days** from the Date Range control uses the same date window as the default Last 7 Days dashboard view. This keeps analytics consistent when you compare initial dashboard data with the same preset selected later. ## Understand token metrics | Metric | What it means | How to use it | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | **Total Tokens** | The combined token usage reported for LLM calls in the selected scope. | Use it as the headline consumption number for a project, workflow, model, agent, step, or run. | | **Input Tokens** | Tokens sent to LLMs as instructions, context, and prompts. | Watch for large context windows or workflows that send more information than needed. | | **Output Tokens** | Tokens generated by LLMs in responses. | Use it to find runs or steps where agents produced long answers, summaries, or code changes. | | **Cached Input** | The portion of Input Tokens served from cache when cache data is available. It is a subset of Input Tokens, not an amount added on top of them. | Compare with Input Tokens to understand how often repeated context is reused. | | **LLM Calls** | The number of LLM requests included in the selected scope. | Use it to distinguish frequent small calls from fewer large calls. | Model breakdowns can show **System** and **Custom** labels. **System** indicates models provided by Overcut defaults or platform configuration. **Custom** indicates models your workspace configured for its own use. ## Break down token usage Use the **Token Usage Breakdown** panel to identify what contributes most to consumption. ### By Model Group by **Model** to compare token usage across LLM models. This view is useful when you want to confirm whether a high-capacity model is responsible for a spike or whether usage is spread across several models. When model rows include **System** or **Custom** labels, use them to distinguish Overcut-provided model options from models configured by your workspace. ### By Workflow Group by **Workflow** on the Project Dashboard to see which workflows use the most tokens across the selected date range. Start here when you are reviewing project-level usage or looking for candidates to optimize. ### By Agent Group by **Agent** to understand which agent roles are associated with the most token usage. This can highlight agents that need tighter instructions, narrower context, or a workflow design review. ### By Step Use the Workflow Dashboard to break a single workflow down by **Step**. This is the most direct way to find where token-heavy work happens inside one automation. ## Investigate high-usage runs Use this workflow when a dashboard shows unexpected token usage: Select the preset that matches the period you want to review. Use **Group By** on the Project Dashboard when you need a daily, weekly, or monthly trend. Compare **Total Tokens**, **Input Tokens**, **Output Tokens**, **Cached Input**, and **LLM Calls** with the previous period. Use **Token Usage Breakdown** to group by **Model**, **Workflow**, or **Agent**. Sort your attention toward rows with the highest **Total** values. Use **Heaviest Executions** or sort the Executions list by **Tokens** to open a run that contributed to the spike. Expand token details in the run summary, then review step output token counts to identify the part of the run that produced the most usage. If output tokens are high, review the agent's response requirements and any steps that ask for long summaries or generated code. If input tokens are high, review the amount of context the workflow sends into the agent. ## Related documentation * [Workflows](/docs/workflows/workflows): Understand workflow structure, triggers, actions, and monitoring. * [Workflow Execution Control](/docs/workflows/workflow-execution-control): Learn how Overcut manages queued and running workflows. * [LLM Models](/docs/reference/llm-models): Review model configuration and defaults. * [Workflow Builder](/docs/how-to/workflow-builder): Configure workflow metadata, steps, and model settings. # Trigger with Slash Command Source: https://docs.overcut.ai/docs/workflows/trigger-with-slash-command Launch a workflow when a repository comment or Jira issue comment includes a custom slash command such as /review. This guide walks through creating a Workflow that starts when someone types a **slash command** (`/review`) in a comment. The flow will clone the repository and open an agent session to review the pull request or handle the Jira issue. *** ## Create a Workflow From the main menu, click Workflows and then select Create Workflow. Give the Workflow a descriptive name such as PR Review via Slash Command or Jira Issue Review via Slash Command. *** ## Configure the Slash Command Trigger Click an existing Trigger or click on "Add Trigger" to create a new one. Choose Manual from the Trigger Event selector. In the SlashCommand field, type review. Do **not** include the leading slash character. Enable Require Mention if the command should only trigger when it follows @overcut. Example trigger text: @overcut /review. Slash command triggers always execute immediately when detected, ensuring responsive user interaction. Delay settings are not applicable for this trigger type. The trigger listens to comments on pull requests, issues, and review threads in **GitHub**, **GitLab**, and **Bitbucket**, as well as comments on **Jira tickets**. In those surfaces the command appears at the start of a line (or after `@overcut` if `Require Mention` is enabled). It also works in **registered Slack channels**, where the syntax is `/overcut `: the token after the `/overcut` bot prefix is what matches the SlashCommand field. For Slack setup, see [Slack integration](/docs/integrations/slack). ## Slash Command Usage Patterns Slash commands can be configured in two ways: ### 1. **Manual-Only Trigger** When you add **only** the manual trigger with the Slash Command field, the workflow will **only** run when someone explicitly types the command. This creates a completely manual workflow that gives users full control over when it executes. **Use cases:** * On-demand code reviews * Manual issue analysis * User-initiated documentation generation * Custom workflow execution ### 2. **Hybrid Trigger (Automatic + Manual)** You can combine slash commands with other automatic triggers to create hybrid workflows. For example: * **Issue labeled + Slash command**: Automatically process labeled issues, but also allow manual `/review` commands * **PR opened + Slash command**: Start workflows on PR creation, but also support manual `/analyze` commands **Benefits:** * Automatic processing for common scenarios * Manual override capability when needed * Flexible workflow control * User empowerment without losing automation Slash command executions always take precedence over other running manual workflows. When a user invokes the command, the new run starts immediately with the parameters provided in the comment. see [Trigger Execution](/docs/reference/trigger-execution) for more details. *** ## Test the Workflow **GitHub**: In the pull request conversation, type /review (or @overcut /review if a mention is required). **Jira**: In the issue comments, type /review (or @overcut /review if a mention is required). **Slack**: In a [registered channel](/docs/integrations/slack#register-channels-in-a-project), type /overcut review. Slack always uses /overcut as the bot prefix; the token after it (review) is what matches the SlashCommand field on this trigger. A plain @overcut mention fires a separate **mention** trigger, not this slash-command trigger. A new execution appears on the Executions page. The agent responds in the source surface based on your workflow setup. *** ## Supported Platforms Slash commands work across Overcut integrations that support text-based workflow triggers: * **GitHub**: Pull requests, issues, and review threads * **Jira**: Issue comments and descriptions * **GitLab**: Issues, merge requests, and comments * **Bitbucket**: Issues, pull requests, and comments * **Azure DevOps**: Work items and pull requests * **Slack**: Registered channels, through `/overcut ` or `@overcut /` Syntax depends on the surface. Repository and ticket comments match the command string you configured on the trigger (for example, `/review` or `@overcut /review`). Slack uses the bot's built-in slash command, `/overcut `; the token after `/overcut` is what matches the SlashCommand field on your trigger. A plain `@overcut` mention in Slack fires a separate **mention** trigger, not the slash-command trigger covered here. *** ## ✅ Success Checklist
  1. The workflow triggers on the configured command or mention
  2. The workflow executes successfully
  3. Works consistently across GitHub, GitLab, Bitbucket, Azure DevOps, Jira, and registered Slack channels
# Triggers Source: https://docs.overcut.ai/docs/workflows/triggers Triggers define when a Workflow should start, based on events from GitHub, GitLab, Jira, ClickUp, or manual input. Triggers are the starting point for every automation in Overcut. Each trigger maps to a standardized event from an external provider, such as GitHub, GitLab, Jira, ClickUp, or Overcut's own API. When that event fires, Overcut evaluates your Workflow and starts the flow if all conditions are met. ## Supported Platforms Overcut supports triggers from multiple platforms, with events normalized to a consistent format: * **GitHub**: Pull requests, issues, and review activity * **GitLab**: Merge requests, issues, and comments * **Jira**: Issue lifecycle, comments, and status changes * **Bitbucket**: Pull requests, issues, and comments * **Azure DevOps**: Work items, pull requests, and comments * **ClickUp**: Task creation, updates, status changes, and comments * **Slack**: Registered channels, through mentions, slash commands, and messages in channels set to **Watch all messages**. Top-level posts can trigger `channel_message`; thread replies can trigger `thread_reply` when no run or session is live on that thread. See [Slack integration](/docs/integrations/slack). * **Custom Events**: Workspace-defined event types fired from any third-party system via a public webhook URL. Use for CI servers, monitoring tools, internal scripts, or anything without a native integration. See [Custom Events](/docs/integrations/custom-events). All platforms use the same trigger types and conditions. Overcut automatically normalizes platform-specific events into standardized formats, so your workflows work consistently regardless of the source platform. ## Trigger Categories Kick off flows when issues are opened, labeled, edited, or commented on. Start workflows for PR creation, merging, review activity, and more. Trigger workflows when CI runs are queued, started, completed, failed, cancelled, or timed out. Run workflows with a button click, by @mentioning Overcut, or via custom slash commands. Run workflows on a cron-based schedule. Fire workflows from any third-party system that can send an HTTP request: CI, monitoring, or your own scripts. ## Scheduled Triggers [Scheduled Workflows](/docs/workflows/scheduled-workflows) let you run automations on a **cron-based schedule**: hourly, daily, weekly, or any custom interval. They are ideal for maintenance, reporting, and other recurring tasks that aren’t tied to an external event. Scheduled triggers are evaluated in your workspace time-zone and support **Single** and **Per-Repository** execution modes (see [Scheduled Workflows → Execution Modes](/docs/workflows/scheduled-workflows#execution-modes)). ## Trigger Delays You can configure an optional delay before workflow execution to allow related updates to complete. This is particularly useful for: * **Issue creation**: Wait for fields to be filled out and labels to be added * **PR updates**: Allow time for description edits and initial comments * **Field changes**: Let users complete their input before processing begins **Interactive triggers** (slash commands and mentions) always ignore delay settings and execute immediately for responsive user experience. **When to use delays:** * **1-2 minutes**: For issue/PR creation to allow the user to complete the initial setup * **No delay**: For immediate response needs or when context is already complete **Delay behavior:** * Delays are applied when the trigger is first detected * If additional related events occur during the delay window, the timer resets * This ensures the workflow waits for activity to settle before executing * During delays, events automatically merge through [event deduplication](/docs/workflows/workflow-execution-control#event-deduplication) ## Multi-trigger orchestration (OR logic) You can configure multiple triggers for a single workflow. When an event occurs, all triggers are evaluated in random order. If any trigger matches the event, the workflow is triggered using that matching trigger's configuration: its delay, filters, and execution mode remain intact. Evaluation stops as soon as one trigger matches. Use one trigger when the workflow should start from exactly one event source (for example, issue\_opened). The trigger simply relays that event to the first downstream step. Add multiple triggers (for example, issue\_labeled or pull\_request\_merged) when the workflow should start if **any** of those events occur. The dispatcher evaluates triggers in random order and starts the workflow as soon as one trigger matches; all other triggers are skipped for that event. You can mix scheduled, event, and manual triggers in a single workflow, but there are some limitations: * Only one scheduled trigger is allowed per workflow; use cron expressions within that trigger if you need multiple execution times. * Each type of trigger requires a different configuration: * Scheduled triggers require a cron expression. * Event triggers require a set of filters. * Manual triggers require a slash command. ## Editing triggers in the Properties panel Selecting any trigger highlights it inside the **Properties panel** on the right. The form reconfigures itself to show only the fields that apply to the selected trigger, so you are never editing irrelevant inputs. Live previews for manual slash commands update as you type, and any schema validation issues are surfaced inline before you can publish.
  • Use the **conditions builder** to stack repository, project, label, or author filters. Each row maps directly to the trigger schema, so what you configure visually is what the dispatcher enforces.
  • Event-specific fields (such as issue metadata versus pull-request metadata) appear automatically, keeping the available filters in sync with the selected event.
  • CI workflow triggers surface filters for run status, conclusion, branch, commit SHA, run ID, workflow name or URL, pull request association or ID, and job count.
  • Inline warnings appear beside any incomplete filter rows: for example, if you add a label condition but leave the value empty, the panel flags it before allowing you to save.
  • The **delay** setting is available for all event triggers. It allows you to delay the workflow execution by a certain number of seconds.
  • Enter a **cron expression**; inline validation confirms the format before the schedule is saved.
  • Select an **execution mode** (Single vs. Per-Repository) so the dispatcher knows whether to run once or per resource.
  • Define the required **slash command** (for example, /review) and whether an @overcut mention is required. The panel blocks saves until the command field is populated.
  • Use the built-in **slash command preview** to confirm the exact syntax builders will type before sharing instructions with your team.
  • Create multiple manual triggers to allow different slash commands to trigger the same workflow.
 ### Acknowledgment reactions Mention, channel message, and thread reply triggers show an **Acknowledgment** group in the **Properties panel**. **Reaction on trigger message** sets the emoji Overcut adds to the message that started the run, so the sender knows it was picked up. Choose from Eyes, Robot, Hourglass, Rocket, Thumbs up, Check mark, Wave, or Zap, or **None (no reaction)** to add nothing. **Eyes** is the default for new and existing workflows. Select **None (no reaction)** to suppress the acknowledgment reaction. Acknowledgment reactions are unavailable for slash commands, scheduled triggers, Git events, and custom events. *** ## Issue Events Issue triggers include lifecycle actions (opened and closed), content updates, and status transitions. Use **State Change** when an issue moves between workflow states without being created or closed.
  • issue\_opened : Issue was created.
  • issue\_closed : Issue was closed.
  • issue\_edited : Title or body changed.
  • issue\_assigned : Assignee added.
  • issue\_unassigned : Assignee removed.
  • issue\_labeled : Label was added.
  • issue\_unlabeled : Label was removed.
  • issue\_commented : New comment was posted on an issue.
**State Change** is an **Issue Action** option in the trigger filters. It applies to status transitions that do **not** create or close the issue (for example, Backlog → In Progress). Use **opened** and **closed** when you want to react to creation or closure events, even if the status also changes at the same time. **Azure DevOps tags:** ADO does not emit `issue_labeled`/`issue_unlabeled`. A work-item tag change arrives as `issue_edited`. To trigger on an ADO tag, select **Issue edited** and add a condition like `context.trigger.labelsAdded contains ""`. The `labelsAdded`/`labelsRemoved` arrays are available on label changes across all providers. See [Event Context](/docs/reference/event-context#label-operations). ## Pull Request Events
  • pull\_request\_opened : Pull request was opened.
  • pull\_request\_closed : Pull request was closed without merge.
  • pull\_request\_merged : Pull request was merged into base.
  • pull\_request\_edited : Title or description of PR was changed.
  • pull\_request\_reviewed : A review was submitted (approve/request changes).
  • pull\_request\_assigned : An assignee was added to the pull request.
  • pull\_request\_unassigned : An assignee was removed from the pull request.
  • pull\_request\_labeled : Label was added to the pull request.
  • pull\_request\_unlabeled : Label was removed from the pull request.
  • pull\_request\_commented : A general comment was posted on the pull request.
  • pull\_request\_review\_commented : An inline code comment was posted during review.
## CI Workflow Events CI workflow events fire when a pipeline run changes state in a connected CI provider (GitHub Actions, GitLab CI, Azure DevOps Pipelines, or Bitbucket Pipelines). When the run is associated with a pull request, `trigger.pullRequest.*` fields are also available, gated on `trigger.ciWorkflow.isPullRequest`.
  • ci\_workflow\_queued : A CI run entered the queue. Use this to track pipeline wait times or alert on queuing delays.
  • ci\_workflow\_started : A CI run started executing. Useful for notifying the team that a build is in progress.
  • ci\_workflow\_completed : A CI run finished regardless of outcome. Check `trigger.ciWorkflow.status` for the result.
  • ci\_workflow\_failed : A CI run ended with a failure. Trigger notifications, create follow-up issues, or post PR comments.
  • ci\_workflow\_cancelled : A CI run was cancelled before completion.
  • ci\_workflow\_timed\_out : A CI run stopped after exceeding its time limit.
For the full list of `trigger.ciWorkflow.*` template variables available in CI events, see the [CI Workflow Event Properties](/docs/reference/event-context#ci-workflow-event-properties) section in the Event Context Reference. ## Manual, Mention & Slash Command
  • manual : Manually triggered using a slash command on an issue, PR, comment, or registered Slack channel.
  • mention : Overcut is @mentioned in an issue, PR, comment, or registered Slack channel. A plain `@overcut` mention in Slack fires this trigger, not slash\_command. An @overcut mention inside a Slack thread is still a mention event, not thread\_reply.
  • slash\_command : A configured slash command is detected. In repository and ticket comments the command appears as you configured it (e.g. /review). In Slack, commands run as /overcut \ (e.g. /overcut review); the token after the /overcut bot prefix is what matches your trigger's SlashCommand field.
  • channel\_message : A top-level message is posted in a registered Slack channel set to **Watch all messages**. Use trigger conditions, such as actor, content, and channel, to filter busy channels.
  • thread\_reply : A reply is posted in a thread in a registered Slack channel set to **Watch all messages**, and no run or session is live on that thread. Replies to a live run or session continue that conversation instead of starting another workflow.
A slash\_command trigger fires when Overcut detects the configured command string. * **Repository and ticket comments** (GitHub, GitLab, Bitbucket, Azure DevOps, Jira): the trigger matches the command as you configured it, for example /review. Enable requireMention to require an @overcut mention before the command. * **Registered Slack channels**: the user types /overcut \; the token after /overcut is matched against the SlashCommand field. A plain @overcut message in Slack does **not** match a slash-command trigger; configure a mention trigger for that. For setup instructions, see the [Slash Command Guide](/docs/workflows/trigger-with-slash-command). For Slack-specific setup, see [Slack integration](/docs/integrations/slack). Slack channels set to **Watch all messages** can trigger workflows from top-level messages and thread replies, including bot replies from third-party services. Overcut suppresses its own messages. Add actor, content, and channel conditions when you use `channel_message` or `thread_reply` in busy channels. ## How Triggers Are Evaluated Overcut matches incoming events against the configured **Trigger Event** and optional filters, then manages execution through resource locking and priority queuing. For Slack messages in channels set to **Watch all messages**, top-level messages are evaluated as `channel_message` events. Thread replies are evaluated as `thread_reply` events only when no run or session is live on that thread. If a run or session is live, the reply continues the existing conversation and does not start a duplicate workflow. A webhook, manual call, or registered Slack message is received by Overcut. Platform-specific events are converted to standardized formats (e.g., Jira issue events become issue\_opened, issue\_commented). The normalized event is compared to the trigger identifier defined in your Workflow. Optional filters like repository name, project key, or label value are evaluated. Matching workflows are queued for the specific resource (issue/PR/repo) with priority ordering and event deduplication. Workflows execute in priority order with resource locking to prevent conflicts. For field-level payload details, see the [Trigger Execution reference](/docs/reference/trigger-execution). Overcut uses [resource locking and priority queuing](/docs/workflows/workflow-execution-control) to ensure predictable execution order and prevent race conditions when multiple workflows target the same resource. ## Using Triggers in a Workflow When you create a new Workflow, Overcut inserts a Trigger block by default. You can customize its settings directly in the canvas UI. Go to the Workflows tab and click Create Workflow. Select the Trigger Container to open the Properties panel for the highlighted card. Use the canvas-level Add trigger button to insert new cards, drag the handle on each card to reorder them, and remove any unused cards from the inline menu. Drag from the container’s right-hand handle into the first action, agent, or logic block. Once connected, continue chaining steps as usual; the container automatically routes whichever trigger matches into that first step. For workflows that need to work with multiple repositories or automatically identify the most relevant repository for a ticket, consider adding a repo.identify step after your trigger. This step uses AI-powered analysis to determine which code repositories are most relevant to the ticket context. Learn more in our Repository Mapping guide. ## Accessing Trigger Data Once a trigger fires, all event data is available throughout your workflow via template variables. You can access properties like `{{trigger.issue.title}}`, `{{trigger.repository.fullName}}`, `{{trigger.pullRequest.headBranch}}`, and many more. Complete reference of all available event properties, organized by event type with practical examples. Deep dive into multiple triggers, event merging, priority queuing, and sequential execution mechanics. # Workflow Execution Control Source: https://docs.overcut.ai/docs/workflows/workflow-execution-control Understand how Overcut manages workflow execution through triggers, resource locking, priority queuing, and event deduplication. Overcut's workflow execution system ensures predictable, efficient automation by controlling when and how workflows run. This system prevents race conditions, reduces redundant executions, and allows you to prioritize critical workflows. Prevents multiple workflows from running simultaneously on the same issue, or PR. Controls execution order when multiple workflows are queued for the same resource. Merges rapid-fire events into single workflow executions with the latest state. Queued workflows run by priority level, and workflows with the same priority run first-come, first-served. ## How Workflow Execution Works When an event occurs (like opening an issue or creating a PR), Overcut follows this execution pipeline: A webhook from GitHub, GitLab, Jira, or manual trigger is received. Overcut finds all workflows with matching triggers and conditions. Each matching workflow is queued for the specific resource (issue or PR) using a lock key. If a workflow is already queued for the same resource, events are merged with the latest state. Queued workflows are ordered by priority (1-100 scale), then by queue time (FIFO). Only one workflow runs per resource at a time, preventing conflicts and race conditions. ## Resource Locking ### Lock Key Structure Overcut uses **lock keys** to ensure only one workflow runs per resource at a time: * **Issues**: `owner/repo:issue:123` * **Pull Requests**: `owner/repo:pr:456` ### Scheduled Workflow When using "Per-Repository" execution mode, Overcut starts an execution for each repository selected. For [Scheduled Workflows](/docs/workflows/scheduled-workflows), Overcut automatically **skips a new run if the previous one is still in progress for the same lock key** (issue, PR, or repository). This guarantees that long-running maintenance jobs don’t pile up and overload your workers. ### Why Locking Matters Without resource locking, multiple workflows could: * Make conflicting changes to the same issue * Create duplicate comments or labels * Waste resources on redundant operations * Cause race conditions and unpredictable behavior ### Example: Issue Workflow Locking ``` Issue #123 receives rapid events: 1. issue_opened 2. issue_labeled (bug) 3. issue_assigned 4. issue_labeled (urgent) Lock Key: "myorg/myrepo:issue:123" Result: All workflows for issue #123 queue behind the lock Only one workflow runs at a time for this specific issue ``` ## Priority Queuing ### Priority Scale (1-100) Control workflow execution order using numeric priority: * **1 = Highest Priority** (executes first) * **5 = Default Priority** (normal workflows) * **100 = Lowest Priority** (executes last) Lower numbers execute first. Think of priority as "position in line" - priority 1 is first in line. ### Priority Guidelines * Use the full 1-100 range for fine-grained control * Create your own prioritization scheme, for example: * **1-20**: Critical security scans, system failures * **21-40**: Code reviews, bug fixes, urgent issues * **41-60**: Normal automation, standard workflows * **61-80**: Documentation updates, metrics collection * **81-100**: Background analytics, cleanup tasks ### Setting Priority in UI Navigate to your workflow and click the settings/metadata section. Enter a number between 1-100 in the Priority field. Lower numbers execute first. ### Priority in Action ``` Queue for issue #123 (same lock key): 1. "Update Metrics" (priority: 8) - queued at 10:00:00 2. "Security Scan" (priority: 2) - queued at 10:00:15 3. "Auto-assign" (priority: 5) - queued at 10:00:30 Execution Order: 1. Security Scan (priority 2) ← Executes first 2. Auto-assign (priority 5) ← Executes second 3. Update Metrics (priority 8) ← Executes last ``` ## Event Deduplication ### How Deduplication Works When multiple events occur rapidly for the same resource and workflow: 1. **First Event**: Creates queue entry 2. **Subsequent Events**: Merge with existing queue entry 3. **Final State**: Workflow executes with the latest merged state ### Benefits * **Efficiency**: Reduces redundant executions by 60-80% * **Accuracy**: Workflows see the final state, not intermediate changes * **Resource Savings**: Less compute, storage, and API usage * **Better UX**: Fewer duplicate comments or actions ## Trigger Delays and Execution Control ### How Delays Interact with Queuing [Trigger delays](/docs/workflows/triggers#trigger-delays) work with the execution control system: 1. **Delay Applied**: When trigger first fires, workflow queues with future `readyAt` time 2. **Event Merging**: Additional events during delay window merge with queued workflow 3. **Priority Respected**: When delay expires, workflow processes according to priority 4. **Lock Acquired**: Workflow executes when it reaches front of priority queue ## Workspace-level Concurrency Limits Overcut enforces a per-workspace limit on **concurrent workflow executions** based on your subscription plan. This ensures that high demand in one workspace does not impact the rest of your organization. Your workspace's concurrent execution limit is determined by your subscription plan. Check your billing settings to see the exact concurrent run count for your workspace. Use this guidance to manage capacity: * **Monitor your usage**: Track running workflows in the workspace overview to understand current utilization. * **Consider workflow duration**: Long-running workflows consume execution slots longer, reducing availability for other triggers. * **Plan for peak times**: Distribute high-priority workflows across time or adjust trigger frequency when approaching your limit. ## On Hold Release Cycle When a workspace reaches its concurrency limit, new workflow runs enter an **On Hold** state until capacity becomes available. ### What you will see * The run timeline shows an On Hold entry with a message indicating that workspace capacity has been reached. * Your workflow's trigger payload is preserved, so nothing is lost and no manual re-triggering is needed. ### How release works * When a running execution completes, the oldest On Hold run is automatically released (first-in, first-out within the workspace). * Released runs resume automatically and progress through normal execution without any user interaction required. ## Related Documentation * **[Triggers](/docs/workflows/triggers)**: Understanding when workflows start * **[Advanced Trigger Execution](/docs/reference/trigger-execution)**: Deep dive into multiple triggers, event merging, and priority behavior * **[Workflow Metadata](/docs/how-to/workflow-builder)**: Configure timeout, priority, default model, and status update settings * **[Building Blocks](/docs/building-blocks)**: Core workflow components * **[Import & Export](/docs/workflows/workflow-import-export)**: Managing workflow definitions * **[Overcut Playbooks](/docs/quick-starts/playbooks)**: Ready-to-use workflow templates with priority settings # Import & Export Workflows Source: https://docs.overcut.ai/docs/workflows/workflow-import-export Move Workflows between projects, back-up complex logic graphs, and share automations with your teammates. Design a Workflow once, reuse it everywhere. Overcut lets you **export** any existing Workflow as a portable JSON artifact and **import** that artifact into another project or workspace. For templates that your own workspace maintains, the [Workspace Library](/docs/reference/workspace-library) offers **Install from Library** instead; see [File import or Library template?](#file-import-or-library-template) below. Save the current Workflow as a .json file on your computer. Bring a Workflow .json file into Overcut, map its agents, and start iterating. The feature is available on all plans. You need the workflow\.view permission to export and workflow\.create to import. *** ## Export a Workflow Navigate to Workflows and select a Workflow. In the builder top-bar, click the Export icon. Overcut immediately downloads a file named `{{workflow-name}}.json`. *** ## Import a Workflow In an empty or existing project, open any Workflow in the Builder (or create a new one). Click the Import icon in the top-bar and select the .json file you exported earlier. Overcut parses the file and opens the Import Workflow dialog. The Workflow Name field is pre-filled from the file; change it if you’d like. Every agent referenced in the file must be mapped to an existing agent in the current project. Use the dropdown for each row to select the correct agent role. Click Import. After the server validates the mapping, a success toast appears with Open Workflow. Click it to jump straight into your new Workflow. • The artifact only contains the Workflow definition, not run history or execution metrics.
• Every referenced agent must exist in the target project, or in the Workspace Library, before import.
• Context parameter definitions and values are not exported. The file lists the keys the Workflow references; the imported draft publishes only after those keys are defined in the target workspace.
• Other external text references (e.g., repositories, labels) may need to be manually updated after the import. ### File import or Library template? Use **Import from File** when you have an exported JSON file, for example from another workspace or from version control. Use **Install from Library** when your workspace maintains the Workflow as a template in the [Workspace Library](/docs/reference/workspace-library#install-a-workflow-template). Both create an independent, project-owned draft and ask you to map project-owned agents. The Library skips the file, always installs the template's last published version, and needs no mapping for agents that live in the Library. *** ## JSON File Structure Here’s a shortened example of the exported file. You generally won’t edit this by hand, but it can be useful for version control or advanced CI flows. ```json title="my-workflow.json" theme={"dark"} { "_formatVersion": "1.0.0", "workflow": { "name": "Mention", "definition": { "flow": [ { "to": "git-clone", "from": "", "condition": null }, { "to": "agent-session", "from": "git-clone", "condition": null } ], "name": "Mention", "steps": [ { "id": "git-clone", "name": "Clone Repo", "action": "git.clone", "params": { "branch": "main", "cloneOptions": {}, "repoFullName": "{{trigger.repository.fullName}}" }, "instruction": null }, { "id": "agent-session", "name": "Multi-Agent Session", "action": "agent.session", "params": { "goal": "Help the user with their questions", "agentIds": ["my-agent-id-1", "my-agent-id-2"], "exitCriteria": { "timeLimit": { "maxDuration": "2h" }, "userSignals": { "explicit": ["/done", "thanks"] }, "maxExchanges": 10, "maxUserSilence": "4h" }, "resurrection": { "enabled": true, "preserveDays": 7, "restartCommands": ["bot /restart", "/continue"] }, "interruptible": true }, "instruction": "You are helping the user with their issue. Be helpful and concise." } ], "trigger": { "event": "mention", "conditions": { "field": null, "rules": [ { "field": "context.repository.fullName", "rules": null, "value": "my-org/my-repo", "operator": "equals", "combinator": null } ], "value": null, "operator": null, "combinator": "and" } }, "version": "1.0.0", "priority": 5, "timeoutMs": null } }, "refs": { "agents": [ { "id": "my-agent-id-2", "name": "Senior Developer" }, { "id": "my-agent-id-1", "name": "Product manager" } ], "contextParameters": [ { "key": "base_branch", "description": "Branch that pull requests target" } ] } } ``` *** ## Error Handling If the file is invalid or an agent mapping is missing, Overcut shows a detailed error message. No changes are made until the import succeeds. *** ## Next Steps * After you import a Workflow, it will be available in the Workflows page. * You may want to look at the imported Workflow to add specific conditions or update references to repositories or labels. * If the file lists contextParameters, define each key under [Context Parameters](/docs/reference/context-parameters) before publishing the imported Workflow. # Workflow Versioning Source: https://docs.overcut.ai/docs/workflows/workflow-versioning Understand how Overcut saves workflow drafts, surfaces unpublished changes, and helps you publish or discard updates with confidence. ## Overview Workflows evolve over time. You might tweak an action, experiment with a new trigger, or roll back to an earlier definition while troubleshooting. Overcut keeps every edit safe by **auto-saving your changes as drafts** and guiding you through a lightweight review and publish flow. This page explains how drafts move from your Workflow Builder to production, where to spot unpublished work, and when to publish or discard it. Every edit in the Workflow Builder is saved immediately, so you never lose work if you close the tab or switch tasks. A colored chip in the workspace header shows the number of workflows with unpublished changes and links straight to a consolidated review page. Compare the working draft to the last published version, publish or discard in one place, and jump back to the builder with a click. Side-by-side diffs let you inspect any past version and restore it into your working copy when you need to roll back. ## Draft lifecycle Open any workflow in the **Workflow Builder**. The moment you change a field or update YAML, Overcut creates a **draft** of your workflow. Your browser does not need to stay open. Drafts are saved server-side every few seconds. As soon as at least one draft exists in the workspace, an **Unpublished Changes** chip appears in the workspace header. The chip's counter shows how many workflows contain drafts. Click the chip to open the **Unpublished Changes** review page. Here you can inspect every draft, compare it to the last published version, and decide what to do next. * **Publish** finalizes the draft and makes it the latest published version. You will be prompted for a commit message so teammates understand what changed. * **Discard** removes the draft and reverts the working copy to the last published version. Nothing is deleted from Version History; you can always restore discarded changes later. Automated triggers always execute the most recent **published** version. If no version has ever been published, automation is paused until you publish at least once. The same rule applies to templates in the [Workspace Library](/docs/reference/workspace-library): a template must have a published version before a project can install it, and installing copies that published version. The installed copy starts as a draft in the target project. Context parameter values are not part of the draft; they save immediately and never need a publish. See [Context Parameters](/docs/reference/context-parameters). ## Finding unpublished changes The moment a draft exists, Overcut surfaces it in multiple places: * **Workspace header chip**: A colored **Unpublished Changes** chip appears beside the workspace name. Its badge shows the number of workflows with drafts. Clicking the chip opens the review page. * **Version History**: Drafts show up at the top of the history list, labeled *Draft* so you can compare them against any earlier version. The header chip disappears automatically when all drafts are either published or discarded. ## Reviewing and publishing drafts On the **Unpublished Changes** page you will find: * A filterable list of workflows with drafts, including last-updated timestamps and author avatars. * An inline **side-by-side YAML diff viewer** to highlight exactly what changed. * **Edit** buttons that reopen the draft in the Workflow Builder when you need to make further tweaks. * **Publish** and **Discard** controls that act on the currently selected workflow. When you click **Publish**: 1. Enter a short commit message that summarizes why you are publishing the changes. 2. Overcut saves the draft as a new version and removes it from the "Unpublished Changes" list. 3. Any future manual or automated executions will use the newly published version by default. When you click **Discard**: 1. The draft is deleted. 2. The working copy reverts to the last published version. 3. The workflow disappears from the "Unpublished Changes" list. Publishing is lightweight: think of it as committing code. Publish frequently to keep your workspace predictable. ## Manual executions and drafts When you click **Run** from either the workflow list or the Workflow Builder, Overcut asks which definition you want to execute: 1. **Last published version (default)**: Overcut automatically selects the most recent published version because it is the same definition your triggers and schedules rely on. 2. **Working draft**: Choose this option to test your unpublished edits without publishing them. If a workflow has **never** been published and you leave the default selection, the run is blocked because no committed version exists. Either publish the draft first or change the selector to **Working draft** to continue. Selecting **Working draft** executes the current auto-saved definition immediately, even if no published version exists, so you can validate changes before publishing them. Running a draft is perfect for quick experiments, but only published versions power automation. Publish once you are satisfied with the results. ## Best practices * **Review before you run manually.** Manual runs can target your working draft, but use the diff viewer to confirm changes before executing. * **Discard stale drafts.** If a draft lingers for days, it can confuse collaborators. Delete drafts you no longer plan to finish. Version History keeps a record if you need it later. * **Use commit messages wisely.** Clear messages make it easier for teammates (and future you) to understand why a change was made. Workflows without a published version **cannot** run automatically. Make sure you publish at least once before enabling triggers or schedules. ## Related documentation * [Workflow Version History](/docs/reference/workflow-history): compare versions side-by-side and restore earlier definitions * [Workflow Metadata](/docs/how-to/workflow-builder): configure workflow settings in the builder * [Workflow Execution Control](/docs/workflows/workflow-execution-control): priority queuing, resource locking, and deduplication # Workflows Source: https://docs.overcut.ai/docs/workflows/workflows Understand how Workflows power automation in Overcut with triggers, actions, agents, and visual flow design. Workflows are the heart of Overcut automation. They define end-to-end automations that automatically respond to events, execute complex multi-step processes, and coordinate AI agents to accomplish tasks. Think of them as visual programming for automation: you design the flow, and Overcut executes it reliably. *** ## What is a Workflow? A **Workflow** is a complete automation that defines: * **When** it should run (the trigger) * **What** should happen (the steps and actions) * **How** steps connect and flow (the execution graph) Workflows are Overcut's automation pipelines: a visual, declarative way to build complex automation without writing code. A Workflow is one executable automation. To coordinate the same work item across multiple workflows over time, use an [Orchestration](/docs/orchestrations/overview) to manage the goal and the routing between runs. Design workflows using a visual canvas with drag-and-drop blocks for triggers, actions, and agents. Automatically respond to GitHub events, Jira updates, mentions, slash commands, or scheduled triggers. Integrate AI agents that can make decisions, generate content, and collaborate with users. Build complex workflows with dependencies, parallel execution, and conditional logic. *** ## Core Components Every Workflow consists of these fundamental building blocks: ### **Trigger** The event that starts your workflow execution. Triggers can be: * **GitHub events**: Pull requests opened, issues labeled, comments posted * **Jira events**: Issues created, updated, or commented on * **Interactive triggers**: `@overcut` mentions or slash commands like `/review` * **[Scheduled Workflows](/docs/workflows/scheduled-workflows)**: Time-based triggers for recurring tasks like nightly scans or weekly reports Every Workflow must have exactly one trigger node. This is the entry point that determines when your automation runs. ### **Actions** * **[`git.clone`](/docs/workflows/git-clone)**: Clone repositories for code analysis * **[`repo.identify`](/docs/workflows/repo-identify)**: Automatically determine relevant repositories for tickets * **[`script.run`](/docs/workflows/run-script)**: Run deterministic bash scripts without invoking an AI agent or LLM * **[`agent.run`](/docs/workflows/agent-run)**: Single-agent execution for straightforward tasks * **[`agent.session`](/docs/workflows/agent-session)**: Multi-agent sessions with coordination and iteration To read about the differences between the two agent actions, see the [Agent Differences](/docs/workflows/agent-differences) page. ### **Flow** The connections between steps that define execution order and dependencies. *** ### **Event Processing Flow** 1. **Event Reception**: Webhooks from GitHub, Jira, or other providers are received 2. **Normalization**: Events are converted to standardized formats 3. **Trigger Matching**: Overcut evaluates which Workflows should run 4. **Execution Queuing**: Matching workflows are queued for execution 5. **Step Processing**: Each step runs according to the defined flow 6. **State Management**: Context and results are preserved between steps 7. **Completion**: Final results are published and cleanup occurs *** ## Creating a Workflow The **Workflows** page offers four starting points: **Create** for a blank workflow, **Add from Playbook** for a public template from the [Playbook Catalog](/docs/quick-starts/playbooks), **Install from Library** for a template your workspace maintains in the [Workspace Library](/docs/reference/workspace-library), and **Import from File** for an exported JSON file. The last three all create a project-owned draft you then customize. ### **Step 1: Define the Problem** Start by understanding what you want to automate: * What event should trigger the workflow? * What should happen when it runs? * What are the expected outcomes? ### **Step 2: Design the Flow** Break your automation into logical steps: * **Preparation**: Clone repos, gather context, validate inputs * **Processing**: Run AI agents, perform analysis, make decisions * **Action**: Update tickets, create branches, send notifications * **Cleanup**: Archive results, update status, close sessions ### **Step 3: Configure Components** For each step, configure: * **Parameters**: Static values or dynamic variables from previous steps * **Instructions**: Specific guidance for AI agents * **Conditions**: When steps should run or be skipped * **Timeouts**: Maximum execution time for each step ### **Step 4: Connect the Flow** Define how steps relate to each other: * **Sequential**: Steps run one after another * **Parallel**: Independent steps run simultaneously - Coming soon * **Conditional**: Steps run based on previous results - Coming soon * **Loops**: Steps repeat until conditions are met - Coming soon *** ## Advanced Features ### **Template Variables** Use dynamic values throughout your workflow: * **`{{trigger.issue.title}}`**: Access trigger event data * **`{{outputs.git-clone.repositoryPath}}`**: Reference previous step outputs * **`{{params.base_branch}}`**: Reference a [context parameter](/docs/reference/context-parameters), a value that each project, repository, workflow, orchestration, or agent can set for itself For [Run Script](/docs/workflows/run-script) steps, pass dynamic workflow data through **Environment Variables** instead of template-interpolating the **Bash Script** body. This keeps trigger text and previous step output as data that the script can read from environment variables. See the complete [Event Context Reference](/docs/reference/event-context) for all available trigger properties and practical examples. ### **Inspect Run Context** Open a workflow run's details and select **Context** to open the **Run Context** panel. The panel shows the actual `trigger` data, step `outputs`, and resolved context parameters under `params` available to that run's steps and templates. Use **Run Context** to confirm values used by template expressions such as `{{trigger.issue.title}}`, `{{outputs..}}`, and `{{params.}}`. The JSON is read-only, and step outputs update while the run executes so you can troubleshoot variables and verify what each completed step produced. ### **Monitoring** Overcut provides visibility into workflow and agent behavior through: * **Workflow status**: Track workflow progress (Running, Completed, Failed, Timeout) * **Agent status**: Monitor agent sessions (Running, InSession, WaitingForReply, Terminating, Completed, Failed) * **Execution logs**: Detailed logs for each step and agent with the full tool calls and context available to the agent ### **Agent Engine Indicators** Agent engine indicators help you confirm which engine powers each workflow and step. * **Workflow catalog**: Each workflow card shows the engine logo so you can compare workflows at a glance. * **Run details**: Step lists include the engine logo for each step, helping you verify engine usage during execution. Use engine indicators to validate that workflows and steps align with your team’s preferred agent engines before you share or reuse them. ### **State Management** Context is preserved throughout execution: * **Workflow Context**: Global variables accessible to all steps * **Step Outputs**: Results from each step available to subsequent steps *** ## Next Steps Now that you understand Workflows, explore these topics: * **[Triggers](/docs/workflows/triggers)**: Learn about different trigger types and configuration * **[Actions and Agents](/docs/workflows/agent-differences)**: Understand the differences between agent.run and agent.session * **[Building Blocks](/docs/building-blocks)**: Deep dive into the core components * **[Quick Starts](/docs/quick-starts)**: Step-by-step guides for common workflows * **[Repository Management](/docs/repositories/repository-mapping)**: Understand how workflows interact with code Ready to build your first Workflow? Start with a simple workflow and gradually add complexity as you become familiar with the platform.