# Azure DevOps Integration Setup Guide

This guide walks you through connecting Lathe Studio to Azure DevOps for CI/CD pipeline integration.

---

## Prerequisites

- Azure DevOps account (Azure DevOps Services or Azure DevOps Server)
- Azure DevOps project with build pipelines
- Project admin access in Lathe Studio

---

## Overview

The Azure DevOps integration enables:

- **CI/CD Webhooks**: Automatically create builds when Azure Pipelines complete
- **Work Item Sync**: Link test failures to Azure DevOps work items
- **Pull Request Integration**: Display test results in PRs

---

## Connecting Azure DevOps

### Step 1: Create an API Key

1. Go to **Settings > Organization > API Keys**  
2. Click **Create API Key**  
3. Give it a name (e.g., "Azure DevOps")  
4. Select scopes:
   - `builds:read` \- View builds  
   - `builds:create` \- Create new builds  
5. Copy the generated key (shown only once)

### Step 2: Configure Azure DevOps Service Hook

1. In Azure DevOps, go to your project  
2. Navigate to **Project Settings > Service Hooks**  
3. Click **Create subscription**  
4. Select **Web Hooks** as the service  
5. Configure trigger:
   - **Event**: Build completed  
   - **Filter**: Select your build pipeline  
6. Configure action:
   - **URL**: `https://lathestudio.dev/api/webhooks/azure-devops`  
   - **HTTP Headers**:
     - `Authorization`: `Bearer <your-api-key>`  
     - `Content-Type`: `application/json`  
7. Click **Finish**

### Step 3: Test the Integration

1. Run a build in Azure DevOps  
2. Go to **Releases** page in Lathe Studio  
3. You should see the build in the **Build Queue** section  
4. Assign it to a release

---

## Authentication Methods

### Method 1: API Key (Recommended)

Include the API key in the Authorization header:

```
Authorization: Bearer pt_live_xxxxxxxxxxxxxxxx
```

### Method 2: Organization ID

Include your organization ID in a custom header:

```
X-Pt-Org-Id: your-org-uuid
```

---

## How It Works

1. **Build Completes** → Azure DevOps sends webhook to `/api/webhooks/azure-devops`  
2. **Authentication** → Webhook verifies API key or org ID  
3. **Project Matching** → System tries to match project URL to a Lathe Studio project  
4. **Queue or Create**:
   - If project + active release found → Build created directly  
   - If project found but no release → Queued for release assignment  
   - If no project match → Queued for project + release assignment  
5. **Assignment** → User assigns queued builds via Releases page

---

## Build Queue UI

The Build Queue appears on the Releases page when there are pending builds:

- Shows build name, source (Azure DevOps), project, commit/branch  
- **Assign to Release**: Select an active release for the project  
- **Select Project**: Navigate to projects if project not auto-detected  
- **Reject**: Remove build from queue (no build created)

---

## Azure Pipelines Example

Add this to your `azure-pipelines.yml`:

```yaml
trigger:
  branches:
    include:
      - main
      - develop

stages:
  - stage: Test
    jobs:
      - job: RunTests
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - script: npm test
            displayName: 'Run tests'

- script: |
              curl -X POST https://lathestudio.dev/api/v1/results/ingest \
                -H "Authorization: Bearer $(PT_API_KEY)" \
                -H "Content-Type: application/json" \
                -d '{
                  "build_name": "Build $(Build.BuildNumber)",
                  "branch": "$(Build.SourceBranchName)",
                  "commit_sha": "$(Build.SourceVersion)",
                  "test_results": [...]
                }'
            displayName: 'Notify Lathe Studio'
            env:
              PT_API_KEY: $(PT_API_KEY)
```

---

## Azure DevOps Server (On-Premises)

For on-premises Azure DevOps Server:

1. Ensure your server is accessible from the internet (or use reverse proxy)  
2. Use the same webhook URL: `https://lathestudio.dev/api/webhooks/azure-devops`  
3. Configure SSL certificates properly  
4. Allowlist Lathe Studio IP addresses if using a firewall:
   - Contact support for current IP ranges

---

## Work Item Integration

To create work items for test failures:

1. Connect Azure DevOps in **Project Settings > Integrations**  
2. Configure work item type (Bug, Task, etc.)  
3. Map Lathe Studio fields to Azure DevOps fields  
4. Enable automatic work item creation (optional)

### Field Mappings

| Lathe Studio | Azure DevOps |
| --- | --- |
| Test Case Title | Title |
| Priority | Priority |
| Test Steps | Repro Steps |
| Tester Notes | Description |
| Environment | Environment |

---

## Troubleshooting

### Builds not appearing

1. Check service hook delivery in Azure DevOps (Project Settings > Service Hooks > History)  
2. Verify API key is not expired or revoked  
3. Ensure the build pipeline is correctly selected in the service hook  
4. Check that the project URL matches your Lathe Studio project settings

### Wrong project assigned

The system matches by:

1. Project URL (exact match)  
2. Project name (partial match)  
3. Repository URL

You can manually assign to the correct project from the queue.

### Rate limiting

API keys are limited to 60 requests per minute by default. Contact support to increase limits.

### Work items not creating

1. Verify Azure DevOps connection is active  
2. Check work item type is valid for your project  
3. Ensure you have permission to create work items  
4. Review field mappings for required fields

---

## Security

- API keys are hashed using SHA-256 before storage  
- Only the first 12 characters are stored for identification  
- Keys can be revoked at any time  
- Use Azure DevOps variable groups to securely store API keys  
- All webhook communications use HTTPS

---

## Unlinking Azure DevOps

To disconnect:

1. Go to **Project Settings > Service Hooks** in Azure DevOps  
2. Find the Lathe Studio subscription  
3. Click **Delete**

**Note**: Previously created builds remain in Lathe Studio. New builds will not be created until reconnected.

---

## Advanced Configuration

### Branch Filtering

Configure which branches trigger builds in **Project Settings > CI/CD**:

- Include: `main`, `develop`, `release/*`  
- Exclude: `dependabot/*`, `draft/*`

### Build Retention

Sync Azure DevOps build retention policies with Lathe Studio:

- Automatic cleanup of old builds  
- Archive completed releases

---

_For additional help, contact support._