Azure DevOps to Monday.com Sync Tool

A comprehensive Python application to synchronize work items from Azure DevOps (ADO) to Monday.com boards with a full-featured GUI.

Features

Core Functionality

✅ Work Item Sync: Automatically sync ADO work items to Monday.com boards
✅ Smart Duplicate Prevention: Checks existing items by ADO ID to prevent duplicates
✅ Skip Unchanged Items: Fast skip when ADO Changed Date matches Monday Changed Date
✅ Attachment Handling: Download attachments from ADO and upload to Monday.com
✅ Repro Steps Sync: Post repro steps as Monday.com updates
✅ Custom Field Mapping: Map any ADO field to any Monday.com column dynamically
✅ Configurable Filters: Filter work items by team project and states
✅ Assigned To Filter: Sync only items assigned to specific people (comma-separated)
✅ File Size Limits: Configure maximum attachment size (default 50MB)
✅ Multi-Config Jobs: Run multiple sync jobs in one click (batch processing)
✅ Bugs Report Generator: Create cross-board bug status reports with deltas

GUI Features

📊 Tabbed Interface:
Connection Settings: Configure ADO and Monday.com credentials
Field Mapping: Dynamically map ADO fields to Monday columns with visual interface
Sync: Execute sync with real-time progress and logging
🔐 Configuration Management: Save, Save As, load, and select multiple JSON configs
📁 Config Selector + Job List: Pick a default config or run multiple configs as jobs
🧪 Connection Testing: Verify ADO and Monday.com connections before sync
📈 Real-time Logging: See detailed progress with color-coded status messages
⚡ Background Processing: UI remains responsive during sync operations
📊 Bugs Report: Generate Markdown reports for all configured boards

Prerequisites

Python 3.12+
Azure DevOps account with Personal Access Token (PAT)
Monday.com account with API key
Virtual environment (recommended)

Installation

Clone or download this repository
Create a virtual environment:
```
python -m venv .venv
```
Activate the virtual environment:
```
.\.venv\Scripts\Activate.ps1
```
Install dependencies:
```
pip install -r requirements.txt
```

Configuration

Using the GUI (Recommended)

Launch the GUI:

.\.venv\Scripts\python.exe ado_to_monday_gui.py

Connection Settings Tab:
Enter your Azure DevOps organization URL (e.g., https://dev.azure.com/yourorg)
Enter your ADO Project ID or Name
Enter your ADO Team Project name (e.g., "Gaya - Bespoke Airports")
Enter your ADO Personal Access Token
Enter your Monday.com API key
Enter your Monday.com Board ID
Use Select Config to load a saved configuration
Use Save Config or Save As... to store a new config file
(Optional) Select one or more configs in Jobs to Run for batch sync
Click Test Connections to verify
Click Save Config to persist settings
Field Mapping Tab:
Click Load Fields & Columns to fetch available ADO fields and Monday columns
Click ➕ Add Field Mapping to create a new mapping
Select an ADO field from the dropdown (e.g., System.Title, Custom.StackPriorityValue)
Select a Monday column from the dropdown (e.g., Name, Stack Priority)
Repeat to add more mappings
Click ❌ to remove a mapping
Save Config to persist mappings
Sync Tab:
Configure sync options:
- ✅ Sync Attachments
- ✅ Sync Repro Steps as Updates
- ✅ Update Existing Items (prevents duplicates)
- ✅ Skip items with unchanged Changed Date
- Max Attachment Size (MB)
- State Filter (comma-separated, e.g., "Active, New")
- Assigned To Filter (comma-separated names, leave blank for all)
Click ▶ Start Sync to begin
- Click 📊 Generate Bugs Report to create a report for all configs
Monitor progress in the log window

Using the Script Directly

You can also use the backend script without the GUI:

from ado_to_monday import ADOToMonday

syncer = ADOToMonday(
    ado_org_url="https://dev.azure.com/yourorg",
    ado_project="your-project-guid",
    ado_pat="your-pat-token",
    monday_api_key="your-monday-api-key",
    monday_board_id=123456789
)

# Sync with default settings
syncer.sync()

# Sync with custom team project and states
syncer.sync(
    team_project="Gaya - Bespoke Airports",
    states=["Active", "New"],
    sync_attachments=True,
    sync_repro_steps=True
)

Field Mapping

Default Fields (when no custom mappings configured)

ADO Field	Monday Column
System.Id	ADO ID
System.Title	Name
System.Description	Description
System.AssignedTo	Assigned To
System.State	State
Microsoft.VSTS.Common.Priority	Priority
Custom.StackPriorityValue	Stack Priority Value
System.ChangedDate	Changed Date
Microsoft.VSTS.TCM.ReproSteps	(Posted as Update)
System.WorkItemType	Work Item Type
System.CreatedDate	Created Date

Custom Mapping

With the Field Mapping tab, you can: - Map any ADO field to any Monday column - Add multiple field mappings dynamically - Remove unwanted mappings - Save mappings to configuration file - Fields are automatically typed (dates, text, numbers)

Example Custom Mappings: - System.AreaPath → Team Area - System.IterationPath → Sprint - Custom.ReleaseVersion → Release - Microsoft.VSTS.Common.Severity → Severity

How It Works

Sync Process

Fetch Work Items: Query ADO using WIQL with team project and state filters
Optional Assigned To filter is added when provided
Extract Fields: Pull field values based on configured mappings
Check Duplicates: Query Monday board for items with matching ADO ID
Skip Unchanged (optional): If Changed Date matches, skip sync for that item
Create/Update:
If item exists and "Update Existing" enabled → Update column values
If item doesn't exist → Create new item
Sync Attachments (if enabled):
Download attachments from ADO
Check if file already exists on Monday item
Upload only new files (prevents duplicates)
Skip files exceeding size limit
Sync Repro Steps (if enabled):
Check if repro steps update already posted
Post as Monday update if not present

Duplicate Prevention

Items: Queries Monday board by ADO ID column value before creating
Attachments: Compares filenames in Monday file column before uploading
Updates: Checks existing updates for repro steps marker before posting

Troubleshooting

Connection Errors

Verify ADO PAT token has Work Items: Read permission
Verify Monday.com API key has boards:read and boards:write scopes
Check organization URL format: https://dev.azure.com/yourorg (no trailing slash)
Ensure Board ID is a number (not board name)

Field Mapping Issues

Click Load Fields & Columns before adding mappings
Ensure ADO fields exist in your work items
Ensure Monday columns exist on your board
Check Monday column types match ADO field types (date → date, text → text)

Sync Errors

Review log window for specific error messages
Common issues:
Invalid field names → Update mappings
Column type mismatch → Change Monday column type
Large attachments → Increase max file size or skip large files
Network timeouts → Reduce batch size or retry

File Upload Failures

Default max size is 50MB (configurable)
Ensure file isn't corrupted in ADO
Check Monday.com storage limits
Verify file column exists on board

Advanced Usage

Custom WIQL Queries

Edit the query in create_syncer() method to customize work item selection:

custom_query = """
SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = 'Your Project'
AND [System.State] = 'Active'
AND [System.Tags] CONTAINS 'Monday-Sync'
AND [System.CreatedDate] >= '2024-01-01'
"""

Programmatic Field Mapping

syncer._field_mappings = [
    {'ado_field': 'System.Title', 'monday_column': 'Name'},
    {'ado_field': 'Custom.StackPriorityValue', 'monday_column': 'Stack Priority'},
    {'ado_field': 'System.State', 'monday_column': 'Status'},
]

Configuration File Format

Saved as JSON in the project/exe directory (e.g., sync_config.json or sync_config_*.json):

{
  "ado_org_url": "https://dev.azure.com/yourorg",
  "ado_project": "project-guid",
  "ado_team_project": "Team Project Name",
  "ado_pat": "your-pat-token",
  "monday_api_key": "your-api-key",
  "monday_board_id": "123456789",
  "sync_attachments": true,
  "sync_repro_steps": true,
  "update_existing": true,
   "skip_unchanged": true,
  "max_file_size": 50,
  "state_filter": "Active, New",
   "assigned_filter": "",
  "field_mappings": [
    {
      "ado_field": "System.Title",
      "monday_column": "Name"
    },
    {
      "ado_field": "Custom.StackPriorityValue",
      "monday_column": "Stack Priority Value"
    }
  ]
}

Bugs Report Generator

Generate a consolidated Markdown report across all configured boards.

GUI: Click 📊 Generate Bugs Report in the Sync tab
CLI: Run python bugs_report.py

Reports are saved in the reports folder with timestamps and include delta tracking from the previous run.

License

This project is provided as-is for internal use.