Skip to content

azure-devops.md

Latest commit

 

History

History
282 lines (214 loc) · 8.97 KB

azure-devops.md

File metadata and controls

282 lines (214 loc) · 8.97 KB
Raw

Azure DevOps Pipelines Integration — Accellens

Версия: 1.0 Дата: 10 ноября 2025

1. Обзор

Интеграция Accellens с Azure DevOps Pipelines позволяет запускать web сканы как часть CI/CD pipelines. Поддерживает PR-комментарии, статусные проверки и публикацию отчётов.

2. Установка

Быстрый старт

Скопируйте template в ваш проект:

mkdir -p ci-cd/azure-pipelines
cp ci-cd/azure-pipelines/accellens-scan.yml ci-cd/azure-pipelines/

Добавьте в azure-pipelines.yml:

trigger:
  branches:
    include:
      - main
      - develop
  pullRequest:
    branches:
      include:
        - main

pool:
  vmImage: 'ubuntu-latest'

variables:
  ACCELLENS_PROJECT: 'my-project'
  ACCELLENS_API_URL: 'https://api.accellens.dev'
  ACCELLENS_OUTPUT_FORMAT: 'json'
  ACCELLENS_FAIL_ON: 'high'

stages:
  - stage: AccessibilityScan
    displayName: 'Accessibility Scan'
    jobs:
      - job: AccellensScan
        displayName: 'Run Accellens Scan'
        steps:
          - template: ci-cd/azure-pipelines/accellens-scan.yml
            parameters:
              accellensProject: $(ACCELLENS_PROJECT)
              accellensUrl: 'https://example.com'
              accellensApiUrl: $(ACCELLENS_API_URL)
              accellensOutputFormat: $(ACCELLENS_OUTPUT_FORMAT)
              accellensFailOn: $(ACCELLENS_FAIL_ON)

Настройка переменных

В Azure DevOps перейдите в Pipelines → Your Pipeline → Edit → Variables и добавьте:

  • ACCELLENS_TOKEN — API токен (отметьте как secret)
  • ACCELLENS_PROJECT — slug проекта (опционально, можно указать в pipeline)

Или используйте Variable Groups:

  1. Pipelines → Library → Variable groups
  2. Создайте группу accellens-variables
  3. Добавьте переменные в группу
  4. Используйте в pipeline:
variables:
  - group: accellens-variables

3. Параметры Template

Параметр Обязателен По умолчанию Описание
accellensProject ✅ - Slug проекта в Accellens
accellensUrl ✅* - URL для сканирования (*если не указан accellensUrlsFile)
accellensUrlsFile ✅* urls.txt Файл со списком URL (*если не указан accellensUrl)
accellensApiUrl ❌ https://api.accellens.dev Базовый URL API
accellensOutputFormat ❌ json Формат отчёта: json, pdf, sarif
accellensFailOn ❌ none Уровень для fail: critical, high, medium, low, none
accellensWaitTimeout ❌ 900 Таймаут ожидания (секунды)

Переменные окружения

Можно использовать переменные окружения вместо параметров:

  • ACCELLENS_PROJECT
  • ACCELLENS_URL или ACCELLENS_URLS_FILE
  • ACCELLENS_API_URL
  • ACCELLENS_OUTPUT_FORMAT
  • ACCELLENS_FAIL_ON
  • ACCELLENS_WAIT_TIMEOUT

4. Настройка Variables

  1. Перейдите в Pipelines → Your Pipeline → Edit → Variables
  2. Добавьте переменные:
    • ACCELLENS_PROJECT: slug вашего проекта
    • ACCELLENS_TOKEN: ваш API токен (отметьте как secret)

Или используйте Variable Groups:

  1. Pipelines → Library → Variable groups
  2. Создайте группу accellens-variables
  3. Добавьте переменные в группу
  4. Используйте в pipeline:
variables:
  - group: accellens-variables

5. Выходные данные

  • Артефакт отчёта (accellens-report.json/pdf) в Azure Artifacts.
  • Test Results (через PublishTestResults task).
  • Pipeline status (pass/fail).
  • PR комментарии (через Azure DevOps REST API).

6. Расширенная конфигурация

Интеграция с Pull Requests

trigger:
  branches:
    include:
      - main
  pullRequest:
    branches:
      include:
        - main

steps:
  # ... предыдущие шаги ...

  - task: PowerShell@2
    condition: and(succeeded(), eq(variables['Build.Reason'], 'PullRequest'))
    inputs:
      targetType: 'inline'
      script: |
        $report = Get-Content accellens-report.json | ConvertFrom-Json
        $comment = "## Accessibility Scan Results`n`n"
        $comment += "**Findings:** $($report.findings.Count)`n"
        $comment += "**AAS Score:** $($report.aas_score)`n"

        $headers = @{
          Authorization = "Bearer $(System.AccessToken)"
        }

        $body = @{
          comments = @(
            @{
              parentCommentId = 0
              content = $comment
              commentType = 1
            }
          )
        } | ConvertTo-Json -Depth 10

        Invoke-RestMethod -Uri "$(System.CollectionUri)$(System.TeamProject)/_apis/git/repositories/$(Build.Repository.ID)/pullRequests/$(System.PullRequest.PullRequestId)/threads?api-version=7.0" -Method Post -Headers $headers -Body $body -ContentType "application/json"
    displayName: 'Post PR Comment'

Использование YAML Templates

Создайте templates/accellens-scan.yml:

parameters:
  - name: project
    type: string
  - name: urls
    type: string
    default: './urls.txt'
  - name: failOn
    type: string
    default: 'none'

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'

  - script: |
      npm install -g @accellens/cli
    displayName: 'Install Accellens CLI'

  - script: |
      accellens scan \
        --project ${{ parameters.project }} \
        --urls ${{ parameters.urls }} \
        --token $(ACCELLENS_TOKEN) \
        --fail-on ${{ parameters.failOn }} \
        --output-format json
    displayName: 'Run Accessibility Scan'
    env:
      ACCELLENS_TOKEN: $(ACCELLENS_TOKEN)

Используйте в azure-pipelines.yml:

resources:
  repositories:
    - repository: templates
      type: git
      name: YourProject/templates

extends:
  template: templates/accellens-scan.yml@templates
  parameters:
    project: 'mysite'
    urls: './urls.txt'
    failOn: 'high'

7. Секреты и безопасность

  • ACCELLENS_TOKEN хранится в Azure DevOps Variables (отметьте как secret).
  • Используйте Variable Groups для управления секретами на уровне проекта/организации.
  • Для production используйте Azure Key Vault интеграцию.
  • Используйте System.AccessToken для доступа к Azure DevOps API.

8. Ограничения

  • Максимум 20 URL за запуск (MVP).
  • Скан занимает до 10 минут; увеличивайте ACCELLENS_WAIT_TIMEOUT при необходимости.
  • Mobile сканы не поддерживаются (будет отдельный task v1+).

9. Troubleshooting

Симптом Причина Решение
Pipeline timeout Длинные сканы Увеличить ACCELLENS_WAIT_TIMEOUT, оптимизировать URL список
HTTP 401 Неверный токен Обновить variable, проверить права
Task не пишет отчёт Недостаточно прав Убедиться в праве Contribute на репозиторий

10. Roadmap интеграций

  • Azure DevOps Extension для Accellens (v1).
  • Mobile scan task (accellens/mobile-scan).
  • Интеграция с Azure Security Center.
  • Work Item интеграция для создания задач из findings.

11. Связанные документы