ado-asana-sync

This project aims to synchronize work items and pull requests between Azure DevOps (ADO) and Asana. It's currently in development and not ready for use. Breaking changes will occur as needed.

How to use

• Get the latest container image from the Github Container Registry.
• Configure the environment variables with the relevant values:
  • ADO_PAT - Your Personal Access Token for ADO to accesst the work items.
  • ADO_URL - The full URL of your Azure DevOps instance.
  • ASANA_TOKEN - Your Personal Access Token for Asana to access the work items.
  • ASANA_WORKSPACE_NAME - Name of the Asana workspace to sync with.
  • CLOSED_STATES - Comma separated list of states that will be considered closed.
  • THREAD_COUNT - Number of projects to sync in parallel. Must be a positive integer.
  • SLEEP_TIME - Duration in seconds to sleep between sync runs. Must be a positive integer.
  • SYNCED_TAG_NAME - Name of the tag in Asana to append to all synced items. Must be a valid Asana tag name.
• Run the container with the configured environment variables.
• The application will start syncing work items and pull requests between ADO and Asana based on the configured settings.

Features

Work Item Synchronization

• Synchronizes Azure DevOps work items (User Stories, Bugs, Tasks, etc.) to Asana tasks
• Maintains bidirectional sync for updates, assignments, and status changes
• Automatic user matching between ADO and Asana based on email addresses
• Configurable closed states mapping

Pull Request Synchronization

• Synchronizes active Pull Requests from Azure DevOps to Asana
• Creates separate reviewer tasks for each assigned reviewer
• Task titles follow the format: "Pull Request 5: Update readme (Reviewer Name)"
• Automatic status management:
  • Approved reviews (approve/approve with suggestions) → Close Asana task
  • Other review states (waiting for author, reject, no vote) → Keep task open
  • PR completion/abandonment → Close all reviewer tasks
  • Reviewer removal → Close reviewer's task
• Handles reviewer additions, removals, and approval resets
• Syncs PR title changes to Asana task titles

Pull Request Selection Logic

The system follows this logic to determine which PRs to sync:

1. Repository Discovery: For each configured ADO project, discover all Git repositories
2. Active PR Filtering: Query only PRs with status="active" (excludes completed/abandoned PRs)
3. Reviewer Requirements: Only sync PRs that have at least one assigned reviewer
4. User Matching: Only create tasks for reviewers who have matching Asana accounts (by email)
5. Deduplication: Prevent duplicate reviewer processing by unique email identifier
6. Cleanup Processing: Additionally process previously synced PRs that may now be closed/completed

Exclusion Criteria:

• PRs without reviewers are skipped (logs: "No reviewers found for PR X")
• Reviewers not found in Asana are skipped (logs: "PR X: reviewer Y not found in Asana")
• Repositories/projects without Git API access are skipped gracefully

Changelog

See CHANGELOG.md for a detailed history of changes and new features.

Development

Commit message style

This repo uses Conventional Commits to ensure the build numbering is generated correctly

Manual testing

To test the application manually, you can use the following steps:

Work Item Testing

1. Create new ADO work item and ensure it is synced to Asana.
2. Rename Asana task and ensure it is reverted back to the ADO name.
3. Rename ADO task and ensure it is synced to Asana.
4. Remove Synced tag from item in Asana and ensure it is replaced.
5. Delete synced tag from Asana workspace and from appdata.json file and ensure it is re-created and assigned to all synced tasks.
6. Mark Asana task as complete and ensure it is re-opened.
7. Mark ADO task as complete and ensure it is marked as complete in Asana.
8. Re-open ADO task and ensure it is re-opened in Asana.

Pull Request Testing

1. Create new Pull Request in ADO with reviewers and ensure reviewer tasks are created in Asana.
2. Change the PR title in ADO and ensure the title updates in Asana tasks on next sync.
3. Add a reviewer to the PR and ensure a new task is created for them.
4. Remove a reviewer from the PR and ensure their task is closed.
5. Remove all reviewers from the PR and ensure all tasks are closed.
6. Approve the PR as a reviewer and ensure the reviewer's task is closed.
7. Approve with suggestions and ensure the reviewer's task is closed.
8. Reject or request changes and ensure the reviewer's task remains open.
9. Reset approval and ensure the reviewer's task is reopened.
10. Complete/abandon the PR and ensure all reviewer tasks are closed.

Reference

ADO

• azure-devops PyPi
• azure-devops GitHub
• azure-devops API reference
• azure-devops samples

Asana

• Asana PyPi
• Asana GitHub
• Asana API Reference