Axiom StudioAXIOMSTUDIO
All docs

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

  1. Navigate to the Integrations tab in the top-level sidebar
  2. Click Connect Atlassian Account
  3. You'll be redirected to Atlassian to authorize the axiomstudio app
  4. Grant the requested permissions (Confluence + Jira scopes)
  5. 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 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:

  1. Import Jira tickets into VibeFlow
  2. AI agents implement the work
  3. Status, PR links, and commit details flow back to Jira automatically

Jira Integration Setup

Import Wizard

The Jira Import Wizard is a 3-step process:

Import from Jira

  1. 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)
  2. 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
  3. 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 EventJira Action
Agent starts implementingTransition to "In Progress"
Item marked doneTransition to "Done"/"Closed"/"Resolved"
Execution log publishedComment posted to Jira ticket
Description updatedJira 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_sync metadata 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

  1. Navigate to Integrations → GitHub tab
  2. Click Connect GitHub
  3. Authorize via GitHub OAuth
  4. Select which repositories to link to VibeFlow projects

Pull Requests

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.

Create Pull Request modal with the Source Branch dropdown open, listing a local agent branch as a disabled option suffixed "(not pushed to origin)" because it has not been pushed yet

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 (or VibeFlow 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

  1. Navigate to Integrations → Bitbucket tab
  2. Click Connect Bitbucket
  3. 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.

SettingValue
bitbucket_forge_app_idThe 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_urlThe 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:

  1. Choose Bitbucket as the source control provider
  2. Select a Workspace from the dropdown
  3. Select a Repository in that workspace
  4. 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.

Project Settings → Integrations → Source Control with Bitbucket selected as the provider, showing the connected Bitbucket account alongside the Workspace and Repository dropdowns and the Link Repository button used to link a repository to the project

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

  1. Navigate to Integrations → GitLab tab
  2. Click Connect GitLab — GitLab opens in a new browser tab
  3. Authorize VibeFlow in GitLab
  4. 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.

GitLab Setup sub-tab showing the connected GitLab account and email, the repository linking note that only GitLab.com is supported, and the Disconnect button

Linking a Repository

Repositories are linked per project, from Project Settings → Integrations → Source Control:

  1. Choose GitLab as the source control provider
  2. Search the Repository picker — it lists the GitLab projects you are a member of, across all your groups and namespaces, shown as namespace/project
  3. 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.

Project Settings → Integrations → Source Control with GitLab selected and the Repository picker open, listing a matching GitLab project and the option to link the typed path directly

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.

Pull Requests tab listing three draft GitLab merge requests opened from completed features, each with its repository, source → target branches, and originating feature

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)

A linked GitLab repository in Source Control with its Unlink button, the Link another picker, and the three merge request settings checked

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.

GitLab Logs sub-tab listing create_mr entries with their source branch, draft state and merge request URL, and oauth_connect entries for connected team members

Slack Notifications

Send real-time project notifications to Slack channels when important events happen in your VibeFlow projects.

Setting Up Slack Webhooks

  1. Navigate to the Integrations tab in the top-level sidebar
  2. Click the Slack panel
  3. Add a new webhook:
    • Name — Descriptive label (e.g., "engineering-alerts")
    • Webhook URL — Your Slack Incoming Webhook URL
  4. 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:

  1. Open a project → Settings tab → Notifications
  2. Check the webhooks that should receive notifications for this project
  3. Toggle individual event types on or off

Notification Events

Events are grouped by category:

CategoryEvents
ProjectsProject created, archived, deleted
FeaturesFeature created, archived, deleted
TodosTodo created, completed, rejected
IssuesIssue 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_clickup flag for your organization.

Connecting

  1. Navigate to Settings or Integrations and open the ClickUp panel
  2. Click Connect ClickUp
  3. Authorize the ClickUp OAuth app
  4. Select the workspace VibeFlow should use for browsing, imports, and sync
  5. 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:

  1. 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
  2. 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
  3. 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
  4. 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: imported and sync_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 EventClickUp Action
Imported ClickUp taskCreate todo or issue with mapped VibeFlow status
Todo or issue status changesUpdate linked ClickUp task status using the export mapping
Title, description, or priority changesUpdate linked ClickUp task fields
Tags changeUpdate linked ClickUp task tags
Execution/activity comment publishedPost 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
  • done qualifiers 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 imported from ClickUp or pushed from VibeFlow
  • Sync Status — linked, syncing, completed, failed, or dead_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_devops feature 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.

  1. In Azure DevOps, create a personal access token with the Work Items (Read & Write) and Project and Team (Read) scopes
  2. In VibeFlow, open Integrations → Azure DevOps → Setup
  3. Enter your Organisation URL, for example https://dev.azure.com/your-organisation. The URL must use https:// and must not contain credentials, a query string, or a fragment.
  4. Paste the Personal access token
  5. Click Test connection, then Connect

Azure DevOps setup card with the organisation URL, a stored personal access token, and a Connection verified result

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:

ResultWhat to do
Connection verifiedNothing — the URL and token work
Invalid organisation URLUse an https:// address with no credentials in it
The personal access token was not acceptedCheck the token has not expired or been revoked
The token lacks the required permissionsGrant the token read and write access to work items
Organisation not foundCheck the organization name in the URL
Could not reach Azure DevOpsCheck network access and try again

Organisation URL rejected with the message that it must start with https://

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.

  1. Open the project, then go to Settings → Integrations → Azure DevOps
  2. Choose a project in Azure DevOps project
  3. 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:

SettingEffect
Push changes to Azure DevOps automaticallyNew VibeFlow items are pushed to Azure DevOps, and edits update the linked work item
Push status changesVibeFlow status changes move the linked work item to the mapped state
Sync commentsComments flow in both directions
Import attachmentsFiles attached to linked work items in Azure DevOps are imported as VibeFlow assets
Push attachmentsVibeFlow attachments are uploaded to the linked work item

Project settings showing the bound Azure DevOps project and the Sync behavior toggles

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.

  1. In the State mapping section, review each work item type
  2. For each VibeFlow status, choose the Azure DevOps state it maps to, or leave it Not mapped
  3. Click Save Type mapping for each type

State mapping for the Issue and Epic work item types, mapping VibeFlow statuses to To Do, Doing, and Done

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:

  1. Project — Choose the Azure DevOps project
  2. Board — Choose the team and board
  3. 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.
  4. Confirm — Review the count, then import

Import wizard Items step with two work items selected, each labeled Already imported — will update

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:

StateMeaning
SyncedThe work item matches VibeFlow
PendingA change is queued for delivery
RetryingDelivery failed temporarily and will be retried automatically — no action needed
FailedDelivery 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, or done. 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.

Issue detail with the Azure DevOps panel showing the synced work item, its state, project, and last sync time

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

Issues list with an Azure DevOps work item reference in the Ref column of each row

Troubleshooting

SymptomCause and fix
No Azure DevOps tab or import optionThe feature_azure_devops flag is off for your organization. Ask an admin to enable it.
Azure DevOps import option is disabledThe organization is not connected. Connect it under Integrations → Azure DevOps.
Import fails with this project is not bound to an Azure DevOps projectBind the project under Settings → Integrations → Azure DevOps, then import again.
Warning that the stored token is no longer workingThe token expired or was revoked. Use Replace to save a new one.
Import or binding shows a connection error instead of work itemsThe connection failed; the board is not empty. Run Test connection and follow the result.
Could not bind the projectThe project already has linked work items in a different Azure DevOps project. Unlink them first.
Status changes do not reach Azure DevOpsPush status changes is off, or that status is Not mapped for the work item's type.
Some mappings point at states that no longer existA state was renamed or removed in the process template. Run Re-check against Azure DevOps and update the mappings.
An item shows FailedRead 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-readThe 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.

Azure DevOps Activity & errors tab listing test_connection, create_work_item, and update_work_item operations

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_spira feature 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.

  1. Open Integrations → Spira → Setup
  2. Under Deployment, choose Cloud (spiraservice.net) or Self-hosted
    • Cloud — enter your Tenant, for example acme for https://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 with https://.
  3. Choose the API version: v7 for SpiraPlan, SpiraTeam, or SpiraTest 6.0 and later (including 9.x), or v6 (legacy)
  4. Enter your Spira Username and API key. The API key is your Spira RSS token, including the braces, such as {XXXXXXXX-XXXX-...}.
  5. Click Test Connection, then Connect

Spira setup card for a cloud tenant with the stored API key, credential health, and a Connection verified result

The API key is stored encrypted and never shown again; the card shows •••• set with a Replace action.

ResultWhat to do
Connection verifiedNothing — the connection works
Invalid base URLUse an address that starts with https://
Authentication failedCheck the username and API key, including the braces
Could not reach the Spira instanceCloud: 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 errorRead 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.

  1. Open the project, then go to Settings → Integrations → Spira
  2. Choose a Product
  3. 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:

SettingEffect
Auto-push new items to SpiraNew 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 changeVibeFlow status changes move the linked artifact to the mapped Spira status
Post a completion comment on doneA comment is added to the Spira artifact when the VibeFlow item is done
Import attachmentsSaved with the project's settings. The current import does not download Spira attachments.
Provide commit tokens ([IN:100]) to agentsAgents receive the artifact's token to append to their commit messages
Push attachments to SpiraVibeFlow attachments are uploaded to the linked artifact

Project settings showing a bound Spira product and the Sync behavior toggles

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 status mapping table with Spira status IDs and names for Requirement, Incident, and Task

Spira Artifact Import

Import artifacts from Import → Spira. The VibeFlow project must be bound to a Spira product.

  1. Choose the VibeFlow Project
  2. Choose what to import:
    • Incidents → Issues
    • Tasks → Todos
    • Requirements → Features
  3. Select artifacts, 25 per page. Search applies to the current page, and Select page selects every artifact on it.
  4. Click Import N selected

Import from Spira wizard listing incidents with two 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

SymptomCause and fix
No Spira tab or import optionThe 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 pausedThe API key failed or was revoked. Use Replace, then save.
Export to Spira reports that no Spira product is configuredBind the project to a product first.
Status changes do not reach SpiraAuto-transition is off, or the status has no mapping for that artifact type.
Commits do not appear on Spira artifactsCommit 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.

Spira Activity & errors tab listing document and attachment operations with their status

Figma Integration

Connect your Figma account to pull design context directly from Figma files:

  1. Go to Settings → enter your Figma Personal Access Token
  2. Browse Figma files from within VibeFlow
  3. Pull design context and screenshots for agent reference

Supported AI Agent Platforms

VibeFlow connects with multiple AI coding platforms via MCP (Model Context Protocol):

PlatformSetup Location
Claude Code CLIProject → Setup tab
Claude DesktopProject → Setup tab
CursorProject → Setup tab
GeminiProject → Setup tab
OpenAI CodexProject → Setup tab

Each platform has specific configuration instructions in the Setup tab.

Integration Logs

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.