# Azure DevOps Integration

Table of Contents

1. Prerequisites
2. Setup Instructions
3. Pipeline Configuration
4. Viewing Scan Results
5. Troubleshooting
6. Advanced Configuration

***

### Prerequisites

* Azure DevOps organization and project with pipeline permissions
* AquilaX account with API access
* Required AquilaX credentials:
  * API Token
  * Organization ID
  * Group ID

***

### Setup Instructions

#### Step 1: Obtain AquilaX Credentials

1. Log in to your AquilaX dashboard
2. Navigate to **Settings** → **API Tokens**
3. Copy your API Token, Organization ID, and Group ID

#### Step 2: Configure Azure DevOps Variables

1. In Azure DevOps, go to **Pipelines** → Select your pipeline → **Edit** → **Variables**
2. Add the following secret variable:
   * **Name**: `AQUILAX_API_TOKEN`
   * **Value**: Your API token
   * ✅ Enable **Keep this value secret**

#### Step 3: Create Pipeline File

Create `azure-pipelines.yml` in your repository root with the configuration below.

***

### Pipeline Configuration

#### Basic Pipeline Template

```yaml
trigger:
  - main

pr:
  - "*"

variables:
- name: AQUILAX_ORG_ID 
  value: "YOUR_ORGANIZATION_ID"
 
- name: AQUILAX_GROUP_ID 
  value: "YOUR_GROUP_ID"

- name: AQUILAX_GIT_URL
  value: "$(Build.Repository.Uri)"

- name: AQUILAX_BRANCH
  value: "$(Build.SourceBranchName)"

stages:
- stage: SecurityScan
  displayName: "AquilaX Security Scan"

  jobs:
  - job: AquilaXScan
    displayName: "Run AquilaX CI Scan"
    timeoutInMinutes: 10
    continueOnError: true

    pool:
      vmImage: "ubuntu-latest"

    steps:
    - checkout: self

    - task: UsePythonVersion@0
      inputs:
        versionSpec: "3.12"
      displayName: "Use Python 3.12"

    - script: |
        pip install --no-cache-dir --upgrade aquilax
        aquilax -v
      displayName: "Install AquilaX CLI"

    - script: |
        echo "Repo: $(Build.Repository.Uri)"
        echo "Branch: $(Build.SourceBranchName)"

        pip install --no-cache-dir --upgrade aquilax

        aquilax login "$(AQUILAX_API_TOKEN)" || exit 1

        aquilax ci-scan \
          "$(Build.Repository.Uri)" \
          --org-id "$(AQUILAX_ORG_ID)" \
          --group-id "$(AQUILAX_GROUP_ID)" \
          --branch "$(Build.SourceBranchName)"

      displayName: "Run AquilaX Security Scan"
      continueOnError: true
```

#### Configuration Parameters

| Variable            | Type     | Description                                          |
| ------------------- | -------- | ---------------------------------------------------- |
| `AQUILAX_API_TOKEN` | Secret   | API authentication token (stored as secret variable) |
| `AQUILAX_ORG_ID`    | Variable | Organization identifier                              |
| `AQUILAX_GROUP_ID`  | Variable | Group/project identifier                             |
| `AQUILAX_GIT_URL`   | Auto     | Repository URL (auto-populated)                      |
| `AQUILAX_BRANCH`    | Auto     | Branch name (auto-populated)                         |

<figure><img src="https://53914109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjAmSnvnfbHl4EDK56iDo%2Fuploads%2Fj0QwkAb4IjyQDcCXipPa%2Fpipeline-run-overview.png?alt=media&#x26;token=1d76d0bb-c852-49d1-8f4d-c38f321430e2" alt=""><figcaption></figcaption></figure>

#### Key Settings

**Triggers**

* `trigger: - main` - Runs on commits to main branch
* `pr: - "*"` - Runs on all pull requests

**Pipeline Behavior**

* `timeoutInMinutes: 10` - Scan timeout (adjust based on repository size)
* `continueOnError: true` - Pipeline continues even if issues are found (set to `false` to enforce security gates)
* `vmImage: "ubuntu-latest"` - Build agent (alternatives: `windows-latest`, `macos-latest`)

***

### Viewing Scan Results

#### Access Results

1. Navigate to **Pipelines** → **Runs** → Select your run
2. Click **Artifacts** section
3. Download **AquilaX-Scan-Results** → `results.sarif`

<figure><img src="https://53914109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjAmSnvnfbHl4EDK56iDo%2Fuploads%2FNatwhBIIWmRWqEzYFYOa%2Fscan-execution-log.png?alt=media&#x26;token=124b711a-734a-4f3e-9d82-93cdbaca79c0" alt=""><figcaption></figcaption></figure>

#### SARIF Report Contents

The SARIF report includes:

* Vulnerability details with severity levels
* Affected code locations
* Remediation recommendations
* Compliance findings

<figure><img src="https://53914109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjAmSnvnfbHl4EDK56iDo%2Fuploads%2FmLzLbaCK6WzzcugHMMoq%2Fscan-results-summary.png?alt=media&#x26;token=80bb9ce1-bc94-42f1-a8f7-e6b31f2a2218" alt=""><figcaption></figcaption></figure>

***

### Visual Guide

#### 1. **Pipeline Variables Setup**

Configure the API token as a secret variable in Azure DevOps.

#### 2. **Pipeline Run Overview**

View the pipeline execution status with all stages completed successfully.

#### 3. **Scan Execution Log**

Console output showing repository information, AquilaX CLI installation, and scan execution.

#### 4. **Scan Results Summary**

Security findings breakdown showing vulnerability counts by severity level.

#### 5. **Dashboard Results Link**

Complete scan results available on the AquilaX dashboard.

<figure><img src="https://53914109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjAmSnvnfbHl4EDK56iDo%2Fuploads%2FwPaZmv68c8WtTxHiJBTj%2Fdashboard-results-link.png?alt=media&#x26;token=a883990c-0398-41eb-97f8-a319428efff2" alt=""><figcaption></figcaption></figure>

***

### Troubleshooting

#### Common Issues

| Issue                              | Solution                                                                         |
| ---------------------------------- | -------------------------------------------------------------------------------- |
| **API token not found**            | Verify variable `AQUILAX_API_TOKEN` is created as a secret in pipeline variables |
| **Python installation fails**      | Update `versionSpec` to `"3.x"` for latest Python 3.x version                    |
| **AquilaX CLI installation fails** | Check network connectivity and PyPI access permissions                           |
| **Scan timeout**                   | Increase `timeoutInMinutes` value based on repository size                       |
| **SARIF file not generated**       | Verify scan completed successfully; add debug step to list files                 |

#### Debug Commands

```yaml
# Add before PublishBuildArtifacts step to debug
- script: |
    echo "Checking for SARIF file..."
    ls -la *.sarif || echo "No SARIF files found"
  displayName: "Debug: List SARIF files"
```

***

### Advanced Configuration

#### Multi-Branch Scanning

```yaml
trigger:
  branches:
    include:
    - main
    - develop
    - release/*
```

#### Scheduled Scans

```yaml
schedules:
- cron: "0 2 * * *"
  displayName: Daily security scan
  branches:
    include:
    - main
  always: true
```

#### Branch Protection

Enable build validation in branch policies:

1. Go to **Repos** → **Branches** → Select branch → **Branch policies**
2. Add **Build validation** → Select AquilaX pipeline
3. Set as **Required** to prevent merging with security issues

#### Multi-Stage Pipeline

```yaml
stages:
- stage: SecurityScan
  jobs:
  - job: AquilaXScan
    # ... scan configuration ...

- stage: Build
  dependsOn: SecurityScan
  condition: succeeded()
  jobs:
  - job: BuildApp
    steps:
    - script: echo "Building application..."

- stage: Deploy
  dependsOn: Build
  condition: succeeded()
  jobs:
  - deployment: DeployProd
    environment: 'production'
    strategy:
      runOnce:
        deploy:
          steps:
          - script: echo "Deploying..."
```

***

### Support

* **Documentation**: <https://docs.aquilax.ai>
* **Support**: <admin@aquilax.ai>

***

*Last Updated: February 2026*