DeployBrief DeployBrief
← Back to Documentation

Azure DevOps Setup

Connect your Azure DevOps organization to DeployBrief for seamless deployment brief generation.

Overview

DeployBrief integrates with Azure DevOps to automatically generate deployment briefs from your pipelines. This guide walks you through creating a Personal Access Token (PAT), connecting your organization, and testing the connection.

Step 1: Create a Personal Access Token

Personal Access Tokens are required to authenticate DeployBrief with Azure DevOps.

Creating a PAT:

  1. Navigate to dev.azure.com
  2. Click your profile icon in the top-right corner
  3. Select Personal access tokens
  4. Click + New Token
  5. Configure the token:
    • Name: DeployBrief
    • Organization: Select your organization or "All accessible organizations"
    • Expiration: 90 days (recommended) or custom
    • Scopes: Select Custom defined, then choose:

      Required Scopes (Read only):

      • ✓ Build (Read)
      • ✓ Release (Read)
      • ✓ Work Items (Read)
      • ✓ Code (Read)
      • ✓ Test Management (Read)
  6. Click Create
  7. Copy the token immediately - you won't be able to see it again

Security Note: DeployBrief encrypts your PAT using Azure Key Vault before storing it. However, treat PATs like passwords - don't share them or commit them to source control.

Step 2: Connect Your Organization

Once you have your PAT, connect it to DeployBrief:

  1. In DeployBrief, navigate to Settings → Connections
  2. Click Add Connection
  3. Enter your Azure DevOps details:
    • Organization Name: Your Azure DevOps organization (e.g., "mycompany")
    • Personal Access Token: Paste the PAT you created
    • Display Name: Optional friendly name (e.g., "Production")
  4. Click Save Connection

Example:

Organization: mycompany
PAT: ********************************
Display Name: Production ADO

Step 3: Test the Connection

After saving, DeployBrief will automatically test the connection:

Success: Connection validated. You can now access projects and pipelines.

Failure: Check that your PAT is correct and has the required scopes.

Manual Testing

You can manually test the connection at any time:

  1. Go to Settings → Connections
  2. Find your connection in the list
  3. Click Test Connection
  4. View the results showing accessible projects and pipelines

Managing Multiple Connections

DeployBrief supports multiple Azure DevOps connections per workspace. This is useful if you have:

  • Multiple Azure DevOps organizations
  • Different PATs for different projects
  • Separate production and development environments

Tip: Use descriptive display names to distinguish connections, like "Production", "Staging", or "Client XYZ".

Troubleshooting

Authentication Failed

  • Verify your PAT hasn't expired
  • Check that all required scopes are granted
  • Ensure the organization name is correct (no spaces or special characters)
  • Try creating a new PAT

No Projects Visible

  • Confirm you have access to the Azure DevOps organization
  • Check that the PAT organization scope matches your organization
  • Verify "Code (Read)" scope is granted

No Pipelines Found

  • Ensure "Build (Read)" and "Release (Read)" scopes are granted
  • Check that pipelines exist in your selected project
  • Verify you have permissions to view pipelines in Azure DevOps

Security Best Practices

  • Use minimal scopes: Only grant Read permissions. Write access is never required.
  • Set expiration dates: Regularly rotate PATs (90 days recommended).
  • Monitor usage: Review PAT usage in Azure DevOps settings periodically.
  • Revoke unused tokens: Delete connections and PATs you no longer need.
  • Audit connections: Regularly review connected organizations in Settings.

Next Steps

Now that your Azure DevOps organization is connected: