Azure DevOps Setup

This guide will help you set up Codity with Azure DevOps to start reviewing pull requests automatically.

Prerequisites

  • An Azure DevOps account with access to the repositories you want to connect
  • Important: You must use an organizational account (work or school account). Personal Microsoft accounts (MSA) are NOT supported
  • Ability to create Personal Access Tokens (PATs) in Azure DevOps
  • Repositories must allow webhook creation

Setup Steps

Step 1: Sign In with Azure DevOps OAuth

  1. Navigate to Codity Settings → Providers → Azure DevOps
  2. Click "Connect Azure DevOps"
  3. You'll be redirected to Azure DevOps to authorize Codity
  4. Important: Sign in with your organizational account (work or school account), not a personal Microsoft account
  5. Grant Codity the requested permissions
  6. You'll be redirected back to Codity

Step 2: Create a Personal Access Token

  1. Go to Azure DevOps → User Settings → Personal Access Tokens (or visit https://dev.azure.com/{your-organization}/_usersSettings/tokens)
  2. Click "New Token"
  3. Configure the token:
    • Name: "Codity Access" (or any descriptive name)
    • Organization: Select your Azure DevOps organization
    • Expiration: Set to 90 days (recommended) or your preferred duration
    • Scopes: Select the following required scopes:
      • Code (Read & Write) - Read repository contents and create branches
      • Pull Requests (Read & Write) - Read PRs, create PRs, and post comments
      • Project and Team (Read) - Access project and team information
      • User Profile (Read) - Read user information
  4. Click "Create"
  5. Copy the token immediately - you won't be able to see it again

Step 3: Configure Token in Codity

  1. Return to Codity Settings → Providers → Azure DevOps
  2. Paste your Personal Access Token into the "Azure DevOps Token" field
  3. If using Azure DevOps Server (on-premises), enter your Azure DevOps Server URL
  4. Click "Save" to store the token

Step 4: Enable Repositories

  1. Navigate to Repositories → Add Repository
  2. Select Azure DevOps as your provider
  3. Choose your organization and project
  4. Select the repositories you want to enable for code reviews
  5. Click "Enable" for each repository

Step 5: Verify Setup

  1. Create a test pull request in one of your connected repositories
  2. Wait 1-3 minutes for Codity to analyze the PR
  3. Check the PR comments to see Codity's review feedback

Azure DevOps Server (On-Premises) Setup

If you're using Azure DevOps Server (on-premises):

  1. Configure Server URL: In Codity Settings → Azure DevOps, enter your Azure DevOps Server URL:
    • Format: https://your-server.com/{collection}
    • Example: https://tfs.company.com/DefaultCollection
  2. Network Requirements: Ensure your Azure DevOps Server is accessible from the internet (or from Codity's servers if using a private network)
  3. SSL Certificate: Your server must have a valid SSL certificate
  4. Same Features: Azure DevOps Server supports the same features as Azure DevOps Services

Issue: "MSA Not Supported" or "Personal Account Error"

Symptoms:

  • Error message about personal Microsoft accounts not being supported
  • Cannot sign in with personal Microsoft account

Solutions:

  1. Use organizational account: You must use a work or school account (organizational account), not a personal Microsoft account
  2. Check account type: Verify you're signing in with an account that has an organizational email (e.g., user@company.com not user@outlook.com)
  3. Contact admin: If you don't have an organizational account, contact your organization's IT admin to create one
  4. Switch accounts: If you're already signed in with a personal account, sign out and sign in with your organizational account

Best Practices

  1. Use organizational accounts: Always use work or school accounts, never personal Microsoft accounts
  2. Set appropriate token expiration: Use 90-day expiration for balance of security and convenience
  3. Rotate tokens proactively: Update tokens 1-2 weeks before expiration to avoid downtime
  4. Use descriptive token names: Name tokens clearly with organization and expiration date (e.g., "Codity - Contoso - Expires 2024-03-15")
  5. Monitor token usage: Periodically review active tokens in Azure DevOps and revoke unused ones
  6. Document token expiration dates: Keep track of when tokens expire to plan rotations
  7. Test after token updates: After updating a token, create a test PR to verify everything works
  8. Organization-level tokens: Consider using organization-level tokens when managing multiple projects
  9. Separate tokens for multiple organizations: If you have multiple organizations, use separate tokens for better security and management

Next Steps