> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blitzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure DevOps

> Connect Azure DevOps projects to Blitzy for AI-Native code generation

Azure DevOps integration lets Blitzy access your repositories to analyze code, create branches, push commits, and manage pull requests. Blitzy authenticates through a Microsoft Entra ID (formerly Azure AD) application using a dedicated service identity user in your ADO organization.

This guide walks an ADO administrator through the complete process of granting Blitzy controlled access to your source control repositories.

<Note>
  **Jump to:** [Prerequisites](#prerequisites) | [Permissions](#permissions) | [Setup](#create-the-service-identity-user) | [Repository Permissions](#configure-repository-level-permissions) | [Connect App](#connect-the-blitzy-ado-integration-app) | [Verification](#verification-and-testing)
</Note>

## Prerequisites

| Requirement               | Details                                                                                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Azure DevOps Organization | An active ADO Services organization (`dev.azure.com/{org}`)                                                                     |
| Microsoft Entra ID Tenant | Your ADO organization must be connected to an Entra ID tenant                                                                   |
| Admin Permissions         | Project Collection Administrator or Organization Owner role in ADO, plus User Administrator or Global Administrator in Entra ID |
| Target Repositories       | A list of the specific repositories (and branches) you intend to expose to Blitzy                                               |
| Basic Access License      | At least one available Basic license seat for the service user                                                                  |

<Warning>Never use a personal employee account for service integrations. Always create a dedicated service identity so that access is not disrupted by employee departures or password changes, and so that audit logs clearly identify vendor activity.</Warning>

## Permissions

Blitzy requires the following Azure DevOps permissions, scoped to the minimum level needed.

| Permission           | Access Level | Purpose                                            |
| -------------------- | ------------ | -------------------------------------------------- |
| Code (Read)          | Read         | Analyze your repositories and read source files    |
| Code (Write)         | Read & Write | Create branches and push generated code            |
| Pull Request Threads | Read & Write | Create and manage pull requests                    |
| Project and Team     | Read         | List available projects and repositories           |
| Work Items           | Read         | Reference work items in pull requests and branches |
| Build                | Read         | Monitor CI pipeline status on pull requests        |

<Note>The Blitzy Azure AD app requests broad permission scopes during installation. However, actual access is controlled entirely by the "Blitzy Service Access" custom security group you configure in ADO. The app can only perform actions that this group explicitly allows - regardless of what the OAuth consent screen lists.</Note>

<AccordionGroup>
  <Accordion title="Permission mapping reference">
    | Operation           | Required Permission                     | ADO Security Namespace |
    | ------------------- | --------------------------------------- | ---------------------- |
    | Clone repository    | Git Repositories: Read                  | `GitRepositories`      |
    | Create branch       | Git Repositories: CreateBranch          | `GitRepositories`      |
    | Push commits        | Git Repositories: Contribute            | `GitRepositories`      |
    | Create pull request | Git Repositories: PullRequestContribute | `GitRepositories`      |
    | Read work items     | Work Items: Read                        | `WorkItemTracking`     |
    | View build results  | Build: Read                             | `Build`                |
  </Accordion>

  <Accordion title="Permission quick reference by level">
    | Level               | Scope            | Permission       | Setting                        |
    | ------------------- | ---------------- | ---------------- | ------------------------------ |
    | Organization        | User Access      | Access Level     | Basic                          |
    | Project             | Security Group   | Group            | Blitzy Service Access (custom) |
    | All Repos (default) | Git repositories | All permissions  | **Deny**                       |
    | Specific Repos      | Individual repo  | Read, Contribute | **Allow**                      |
    | Protected Branches  | e.g., main       | Contribute       | **Deny**                       |
    | Working Branches    | e.g., develop    | Contribute       | **Allow**                      |
  </Accordion>
</AccordionGroup>

## Create the Service Identity User

Create a dedicated user account in Microsoft Entra ID for the Blitzy integration. This is a non-interactive account - it does not represent a real person.

<Steps>
  <Step title="Navigate to Entra ID User Management">
    Sign in to the **Microsoft Entra admin center** at `https://entra.microsoft.com`. Expand **Identity**, then select **Users** > **All users**. Click **+ New user** > **Create new user**.
  </Step>

  <Step title="Configure the service user properties">
    In the **Basics** tab, fill in the following fields:

    | Field               | Value                                                        |
    | ------------------- | ------------------------------------------------------------ |
    | User principal name | `svc-blitzy@yourdomain.com` (use your organization's domain) |
    | Display name        | Blitzy Service Account                                       |
    | Password            | Auto-generate or set a strong password. Store securely.      |
    | Account enabled     | Yes (checked)                                                |

    Under **Properties** (optional), set the Department to "Service Accounts" and the Job title to "Third-Party Integration - Blitzy" for easy identification.
  </Step>

  <Step title="Create the user">
    Click **Review + create**, then click **Create**.
  </Step>
</Steps>

<Tip>Consider disabling MFA for this service account, as Blitzy authenticates programmatically. Use Conditional Access policies to exclude this specific account. If your organization requires MFA for all accounts, work with Blitzy to use a service principal with certificate-based authentication instead.</Tip>

<Note>Ensure that this service account password does not expire (or is updated regularly before expiry per your organizational policy).</Note>

## Add the Service User to Azure DevOps

<Steps>
  <Step title="Open organization user settings">
    Sign in to your Azure DevOps organization at `https://dev.azure.com/{YourOrganization}`. Click **Organization settings** (gear icon at the bottom-left), then **Users** under **General**.
  </Step>

  <Step title="Add the service user">
    Click **Add users**. In the **Users or Service Principals** field, enter `svc-blitzy@yourdomain.com` and select the account when it appears.
  </Step>

  <Step title="Set access level">
    Set **Access level** to **Basic**. Basic is required for Code/Repos access - Stakeholder access does not include source control permissions for private projects.
  </Step>

  <Step title="Select projects">
    Under **Add to projects**, select **only** the project(s) that contain the repositories Blitzy needs to access. Do not select all projects.
  </Step>

  <Step title="Set initial group and confirm">
    Set **Azure DevOps Groups** to **Project Contributors** for now. Click **Add** to finalize. You will restrict this further in the next section using a custom security group.
  </Step>
</Steps>

<Warning>Adding the user to the Contributors group provides broad code access across all repos in the project by default. The next section shows how to create a custom group with restricted permissions and remove the user from Contributors.</Warning>

## Create a Custom Security Group

To enforce the principle of least privilege, create a custom security group that grants Blitzy only the specific permissions needed.

<Steps>
  <Step title="Create the group">
    Navigate to **Project settings** > **Permissions**. Click **+ New Group**. Set the name to `Blitzy Service Access` and description to `Custom security group for Blitzy third-party vendor.` Add `svc-blitzy@yourdomain.com` as a member. Click **Create**.
  </Step>

  <Step title="Remove the service user from Contributors">
    On the **Permissions** page, click the **Contributors** group, then the **Members** tab. Locate `svc-blitzy@yourdomain.com` and click **Remove**.
  </Step>
</Steps>

<Note>After this step, the service user's only project-level membership is the custom "Blitzy Service Access" group. All repository and branch permissions are configured through this group.</Note>

## Configure Repository-Level Permissions

Restrict Blitzy to specific repositories by denying access at the top level, then explicitly allowing access on individual repos.

### Deny Access to All Repositories (Default)

1. Navigate to **Project settings** > **Repos** > **Repositories**.
2. Click the top-level **Git repositories** node.
3. Click the **Security** tab.
4. Click **+ Add** and find the **"Blitzy Service Access"** group.
5. Set **all permissions** to **Deny**. Click **Save changes**.

### Allow Access on Specific Repositories

For each repository Blitzy should access, explicitly override the Deny with Allow.

1. Click the **specific repository** (e.g., "frontend-app").
2. Click the **Security** tab, then find or add the **"Blitzy Service Access"** group.
3. Set permissions:

| Permission | Setting   |
| ---------- | --------- |
| Read       | **Allow** |
| Contribute | **Allow** |
| Force push | **Deny**  |

4. Click **Save changes**. Repeat for each additional repository.

<Tip>Keep a record of which repos you grant access to. A simple spreadsheet or wiki page in ADO makes audits and access reviews easier.</Tip>

## Branch-Level Security and Policies

<AccordionGroup>
  <Accordion title="Configure branch-level security (optional)">
    Azure DevOps lets you set permissions on individual branches to control which branches Blitzy can push to, create pull requests against, or read.

    **Open branch security settings:**

    1. Navigate to **Repos** > **Branches** within the target project.
    2. Locate the branch (e.g., **main**), click **... (More actions)** > **Branch security**.

    **Add the Blitzy group and set permissions:**

    1. In the **Branch security** panel, click **+ Add**.
    2. Search for and select the **"Blitzy Service Access"** group.
    3. For protected branches like **main**, set Contribute to **Deny**. For working branches like **develop**, set Contribute to **Allow**.
    4. Click **Save**.

    <Note>Branch permissions override repository-level permissions. If Blitzy has "Contribute = Allow" at the repo level but "Contribute = Deny" on `main`, it can push to other branches but not `main`. This is the desired outcome.</Note>

    **Recommended branching strategy:**

    | Branch             | Read      | Contribute (Push) | Create Pull Requests |
    | ------------------ | --------- | ----------------- | -------------------- |
    | `main`             | **Allow** | **Deny**          | **Allow**            |
    | `develop`          | **Allow** | **Allow**         | **Allow**            |
    | `feature/blitzy-*` | **Allow** | **Allow**         | **Allow**            |
    | `release/*`        | **Allow** | **Deny**          | **Deny**             |
  </Accordion>

  <Accordion title="Set up branch policies (optional)">
    Branch policies enforce code review and build validation even if Blitzy has Contribute permissions on a branch.

    1. Navigate to **Project settings** > **Repos** > **Repositories** > select the target repository.
    2. Click the **Policies** tab, then select the branch (e.g., `main`).
    3. Enable the following recommended policies:
       * **Require a minimum number of reviewers** - Set to at least 1 reviewer
       * **Check for linked work items** - Optional but recommended for traceability
       * **Check for comment resolution** - Require all comments resolved before merge
       * **Build validation** - Add a build pipeline that must succeed before PR completion
       * **Automatically included reviewers** - Add your team lead as an auto-reviewer for PRs
    4. Click **Save**.

    <Warning>Never grant Blitzy the "Bypass policies when completing pull requests" or "Bypass policies when pushing" permissions. These would allow the vendor to skip code reviews and CI checks.</Warning>
  </Accordion>
</AccordionGroup>

## Connect the Blitzy ADO Integration App

Blitzy's Azure AD app uses OAuth to authenticate. Ensure third-party application access is enabled in your ADO organization settings.

<Steps>
  <Step title="Verify OAuth settings">
    Navigate to **Organization settings** > **Policies** (under Security). Locate the **Third-party application access via OAuth** policy and ensure the toggle is set to **On**.
  </Step>

  <Step title="Install the Blitzy Azure AD application">
    Follow the guidance in the Blitzy platform to set up the ADO integration. Use the service identity account `svc-blitzy@yourdomain.com` to connect.
  </Step>

  <Step title="Share the integration">
    In the Blitzy platform, **Share** the ADO integration with your Blitzy teams.
  </Step>
</Steps>

<Warning>If your organization uses Conditional Access policies that block third-party OAuth by default, enabling the ADO toggle alone is not sufficient. You must also create a Conditional Access exclusion for the service identity account targeting the app registration.</Warning>

## Verification and Testing

After completing the configuration, verify that the setup works correctly and that permissions are properly restricted.

| Test                             | Expected Result                     |
| -------------------------------- | ----------------------------------- |
| Clone allowed repo               | Should succeed                      |
| Clone denied repo                | Should fail with 403/TF401019 error |
| Push to allowed branch (develop) | Should succeed                      |
| Push to protected branch (main)  | Should fail with TF402455 error     |

<AccordionGroup>
  <Accordion title="Pull request and integration tests">
    **Test pull request creation:**

    1. Create a pull request from a permitted branch to `main`.
    2. Confirm the PR is created successfully.
    3. Verify that branch policies (required reviewers, build validation) are enforced.

    **Test the Blitzy integration:**

    1. Log in to the Blitzy platform.
    2. Create a test project.
    3. Ensure that this project can only see the allowed repos and branches.
  </Accordion>
</AccordionGroup>

<Tip>Document the test results and keep them as part of your compliance records. This is especially useful during security audits.</Tip>

## Ongoing Maintenance

* **Quarterly reviews** - Review Blitzy's access level, repository permissions, and branch permissions every quarter
* **Last access date** - Check the Users page in Organization settings to see when the service user last accessed ADO
* **Audit logs** - Review ADO audit logs regularly (**Organization settings** > **Auditing**)

## Offboarding Blitzy

<Steps>
  <Step title="Revoke ADO access">
    Remove the service user from all projects. Delete the "Blitzy Service Access" security group.
  </Step>

  <Step title="Disable the identity">
    Delete or disable the Entra ID user account (`svc-blitzy@yourdomain.com`).
  </Step>

  <Step title="Remove the app">
    Uninstall the Blitzy Azure AD app. Contact Blitzy support to remove the ADO integration from the Blitzy platform.
  </Step>

  <Step title="Document">
    Record the offboarding in your change management system.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Service user not found when adding to ADO">
    Ensure the Entra ID tenant is connected to the ADO organization (**Org settings** > **Microsoft Entra**). The user must exist in the same tenant.
  </Accordion>

  <Accordion title="Clone fails with 401 Unauthorized">
    Confirm that the user is the service identity user, not your personal account.
  </Accordion>

  <Accordion title="Clone fails with 403 Forbidden">
    The repository permission is set to Deny. Check if the correct repo has Allow set on Read for the Blitzy group.
  </Accordion>

  <Accordion title="Push fails on an allowed branch">
    Check branch-level security. The Blitzy group may have Contribute = Deny or Not set on that branch.
  </Accordion>

  <Accordion title="PR cannot be completed">
    Branch policies may be blocking. Ensure that reviewers have approved, builds pass, and comments are resolved.
  </Accordion>

  <Accordion title="Permission changes not taking effect">
    ADO caches permissions. Wait a few minutes, clear browser cache, or sign out and back in.
  </Accordion>
</AccordionGroup>

## Security Checklist

<Accordion title="Pre-handoff security verification">
  * [ ] Dedicated service identity user created in Entra ID (not a personal account)
  * [ ] Service user added to ADO with Basic access level
  * [ ] Custom "Blitzy Service Access" security group created
  * [ ] Service user removed from default Contributors group
  * [ ] All repositories set to Deny at the top-level for the custom group
  * [ ] Only authorized repositories have explicit Allow permissions
  * [ ] Branch-level security configured: protected branches deny push access (optional)
  * [ ] Branch policies enabled - required reviewers, build validation (optional)
  * [ ] Third-party OAuth access enabled in Organization policies (if required)
  * [ ] Clone, push, and PR tests passed for both allowed and denied repos/branches
  * [ ] Access review schedule established (quarterly)
  * [ ] Offboarding procedure documented
</Accordion>