Integrations
VibeFlow integrates with external services to sync your project data where your team already works.
Atlassian Integration
Connect your Atlassian Cloud account to sync VibeFlow content to Confluence and import work from Jira.
Connecting
- Navigate to the Integrations tab in the top-level sidebar
- Click Connect Atlassian Account
- You'll be redirected to Atlassian to authorize the axiomstudio app
- Grant the requested permissions (Confluence + Jira scopes)
- You're redirected back to VibeFlow — connected!
Each team member connects their own Atlassian account. This preserves identity: when you create a document in VibeFlow, the corresponding Confluence page is authored by you in Confluence.
If you previously connected for Confluence only, reconnecting will prompt you to grant additional Jira scopes.
Confluence Sync
When Confluence is enabled, VibeFlow automatically syncs your documents and contexts to a "VibeFlow" Confluence space:
What syncs:
- Design documents (PRDs, architecture, style guides)
- Project and feature contexts
How it's organized:
VibeFlow (Confluence space)
└── {project-name}/
├── context/
│ ├── project-context.md
│ └── feature-contexts...
└── documents/
├── PRDs/
├── Architecture/
└── General/
Transparent sync — No extra steps. Edit a document in VibeFlow and it automatically syncs to Confluence. A sync status badge on each document shows the current state (synced, syncing, failed).

Import from Confluence — Import existing Confluence pages into VibeFlow as documents or contexts. Three import modes:
- Single page — Import one page by URL or search
- Page tree — Import a parent page and all its children, preserving hierarchy
- Space mapping — Browse a Confluence space and select pages to import
Confluence References — Link Confluence pages as read-only references attached to projects or features. Agents can read reference content during implementation but cannot modify the source page. References are cached with a 15-minute TTL and refreshed automatically.
Jira Integration
VibeFlow's Jira integration follows a Jira-primary model: Jira is the source of truth for ticket management, and VibeFlow is the AI accelerator that implements the work.
How it works:
- Import Jira tickets into VibeFlow
- AI agents implement the work
- Status, PR links, and commit details flow back to Jira automatically

Import Wizard
The Jira Import Wizard is a 3-step process:

-
Select Items — Browse by sprint or search by keyword/JQL
- Sprint tab: Select a board and sprint, then pick tickets
- Search tab: Search by ticket key (PROJ-123) or keyword; JQL queries supported
- Already-imported tickets are greyed out
- Tickets are grouped by Epic with auto-type detection (Bug → Issue, Task/Story → Todo)
-
Select Branch — Choose which git branch the imported items should target
- Agents on that branch will pick up the work
- Defaults to the project's default branch
- Shows branches with active agent sessions
-
Import — Review progress as tickets are imported
- Epic → Feature auto-mapping (existing features matched by name, or new ones created)
- Jira attachments downloaded and uploaded as VibeFlow assets (25MB limit)
Jira Status Sync
Status changes in VibeFlow automatically sync to Jira:
| VibeFlow Event | Jira Action |
|---|---|
Agent starts implementing | Transition to "In Progress" |
Item marked done | Transition to "Done"/"Closed"/"Resolved" |
| Execution log published | Comment posted to Jira ticket |
| Description updated | Jira description updated (Markdown to ADF) |
Sync is asynchronous via a Redis queue. Each job independently resolves a valid Atlassian token using a fallback chain (acting user → project creator → any org user with Jira enabled).
Jira Sync Badge
Imported items display a clickable badge showing the Jira key (e.g., PROJ-123) with sync status:
- Linked (teal) — Imported, sync active
- Syncing (yellow) — Status transition in progress
- Completed (green) — Done transition and comment posted
- Failed (red) — Sync error; hover for details, click to retry
Jira Configuration
Per-organization settings available in the Jira integration tab:
- Auto-transition — Automatically sync status changes to Jira
- Completion comments — Post completion details (commit, PR, lines changed) as Jira comments
- Import attachments — Download Jira attachments on import
- Commit key prefix — Prefix git commits with Jira key (e.g.,
PROJ-123: Add login form)
Agent Prompt Integration
When working on Jira-imported items, agents automatically:
- Prefix commit messages with the Jira key
- Include
jira_syncmetadata in work item API responses
Team Connection Status
The Integrations tab shows which team members have connected their Atlassian accounts. Higher team coverage means better identity preservation in Confluence and Jira.
GitHub Integration
Connect GitHub to create pull requests automatically from agent work, sync issues, and run check runs for QA and security gates.
Connecting
- Navigate to Integrations → GitHub tab
- Click Connect GitHub
- Authorize via GitHub OAuth
- Select which repositories to link to VibeFlow projects

Pull Request Creation
When an agent completes work on a feature or issue, VibeFlow can automatically create a GitHub pull request:
- Auto-create PRs — Configure per-project whether PRs are created automatically on completion
- Draft PRs — PRs are created as drafts by default
- PR body — Includes execution summary, files changed, commit history, and links to VibeFlow work items
- Per-feature PRs — Features with completed todos get a consolidated PR
- Per-issue PRs — Issues can also trigger PR creation
Manual PR Creation — Source Branch Picker
When you create a PR manually from the + New → Pull Request menu, the Source Branch dropdown lists every branch in the linked GitHub repo. As of the most recent update, branches that exist locally on a connected agent's worktree but haven't been pushed to origin yet also appear in the dropdown — but rendered as a disabled option with the suffix (not pushed to origin).
This closes the gap where the Teams view showed an agent working on (e.g.) main-wt-1778773439 but the Create-PR modal silently hid that branch. Now you can see the agent's branch is real, see why you can't open a PR for it yet, and tell the agent to push before retrying.
The Destination Branch dropdown still only shows pushed-to-origin branches — you can't merge into a branch GitHub doesn't have.

Check Runs
VibeFlow registers check runs on pull requests for:
- Security Review — Shows whether the security lead has approved the changes
- QA Verification — Shows whether the QA lead has verified the implementation
VibeFlow review(orVibeFlow review / <base branch>for repositories linked earlier) - Vera's review result, when PR reviews are enabled for the repository; see Code Review with Vera
Check run status updates in real-time as reviews complete in VibeFlow.
Issue Sync
Link GitHub issues to VibeFlow work items for bidirectional status tracking:
- Import GitHub issues into VibeFlow
- Status changes in VibeFlow update the linked GitHub issue
Configuration
Per-project GitHub settings:
- Repository — Which GitHub repo is linked
- Auto-create PRs — Enable/disable automatic PR creation
- Draft PRs — Create PRs as draft by default
- Base branch — Default target branch for PRs
- PR reviews - Each linked repository has its own Vera review settings card; see Code Review with Vera
- Auto-push agent commits to origin - A project-wide agent push instruction, on by default; see Configuration under Bitbucket Integration below
Vendor Logs
The GitHub Logs sub-tab shows all API interactions: PR creation, check run updates, issue syncs, and any errors with timestamps and details.
Bitbucket Integration
Connect Bitbucket Cloud to create pull requests automatically from agent work and surface QA and security gates directly on your PRs — the same source-control automation as GitHub, for teams on Bitbucket.
Connecting
- Navigate to Integrations → Bitbucket tab
- Click Connect Bitbucket
- Authorize via Bitbucket OAuth — once linked you'll see Connected as @your-username
Each team member connects their own Bitbucket account. The Bitbucket panel has Setup, Logs, and Team sub-tabs, so you can see who on your team is connected.
The VibeFlow Vera app
For code review, a workspace admin can install the VibeFlow Vera app on the Bitbucket workspace once, from the link on the Bitbucket panel. With the app installed, pull request and comment events reach Vera through the app and Vera's review comments and build status are posted as the app, so there is no repository webhook to maintain and nobody's personal token is used for publishing. The panel lists the workspaces that have installed it. Your own Bitbucket connection still identifies who asked for a review; workspaces without the app keep working exactly as before.
For operators: the app is switched on per environment under Operator → Cloud settings.
| Setting | Value |
|---|---|
bitbucket_forge_app_id | The app's id from the Atlassian developer console, ari:cloud:ecosystem::app/<uuid>. Until it is set, the environment ignores every app event. |
bitbucket_forge_install_url | The app's sharing link from the developer console (Distribution). It becomes the install link on the Bitbucket panel. |
A saved setting takes effect on every server within a minute, with no restart.
The environment variables BITBUCKET_FORGE_APP_ID and BITBUCKET_FORGE_INSTALL_URL still work as a fallback, and a Cloud setting overrides them.
A value that is not an app id, or a link that is not https, is ignored and the fallback applies.
Each app environment must point at its own server: deploy the app with VIBEFLOW_BASE_URL=https://cloud.axiomstudio.ai forge deploy -e production for production and with the UAT address for -e development.
Linking a Repository
Repositories are linked per project, from Project Settings → Integrations → Source Control:
- Choose Bitbucket as the source control provider
- Select a Workspace from the dropdown
- Select a Repository in that workspace
- Click Link Repository
A project links one source-control provider at a time — GitHub, Bitbucket, GitLab, or Azure Repos. If a project is already linked to another provider, unlink it first. Unlinking stays available even when the provider connection is gone, so you can always switch providers without getting stuck.

Pull Request Creation
When an agent completes work on a feature or issue, VibeFlow can automatically open a Bitbucket pull request:
- Auto-create PRs — Configure per project whether PRs are created automatically on completion
- Draft PRs — PRs are created as drafts by default
- PR body — Includes the execution summary, files changed, commit history, and links back to the VibeFlow work items
- Per-feature and per-issue PRs — Both completed features and issues can trigger PR creation
You can also open a PR manually at any time from the + New → Pull Request menu.
Build Statuses — QA & Security Gates
VibeFlow posts build statuses on the pull request's commit, so your review gates are visible right inside Bitbucket:
- QA Verification — Reflects whether the QA lead has verified the implementation
- Security Review — Reflects whether the security lead has approved the changes
- VibeFlow review - Vera's review result, when PR reviews are enabled for the repository; see Bitbucket Differences
Statuses update as the corresponding reviews complete in VibeFlow.
Configuration
Per-project Bitbucket settings:
- Auto-create PRs — Open a PR automatically when work completes
- Draft PRs — Create PRs as drafts by default
- Issue PRs — Also open PRs for completed issues, not just features
- Close source branch — Delete the PR's source branch automatically on merge
The project's Auto-push agent commits to origin option, on the Source Control page for every provider, changes the instructions coding agents receive when their session starts.
It is on by default, and only the project owner or an org admin can change it.
When it is on, Developer, Architect and Principal Engineer agents are told to run git push origin HEAD after every commit, never force-push, and keep working if a push fails, so diffs and PRs are viewable sooner.
When it is off, they are told not to push automatically, but an agent working on a PR repair batch still pushes its one fix to the PR.
VibeFlow itself never pushes or blocks a push.
A change applies from an agent's next session start, and cloud-dispatched sessions do not receive the instruction.
Vendor Logs
The Bitbucket Logs sub-tab shows all API interactions — connection, workspace and repository listing, pull request creation, and build-status updates — with timestamps and error details, so you can diagnose issues without contacting support.
GitLab Integration
Connect GitLab.com to open merge requests automatically from agent work and follow their state in VibeFlow — the same source-control automation as GitHub and Bitbucket, for teams on GitLab.
Only GitLab.com is supported. Self-managed GitLab instances cannot be connected yet.
Connecting
- Navigate to Integrations → GitLab tab
- Click Connect GitLab — GitLab opens in a new browser tab
- Authorize VibeFlow in GitLab
- Return to VibeFlow — the panel updates on its own and shows Connected as @your-username
Each team member connects their own GitLab account, and the projects you can link depend on your own GitLab permissions. The GitLab panel has Setup, Logs, and Team sub-tabs; Team lists who in your organization has connected GitLab. Disconnect on the Setup sub-tab removes your connection.

Linking a Repository
Repositories are linked per project, from Project Settings → Integrations → Source Control:
- Choose GitLab as the source control provider
- Search the Repository picker — it lists the GitLab projects you are a member of, across all your groups and namespaces, shown as
namespace/project - Click Link Repository
If a project doesn't appear in the search results, type its full namespace/project path and choose Link "…" to link it directly; VibeFlow checks that the project exists first.

A VibeFlow project can link more than one GitLab repository — use Link another to add more, and Unlink next to a repository to remove it.
As with the other providers, a project links one source-control provider at a time. If it is already linked to GitHub, Bitbucket, or Azure Repos, unlink that provider first. Unlinking stays available even after your GitLab connection is gone, so you can always switch providers.
When you link a repository, VibeFlow registers a webhook on the GitLab project so merge request updates reach VibeFlow. Registering webhooks needs the Maintainer role on the GitLab project. If GitLab refuses, the repository is still linked but live merge request updates are unavailable; ask a Maintainer to unlink and link the repository again. Unlinking a repository also removes its webhook.
Merge Request Creation
When a feature or issue is completed, VibeFlow can open a GitLab merge request automatically:
- Source and target — The MR goes from the work item's target branch into the repository's default branch. Work that targets the default branch itself gets no MR.
- Draft MRs — MRs are created as drafts by default
- MR description — Generated from the completed work in the selected project and repository
- No duplicates — If the same work item completes again, it keeps its existing MR instead of opening a second one
- Several repositories — When a project links more than one GitLab repository, each work item must name its target repository; VibeFlow never guesses
Agents connected through MCP can also open a merge request with create_pr, which detects GitLab from the project's settings (or the GitLab-specific create_gitlab_pr), and post merge request comments with comment_gitlab_pr. When a project links more than one repository, pass the repository to use. The branch must already be pushed to GitLab.
Merge Requests in the Pull Requests Tab
The project's Pull Requests tab lists the GitLab merge requests VibeFlow opened, alongside GitHub and Bitbucket pull requests, with their source and target branches, the work item that produced them, and their draft, open, merged, or closed state. Merge requests created directly in GitLab are not listed. States update from the GitLab webhook and refresh from GitLab when you open the tab. If GitLab is unreachable, the last known state is shown.

Configuration
Per-project GitLab settings, shown once a repository is linked:
- Auto-create MR when a feature or issue is completed — Open an MR automatically when work completes (on by default)
- Create as Draft MR — Create MRs as drafts (on by default)
- Delete source branch after merge — Remove the MR's source branch when it is merged (on by default)

Vera pull request reviews are available for GitHub, Bitbucket, Azure Repos, and GitLab. See Code Review with Vera.
Vendor Logs
The GitLab Logs sub-tab shows GitLab activity — account connections, merge request creation with the branches and MR link, and failed webhook registrations — with timestamps and error details, so you can diagnose issues without contacting support.

Slack Notifications
Send real-time project notifications to Slack channels when important events happen in your VibeFlow projects.
Setting Up Slack Webhooks
- Navigate to the Integrations tab in the top-level sidebar
- Click the Slack panel
- Add a new webhook:
- Name — Descriptive label (e.g., "engineering-alerts")
- Webhook URL — Your Slack Incoming Webhook URL
- Click Save — VibeFlow sends a test message to verify the webhook
Webhooks are org-level — one webhook can receive notifications from multiple projects.
Linking Projects to Webhooks
Each project can be linked to one or more Slack webhooks:
- Open a project → Settings tab → Notifications
- Check the webhooks that should receive notifications for this project
- Toggle individual event types on or off
Notification Events
Events are grouped by category:
| Category | Events |
|---|---|
| Projects | Project created, archived, deleted |
| Features | Feature created, archived, deleted |
| Todos | Todo created, completed, rejected |
| Issues | Issue created, completed, rejected |
Each event type can be independently enabled or disabled per project.
Notification Format
Notifications are sent as Slack Block Kit messages with:
- Header — Event type label
- Body — Entity name with key details
- Deep link — "Open in VibeFlow" link to jump directly to the relevant item
Health Monitoring
VibeFlow monitors webhook health automatically:
- If a webhook fails to deliver, it enters degraded state
- Degraded webhooks are retried periodically by a leader-elected health checker
- Webhooks that recover are automatically marked healthy
- The Slack panel shows current health status for each webhook
ClickUp Integration
VibeFlow's ClickUp integration supports both ClickUp-primary and VibeFlow-primary workflows. You can import existing ClickUp tasks into VibeFlow for agent implementation, or push VibeFlow features, todos, issues, documents, comments, attachments, tags, and status changes back to ClickUp.
This integration is gated behind the feature_clickup feature flag and must be enabled per organization.
Note: ClickUp integration is currently in limited rollout. Contact your admin to enable the
feature_clickupflag for your organization.
Connecting
- Navigate to Settings or Integrations and open the ClickUp panel
- Click Connect ClickUp
- Authorize the ClickUp OAuth app
- Select the workspace VibeFlow should use for browsing, imports, and sync
- Configure a project push target in Project Settings -> Integrations -> ClickUp
Each team member can connect their own ClickUp account. For background sync jobs, VibeFlow first tries the acting user's token and can fall back to another connected user in the organization when needed.
ClickUp Task Import
The ClickUp Import Wizard is a 4-step process:
-
Select Tasks — Browse the ClickUp hierarchy or search by keyword
- Browse by workspace -> space -> folder -> list -> tasks
- Folderless lists appear beside folders
- Search can run within the current list or across the connected workspace
- Already-imported tasks are marked unavailable so they are not linked twice
-
Select Mapping — Choose how imported tasks become VibeFlow work
- Import as todo when the work belongs to a feature
- Import as issue for standalone or featureless work
- Choose an existing feature, create a new feature, or leave an issue featureless
- New feature names can be suggested from the ClickUp folder/list path
-
Select Branch — Choose the target git branch and repository for the imported work
- Imported todos and issues get the selected
target_branch - Agents polling that branch can claim the work
- If no branch is selected, the project default branch is used
- Imported todos and issues get the selected
-
Import — VibeFlow fetches each selected ClickUp task and creates the VibeFlow item
- Task name becomes the todo/issue title
- Task description becomes the VibeFlow description
- ClickUp priority is mapped to VibeFlow priority
- ClickUp status is mapped through the configured status mapping
- ClickUp tags are imported into VibeFlow tags
- A ClickUp link record is created with
push_direction: importedandsync_status: linked
ClickUp task imports are idempotent by task link: if a ClickUp task is already linked to a VibeFlow item, the import is rejected instead of creating a duplicate.
VibeFlow to ClickUp Push
VibeFlow can also push local work into ClickUp:
- Single work item push — Push a todo or issue into the configured ClickUp list
- Feature push — Push a VibeFlow feature as a ClickUp folder and enqueue its todos as ClickUp tasks
- Auto-push — When ClickUp is enabled and a default target is configured, newly-created items can be enqueued for ClickUp creation
- Field sync — Title, description, priority, tags, and configured custom fields can update the linked ClickUp task
- Comment sync — VibeFlow comments can be posted to the linked ClickUp task
Push operations use an asynchronous write-ahead log (WAL). The UI returns quickly with an enqueued status, then the ClickUp worker creates or updates the external task. The worker records failed operations, retries recoverable failures, and uses idempotent link/folder handling to avoid duplicate ClickUp tasks or folders after partial failures.
ClickUp Status Sync
Status changes in VibeFlow can sync to ClickUp:
| VibeFlow Event | ClickUp Action |
|---|---|
| Imported ClickUp task | Create todo or issue with mapped VibeFlow status |
| Todo or issue status changes | Update linked ClickUp task status using the export mapping |
| Title, description, or priority changes | Update linked ClickUp task fields |
| Tags change | Update linked ClickUp task tags |
| Execution/activity comment published | Post a comment to the linked ClickUp task |
Status mapping is configured per ClickUp list. The mapping supports:
- Multiple VibeFlow statuses mapped to one ClickUp status
- One import target for each ClickUp status
- Export-only mappings for additional VibeFlow statuses
donequalifiers for QA and Security review states, so "done but not QA verified" can map differently from fully verified work
Default mappings are provided for common ClickUp statuses such as backlog, scoping, in development, testing, shipped, and cancelled, but real ClickUp list statuses are loaded from the ClickUp API so each project can match its workspace configuration.
ClickUp Sync Badge
Linked todos and issues display ClickUp metadata on the detail view:
- ClickUp Sync Badge — Clickable badge linking to the ClickUp task
- ClickUp Detail Section — Collapsible panel showing task ID, ClickUp status, push direction, and sync status
- Direction — Shows whether the item was
importedfrom ClickUp orpushedfrom VibeFlow - Sync Status —
linked,syncing,completed,failed, ordead_letter
Failed and dead-lettered syncs show the error message so admins can diagnose and retry.
ClickUp Configuration
Project settings expose ClickUp controls:
- ClickUp Documents Sync — Project-owner toggle that automatically pushes VibeFlow documents to ClickUp Docs when created or updated
- ClickUp Push Target — Default ClickUp space and list where pushed work items are created
- ClickUp Status Mapping — Per-list mapping from ClickUp statuses to VibeFlow statuses, including QA/Security qualifiers for
done
Organization-level configuration also controls whether ClickUp is enabled, whether auto-transition and completion comments are enabled, whether attachments are imported, whether auto-push is enabled, and whether attachments should be pushed.
ClickUp Docs
ClickUp Docs can move in both directions:
- Import ClickUp Docs — Imported ClickUp Docs become live, read-only references. Content is fetched from ClickUp on demand, matching Confluence reference behavior.
- Push VibeFlow Documents — VibeFlow documents can be pushed to ClickUp Docs. If a linked ClickUp Doc already exists, edits update that doc instead of creating a duplicate.
- Auto document sync — When enabled for a project, new or updated VibeFlow documents are pushed to ClickUp automatically.
When pushing a document, VibeFlow prefers the ClickUp space associated with the project's linked feature folders, then falls back to the configured default space.
Comments and Attachments
For linked ClickUp tasks:
- ClickUp comments can be imported for deduplication tracking
- VibeFlow comments can be pushed to ClickUp
- ClickUp attachments can be imported into VibeFlow assets when attachment import is enabled
- Attachment and comment operations are logged in the integration vendor logs
Sync Health and Logs
The ClickUp integration exposes health and recovery controls:
- Health status — Reports linked item count, pending syncs, failed syncs, recent dead letters, last poll time, and webhook status
- Retry failed syncs — Requeues dead-lettered WAL entries for another attempt
- Synced links — Lists ClickUp task links for a project
- Vendor logs — Records import, search, docs, comments, attachments, push, and sync operations with success/failure status and request context
ClickUp also supports webhook and polling paths. Webhooks provide near-real-time updates where configured, while polling acts as a fallback for sync health and recovery.
Azure DevOps Integration
Connect an Azure DevOps organization to import Boards work items and use Azure Repos Git. Boards changes, status, comments, and attachments flow back to Azure DevOps. Repository links and PR automation use the same saved connection with additional Code permissions.
The Boards setup below covers work items, comments, attachments, and relations. For repository setup, branches, PR tools, service hooks, and agent credentials, see Azure Repos. Azure Wiki, TFVC, and Azure Pipelines are outside this integration's scope.
Note: Azure DevOps is gated behind the
feature_azure_devopsfeature flag, which is off by default. Until an admin enables it for your organization, the Azure DevOps tab, import option, and project settings do not appear at all. A missing tab means the flag is off, not that a connection failed.
Connecting
The connection is shared by the whole organization. It authenticates with a personal access token (PAT) or, on Azure DevOps Services, with a Microsoft Entra ID service principal. Microsoft recommends service principals for unattended automation, and global PATs retire on 1 December 2026 (organization-scoped PATs remain). Azure DevOps Server uses a PAT.
- In Azure DevOps, create a personal access token with the Work Items (Read & Write) and Project and Team (Read) scopes
- In VibeFlow, open Integrations → Azure DevOps → Setup
- Enter your Organisation URL, for example
https://dev.azure.com/your-organisation. The URL must usehttps://and must not contain credentials, a query string, or a fragment. - Paste the Personal access token
- Click Test connection, then Connect

The token is stored encrypted and is never shown again. Once it is saved, the card shows A token is stored with a Replace action.
Using an Entra service principal (Services only): register an application in Microsoft Entra ID and create a client secret for it. Add the service principal to the Azure DevOps organization (Organization settings → Users) with Basic access and the project permissions a user would need. In VibeFlow choose Entra service principal on the setup card, enter the Directory (tenant) ID, the Application (client) ID and the Client secret, then Test connection and Connect. The secret is stored encrypted and never shown again; changing the tenant or application requires re-entering it. Managed Cloud Runners still need a personal access token, because the secret never leaves the server.
Test connection reports exactly what went wrong:
| Result | What to do |
|---|---|
| Connection verified | Nothing — the URL and token work |
| Invalid organisation URL | Use an https:// address with no credentials in it |
| The personal access token was not accepted | Check the token has not expired or been revoked |
| The token lacks the required permissions | Grant the token read and write access to work items |
| Organisation not found | Check the organization name in the URL |
| Could not reach Azure DevOps | Check network access and try again |

Replacing an expired token: If the stored token stops working, the card shows a warning that the token is no longer working. Click Replace, paste a new token, and click Save changes. Existing links are not affected.
Disconnecting: Disconnect deletes the stored token and stops syncing. Imported items and their links to Azure DevOps are kept. Reconnecting resumes syncing for those items. If Azure Repos or managed Cloud Runners use this connection, follow the credential cleanup and manual recovery steps as well.
Azure Repos scope upgrade
Keep Work Items (Read & Write) for Boards and Project and Team (Read), and add Code (Read & Write) for Azure Repos. Code (Read & Write) also covers pull-request comments, statuses and service-hook subscriptions; broader scopes such as Project and Team (Read & Write) or Work Items (Full) are not needed. Use the existing Replace and Save changes flow; no second connection is needed. Test repository access checks that the saved connection can see your repositories.
Link repositories under Project Settings → Integrations → Source Control → Azure Repos. Multiple Azure repositories can be linked to a project, while Boards project binding remains independent. See the Azure Repos guide for defaults, MCP examples, and operating procedures.
Project Binding
Each VibeFlow project can be bound to one Azure DevOps project. Binding is required for imports, pushes, status mapping, comments, and attachments.
- Open the project, then go to Settings → Integrations → Azure DevOps
- Choose a project in Azure DevOps project
- Click Bind project
A project that already has linked work items cannot be rebound to a different Azure DevOps project, because that would strand the existing links. Unlink those items first, then rebind.
Once the project is bound, Sync behavior controls what moves between the two projects:
| Setting | Effect |
|---|---|
| Push changes to Azure DevOps automatically | New VibeFlow items are pushed to Azure DevOps, and edits update the linked work item |
| Push status changes | VibeFlow status changes move the linked work item to the mapped state |
| Sync comments | Comments flow in both directions |
| Import attachments | Files attached to linked work items in Azure DevOps are imported as VibeFlow assets |
| Push attachments | VibeFlow attachments are uploaded to the linked work item |

State Mapping
Azure DevOps states come from each project's process template, such as Agile, Scrum, Basic, CMMI, or an inherited process. Different work item types can have different states. VibeFlow reads the real states for every work item type, so you map against the states your project actually defines.
- In the State mapping section, review each work item type
- For each VibeFlow status, choose the Azure DevOps state it maps to, or leave it Not mapped
- Click Save Type mapping for each type

When VibeFlow suggests a mapping, it shows Suggested mapping — nothing is saved until you choose Save. Suggestions are never applied automatically.
A status left Not mapped does not push a state change; VibeFlow never guesses a state. If states are renamed or removed in Azure DevOps, click Re-check against Azure DevOps to find mappings that point at states that no longer exist.
Azure DevOps Work Item Import
Import work items from Import → Azure DevOps in the project toolbar. The option is disabled until the organization is connected, and the VibeFlow project must be bound to an Azure DevOps project (see Project Binding); the work items are imported against that bound project.
The import wizard has four steps:
- Project — Choose the Azure DevOps project
- Board — Choose the team and board
- Items — Select work items, page by page, or use Select all on this page. Items that are already imported are labeled Already imported — will update.
- Confirm — Review the count, then import

Imported work items become VibeFlow issues in in_review, so a person triages them before agents can pick them up. The title, description, priority, and assignee are carried over. The description comes from Repro Steps when that field has content (Bug work items in the Agile and CMMI processes keep their description there), and from Description otherwise.
Imports never create duplicates. Importing an already-linked work item refreshes its title, description, and priority in place. It does not change the status of the VibeFlow item, and it fills the assignee only if the item has none. A single import run is limited to 500 work items. If some items fail, the confirmation step lists each failed item and the reason.
VibeFlow to Azure DevOps Push
When the project is bound, todo and issue detail pages show Push to Azure DevOps for items that are not yet linked. Features are pushed as Epic work items. Todos and issues use the project's default work item type; if none is set, todos become Task and issues become Issue.
Pushes are queued and delivered by a background worker, so a push made during an Azure DevOps outage is retried instead of lost. Updates send only the fields VibeFlow changed. If someone edits the work item in Azure DevOps at the same moment (a stale revision), VibeFlow re-reads the latest revision and reapplies its changes on top, so the other edit is not overwritten.
Each linked item shows its sync state:
| State | Meaning |
|---|---|
| Synced | The work item matches VibeFlow |
| Pending | A change is queued for delivery |
| Retrying | Delivery failed temporarily and will be retried automatically — no action needed |
| Failed | Delivery stopped. The badge shows the error, and Retry is offered on the item. |
Status Sync
Status sync runs in both directions:
- VibeFlow → Azure DevOps — When Push status changes is on, a VibeFlow status change moves the linked work item to the mapped state.
- Azure DevOps → VibeFlow — When a work item's state changes in Azure DevOps, VibeFlow moves the linked item to the status mapped to that state.
Inbound changes are applied only when they are safe:
- The state must map to exactly one VibeFlow status for that work item type.
- An inbound change never moves an item to
ready_to_implement,planning,implementing, ordone. Releasing work to agents stays a decision made in VibeFlow. - Items that are done, in planning or implementing, or claimed by an agent session are not changed.
When a change is not applied, the remote state and the reason are recorded on the link instead.
Comments, Attachments, and Relations
- Comments — With Sync comments on, VibeFlow comments are posted to the linked work item. Azure DevOps comments are pulled into VibeFlow about every 10 minutes and appear under Comments from Azure DevOps on the item.
- Attachments — With Import attachments on, files attached in Azure DevOps are imported as VibeFlow assets on a background schedule. With Push attachments on, VibeFlow attachments are uploaded to the work item.
- Relations — Links between Azure DevOps work items, such as parent, child, and related, appear under Linked artifacts. A related work item that is also imported links to its VibeFlow item. One that is not imported is kept as an external reference to Azure DevOps.
Azure DevOps on Work Items
Linked todos, issues, and features show an Azure DevOps panel on the detail view:
- Work item — The work item number and type, linking to the item in Azure DevOps
- State, Project, and Last synced
- Sync badge — Synced, Pending, Retrying, or Failed, with the error on failure
- Unlink — Stops syncing this item. The work item stays in Azure DevOps and the VibeFlow item stays here.

In feature, todo, and issue lists, the Ref column shows the linked work item type and number, the same way Jira keys appear.

Troubleshooting
| Symptom | Cause and fix |
|---|---|
| No Azure DevOps tab or import option | The feature_azure_devops flag is off for your organization. Ask an admin to enable it. |
| Azure DevOps import option is disabled | The organization is not connected. Connect it under Integrations → Azure DevOps. |
| Import fails with this project is not bound to an Azure DevOps project | Bind the project under Settings → Integrations → Azure DevOps, then import again. |
| Warning that the stored token is no longer working | The token expired or was revoked. Use Replace to save a new one. |
| Import or binding shows a connection error instead of work items | The connection failed; the board is not empty. Run Test connection and follow the result. |
| Could not bind the project | The project already has linked work items in a different Azure DevOps project. Unlink them first. |
| Status changes do not reach Azure DevOps | Push status changes is off, or that status is Not mapped for the work item's type. |
| Some mappings point at states that no longer exist | A state was renamed or removed in the process template. Run Re-check against Azure DevOps and update the mappings. |
| An item shows Failed | Read the error on the badge, fix the cause, then click Retry on the item. |
| Failed with the work item changed in Azure DevOps and could not be re-read | The work item was edited in Azure DevOps during an update (a stale revision), and VibeFlow could not re-read it to reapply its changes. Check the connection with Test connection, then click Retry. |
Every call to Azure DevOps is recorded on the Activity & errors tab of the Azure DevOps integration, including errors and request context.

Spira Integration
Connect SpiraPlan, SpiraTeam, or SpiraTest to import Spira artifacts into VibeFlow and push VibeFlow work, status, comments, attachments, and documents back to Spira. Agents can also tag their commits with Spira artifact tokens so Spira links commits to artifacts.
Note: Spira is gated behind the
feature_spirafeature flag, which is off by default. Until an admin enables it for your organization, the Spira tab, import option, and project settings do not appear at all.
Connecting
The connection is shared by the whole organization and authenticates with a Spira username and API key.
- Open Integrations → Spira → Setup
- Under Deployment, choose Cloud (spiraservice.net) or Self-hosted
- Cloud — enter your Tenant, for example
acmeforhttps://acme.spiraservice.net. Pasting the full cloud URL fills in the tenant. - Self-hosted — enter the Base URL, for example
https://spira.example.com/spira. It must start withhttps://.
- Cloud — enter your Tenant, for example
- Choose the API version: v7 for SpiraPlan, SpiraTeam, or SpiraTest 6.0 and later (including 9.x), or v6 (legacy)
- Enter your Spira Username and API key. The API key is your Spira RSS token, including the braces, such as
{XXXXXXXX-XXXX-...}. - Click Test Connection, then Connect

The API key is stored encrypted and never shown again; the card shows •••• set with a Replace action.
| Result | What to do |
|---|---|
| Connection verified | Nothing — the connection works |
| Invalid base URL | Use an address that starts with https:// |
| Authentication failed | Check the username and API key, including the braces |
| Could not reach the Spira instance | Cloud: check the tenant name. Self-hosted: check that your Spira server is reachable from Axiom Studio. Loopback and cloud metadata addresses are always blocked. |
| Spira returned an error | Read the message shown and try again |
Credential health: if the stored key starts failing or is revoked, the card shows that sync is paused. Replace the API key and save to resume.
Disable and disconnect: Disable turns syncing off and keeps the stored credentials. Disconnect deletes the stored username and API key. In both cases artifact links are kept, and sync resumes when you reconnect.
Project Binding
Each VibeFlow project binds to one Spira product. Different projects in the same organization can bind to different products.
- Open the project, then go to Settings → Integrations → Spira
- Choose a Product
- Click Bind product
Binding enables push and status sync for the project and loads default status mappings. Rebind product switches products, and Remove binding unbinds the project.
Sync behavior controls what moves to Spira:
| Setting | Effect |
|---|---|
| Auto-push new items to Spira | New features, todos, and issues are created in Spira, and edits to the title, description, and priority are pushed. Project documents are pushed to Spira as Markdown files, and later edits become new file versions. |
| Auto-transition Spira status on VibeFlow status change | VibeFlow status changes move the linked artifact to the mapped Spira status |
| Post a completion comment on done | A comment is added to the Spira artifact when the VibeFlow item is done |
| Import attachments | Saved with the project's settings. The current import does not download Spira attachments. |
| Provide commit tokens ([IN:100]) to agents | Agents receive the artifact's token to append to their commit messages |
| Push attachments to Spira | VibeFlow attachments are uploaded to the linked artifact |

Status Mapping
The Status mapping table maps each VibeFlow status to a Spira workflow status for each artifact type: Requirement, Incident, and Task. The table is filled with Spira's default status IDs when you bind a product. If your Spira product uses customized workflows, update the Spira status ID and Spira status name values, then click Save status mapping.
A VibeFlow status with no mapping for an artifact type does not change the Spira status.

Spira Artifact Import
Import artifacts from Import → Spira. The VibeFlow project must be bound to a Spira product.
- Choose the VibeFlow Project
- Choose what to import:
- Incidents → Issues
- Tasks → Todos
- Requirements → Features
- Select artifacts, 25 per page. Search applies to the current page, and Select page selects every artifact on it.
- Click Import N selected

Imported items land in in_review, so a person triages them before agents can pick them up. The name, description, and priority are carried over. When you import a Requirement, its parent Requirements are imported too, as parent features.
Artifacts that are already imported are left out of the list. Re-importing a linked artifact refreshes its title and description and never changes its VibeFlow status. If some artifacts fail, the result lists each failure and the reason; the rest are still imported.
Changes made in Spira after import are not pulled into VibeFlow automatically.
VibeFlow to Spira Push
When the project is bound:
- Auto-push creates new features as Requirements, todos as Tasks, and issues as Incidents. A todo's feature is created in Spira first, so Tasks appear under their Requirement.
- Export to Spira on a feature's detail view exports the feature as a Requirement with its todos as child Tasks. It works even when auto-push is off.
- Status changes, completion comments, and attachments follow the Sync behavior settings.
- Comments on linked todos and issues are forwarded to the Spira artifact.
Pushes are queued and retried, so a push made while Spira is unavailable is delivered later instead of lost.
Commit Tokens and Source Control
With Provide commit tokens ([IN:100]) to agents on, agents append the linked artifact's token to their commit messages, for example Fix login redirect [IN:100]. Tokens use the artifact prefix: RQ for Requirements, IN for Incidents, and TK for Tasks.
Spira records these associations only when its Source Code provider is pointed at your repository. Configure that in Spira; without it, Spira ignores the tokens.
Spira on Work Items
Linked features, todos, and issues show their Spira artifact:
- Ref column — Feature, todo, and issue lists show the artifact token, linking to the artifact in Spira
- Spira panel — The detail view shows the Artifact, Spira Status, Commit token, and Sync Status
- Unlink — Stops syncing. The artifact stays in Spira and the item stays in VibeFlow.
Spira Troubleshooting
| Symptom | Cause and fix |
|---|---|
| No Spira tab or import option | The feature_spira flag is off for your organization. Ask an admin to enable it. |
| Import shows Select a VibeFlow project bound to a Spira product. | Bind the project to a product under Settings → Integrations → Spira. |
| Credential health shows sync is paused | The API key failed or was revoked. Use Replace, then save. |
| Export to Spira reports that no Spira product is configured | Bind the project to a product first. |
| Status changes do not reach Spira | Auto-transition is off, or the status has no mapping for that artifact type. |
| Commits do not appear on Spira artifacts | Commit tokens are off for the project, or Spira's Source Code provider is not pointed at the repository. |
Every call to Spira is recorded on the Activity & errors tab of the Spira integration.

Figma Integration
Connect your Figma account to pull design context directly from Figma files:
- Go to Settings → enter your Figma Personal Access Token
- Browse Figma files from within VibeFlow
- Pull design context and screenshots for agent reference
Supported AI Agent Platforms
VibeFlow connects with multiple AI coding platforms via MCP (Model Context Protocol):
| Platform | Setup Location |
|---|---|
| Claude Code CLI | Project → Setup tab |
| Claude Desktop | Project → Setup tab |
| Cursor | Project → Setup tab |
| Gemini | Project → Setup tab |
| OpenAI Codex | Project → Setup tab |
Each platform has specific configuration instructions in the Setup tab.
Integration Logs

Every integration vendor has a dedicated Logs tab showing:
- Success/failure status of each API call
- Error codes and messages
- Request context and timestamps
- OAuth token refresh events
Logs help diagnose sync issues without contacting support.