How do I set up the Azure DevOps integration for the first time?
Follow the Integrating Craft.io with Azure DevOps setup guide. Before you start, make sure you have:
Your ADO organization URL
A Personal Access Token (PAT) with the correct scopes
Admin access to both Craft.io and Azure DevOps
I am getting a 404 error when setting up the ADO webhook - what should I check?
A 404 on the webhook URL usually means the URL may have been copied incorrectly. To fix it:
Go to Workspace Settings > Integrations > Azure DevOps and copy the webhook URL fresh
Re-enter it in ADO under Project Settings > Service Hooks
Check for trailing spaces or line breaks in the URL
Why aren't status changes syncing between Craft.io and Azure DevOps?
Check these in order:
Go to Workspace Settings > Integrations > Azure DevOps > Status Mapping and confirm every Craft.io status has a corresponding ADO state mapped
Verify the webhook is still active in ADO and has not been paused or deleted
See How to automate status updates from your dev tool for a full walkthrough.
Why aren't dates syncing between Craft.io and Azure DevOps?
Date sync requires explicit field mapping:
Go to Workspace Settings > Integrations > Azure DevOps > Field Mapping and confirm Start Date and Target Date are mapped to the correct ADO fields
Some ADO date fields are read-only depending on your process template, which will prevent two-way sync
How do I update my ADO Personal Access Token?
Go to Workspace Settings > Integrations > Azure DevOps and update the PAT field. When generating a new token, make sure it includes:
Work Items - Read & Write
Project and Team - Read
ADO PATs have a maximum lifespan of one year. If your token has expired, syncing will stop immediately.
My ADO Personal Access Token has expired - how do I renew it?
When a token expires, syncing stops immediately with no automatic notification. To renew:
Go to your Azure DevOps profile and select Personal Access Tokens
Locate the existing token and click Renew, or create a new one with the same scopes (Work Items: Read & Write, Project and Team: Read)
In Craft.io, go to Workspace Settings > Integrations > Azure DevOps and paste the new token
Save and verify that items return to an active sync state
💡 Set a calendar reminder before your token expiry date to avoid unplanned sync interruptions.
How do I map item types between Craft.io and Azure DevOps?
Go to Workspace Settings > Integrations > Azure DevOps > Item Type Mapping. You can map:
Craft.io Epics → any ADO work item type
Craft.io Features → any ADO work item type
Craft.io Stories → any ADO work item type
See Mapping Work Item Types Between Craft.io and Azure DevOps for a full walkthrough.
My user stories are stuck syncing with ADO - how do I fix this?
Items stuck in a syncing state are usually caused by a field-level conflict. To diagnose:
Open the item in Craft.io and check Sync Status in the item panel for an error message
Look for a required ADO field that is not populated in Craft.io, or a value that does not match the allowed values in ADO
Resolve the conflicting field and re-trigger the sync
If no error message is shown, contact support with the item ID.
What happens when Azure DevOps has mandatory fields not mapped in Craft.io?
If ADO requires a field that is not mapped or populated in Craft.io, the sync will fail for every item of that type. The most common causes:
Priority - required by the integration but missing from some custom ADO work item types. Add it to the work item type in ADO and retry.
Description and Acceptance Criteria - if set as required in ADO but empty in Craft.io, sync will fail. Populate the fields or remove the required constraint in ADO.
Custom required fields (such as Story Owner, Category, or FY Quarter) - map these in Workspace Settings > Integrations > Azure DevOps > Field Mapping and ensure valid values are populated before syncing.
If you find a missing field on one work item type, check all other types and connected projects - the same field is often missing in multiple places.
How do I find all items stuck in a sync error state?
To see all affected items at once:
Open Table view with hierarchy set to All
Filter by Sync Status = Sync Error
Once the root cause is resolved, select all affected items and use Bulk Push to ADO to re-trigger the sync in one action
Is the ADO integration available on the Starter plan?
Two-way sync with Azure DevOps requires a Pro or Enterprise plan. The Starter plan includes development tool integration but with limitations on sync depth and configuration options. Contact your Customer Success Manager for a full plan comparison.
Can I edit the ADO status field directly in Craft.io?
No. Once an item is synced to Azure DevOps, ADO becomes the source of truth for status. Status updates flow from ADO into Craft.io - not the other way around.
To update the status of a synced item, change it in Azure DevOps and it will reflect in Craft.io automatically.