Personalizzare la pipeline

  • Articolo

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Questa è una guida dettagliata sui modi comuni per personalizzare la pipeline.

Prerequisito

Seguire le istruzioni in Creare la prima pipeline per creare una pipeline di lavoro.

Informazioni sul azure-pipelines.yml file

Una pipeline viene definita usando un file YAML nel repository. In genere, questo file è denominato azure-pipelines.yml e si trova nella radice del repository.

Passare alla pagina Pipeline in Azure Pipelines, selezionare la pipeline creata e scegliere Modifica nel menu di scelta rapida della pipeline per aprire l'editor YAML per la pipeline.

Nota

Per istruzioni su come visualizzare e gestire le pipeline nel portale di Azure DevOps, vedere Visualizzare e gestire le pipeline.

Esaminare il contenuto del file YAML.

 trigger:
 - main

 pool:
   vmImage: 'ubuntu-latest'

 steps:
 - task: Maven@4
   inputs:
     mavenPomFile: 'pom.xml'
     mavenOptions: '-Xmx3072m'
     javaHomeOption: 'JDKVersion'
     jdkVersionOption: '1.11'
     jdkArchitectureOption: 'x64'
     publishJUnitResults: false
     testResultsFiles: '**/surefire-reports/TEST-*.xml'
     goals: 'package'

Nota

Il contenuto del file YAML può essere diverso a seconda del repository di esempio avviato o degli aggiornamenti eseguiti in Azure Pipelines.

Questa pipeline viene eseguita ogni volta che il team esegue il push di una modifica al ramo principale del repository o crea una richiesta pull. Viene eseguito in un computer Linux ospitato da Microsoft. Il processo della pipeline ha un singolo passaggio, che consiste nell'eseguire l'attività Maven.

Modificare la piattaforma per la compilazione

È possibile compilare il progetto in agenti ospitati da Microsoft che includono già SDK e strumenti per vari linguaggi di sviluppo. In alternativa, è possibile usare agenti self-hosted con strumenti specifici necessari.

  • Passare all'editor per la pipeline selezionando Modifica azione pipeline nella compilazione o selezionando Modifica nella pagina principale della pipeline.

  • Attualmente la pipeline viene eseguita in un agente Linux:

    pool:
  vmImage: "ubuntu-latest"

  • Per scegliere una piattaforma diversa come Windows o Mac, modificare il vmImage valore:

    pool:
  vmImage: "windows-latest"

    pool:
  vmImage: "macos-latest"

  • Selezionare Salva e quindi confermare le modifiche per visualizzare l'esecuzione della pipeline in una piattaforma diversa.

Aggiungere passaggi

È possibile aggiungere altri script o attività come procedura alla pipeline. Un'attività è uno script preconfezionato. È possibile usare le attività per la compilazione, il test, la pubblicazione o la distribuzione dell'app. Per Java, l'attività Maven usata gestisce i risultati dei test e della pubblicazione, tuttavia, è possibile usare un'attività per pubblicare anche i risultati del code coverage.

  • Aprire l'editor YAML per la pipeline.

  • Aggiungere il frammento di codice seguente alla fine del file YAML.

    - task: PublishCodeCoverageResults@1
  inputs:
    codeCoverageTool: "JaCoCo"
    summaryFileLocation: "$(System.DefaultWorkingDirectory)/**/site/jacoco/jacoco.xml"
    reportDirectory: "$(System.DefaultWorkingDirectory)/**/site/jacoco"
    failIfCoverageEmpty: true

  • Selezionare Salva e quindi confermare le modifiche.

  • È possibile visualizzare i risultati del test e del code coverage selezionando la compilazione e passando alle schede Test e Coverage .

Compilazione tra più piattaforme

È possibile compilare e testare il progetto su più piattaforme. Un modo per farlo è con strategy e matrix. È possibile usare le variabili per inserire facilmente i dati in varie parti di una pipeline. Per questo esempio si userà una variabile per passare il nome dell'immagine da usare.

  • azure-pipelines.yml Nel file sostituire il contenuto seguente:

    pool:
  vmImage: "ubuntu-latest"

    con il contenuto seguente:

    strategy:
  matrix:
    linux:
      imageName: "ubuntu-latest"
    mac:
      imageName: "macOS-latest"
    windows:
      imageName: "windows-latest"
  maxParallel: 3

pool:
  vmImage: $(imageName)

  • Selezionare Salva e quindi confermare le modifiche per visualizzare l'esecuzione della compilazione fino a tre processi in tre piattaforme diverse.

Ogni agente può eseguire un solo processo alla volta. Per eseguire più processi in parallelo, è necessario configurare più agenti. Sono necessari anche processi paralleli sufficienti.

Compilazione con più versioni

Per compilare un progetto usando versioni diverse di tale linguaggio, è possibile usare una matrix delle versioni e una variabile. In questo passaggio è possibile compilare il progetto Java con due diverse versioni di Java in una singola piattaforma o eseguire versioni diverse di Java su piattaforme diverse.

Nota

Non è possibile usare strategy più volte in un contesto.

  • Se si vuole eseguire la compilazione su una singola piattaforma e su più versioni, aggiungere la matrice seguente al azure-pipelines.yml file prima dell'attività Maven e dopo .vmImage

    strategy:
  matrix:
    jdk10:
      jdkVersion: "1.10"
    jdk11:
      jdkVersion: "1.11"
  maxParallel: 2

  • Sostituire quindi questa riga nell'attività maven:

    jdkVersionOption: "1.11"

    con questa riga:

    jdkVersionOption: $(jdkVersion)

  • Assicurarsi di ripristinare la $(imageName) variabile nella piattaforma preferita.

  • Se si vuole eseguire la compilazione su più piattaforme e versioni, sostituire l'intero contenuto nel azure-pipelines.yml file prima dell'attività di pubblicazione con il frammento di codice seguente:

    trigger:
- main

strategy:
  matrix:
    jdk10_linux:
      imageName: "ubuntu-latest"
      jdkVersion: "1.10"
    jdk11_windows:
      imageName: "windows-latest"
      jdkVersion: "1.11"
  maxParallel: 2

pool:
  vmImage: $(imageName)

steps:
- task: Maven@4
  inputs:
    mavenPomFile: "pom.xml"
    mavenOptions: "-Xmx3072m"
    javaHomeOption: "JDKVersion"
    jdkVersionOption: $(jdkVersion)
    jdkArchitectureOption: "x64"
    publishJUnitResults: true
    testResultsFiles: "**/TEST-*.xml"
    goals: "package"

  • Selezionare Salva e quindi confermare le modifiche per visualizzare l'esecuzione di due processi di compilazione in due piattaforme e SDK diversi.

Personalizzare i trigger CI

I trigger della pipeline causano l'esecuzione di una pipeline. È possibile usare trigger: per fare in modo che una pipeline venga eseguita ogni volta che si esegue il push di un aggiornamento in un ramo. Le pipeline YAML sono configurate per impostazione predefinita con un trigger CI nel ramo predefinito , che in genere mainè . È possibile configurare trigger per rami specifici o per la convalida della richiesta pull. Per un trigger di convalida della richiesta pull, sostituire semplicemente il trigger: passaggio con come pr: illustrato nei due esempi seguenti. Per impostazione predefinita, la pipeline viene eseguita per ogni modifica della richiesta pull.

  • Per configurare i trigger, aggiungere uno dei frammenti di codice seguenti all'inizio del azure-pipelines.yml file.

    trigger:
  - main
  - releases/*

    pr:
  - main
  - releases/*

    È possibile specificare il nome completo del ramo , ad esempio main, o un carattere jolly corrispondente al prefisso , ad esempio releases/*.

Impostazioni della pipeline

È possibile visualizzare e configurare le impostazioni della pipeline dal menu Altre azioni nella pagina dei dettagli della pipeline.

Screenshot of pipeline settings and more actions menu.

  • Gestire la sicurezza Gestire la sicurezza -
  • Rinomina/sposta : modificare il nome e il percorso della cartella della pipeline. Screenshot of rename or move pipeline page.
  • Notifica di stato Aggiungere una notifica - di stato al repository
  • Elimina : elimina la pipeline, incluse tutte le compilazioni e gli artefatti associati.
  • Visualizzazione Esecuzioni - pianificate Esecuzioni pianificate

Scegliere Impostazioni per configurare le impostazioni della pipeline seguenti.

Screenshot of pipeline settings page.

Nel riquadro Impostazioni pipeline è possibile configurare le impostazioni seguenti.

  • Elaborazione di nuove richieste di esecuzione: a volte si vuole impedire l'avvio di nuove esecuzioni nella pipeline.

    • Per impostazione predefinita, l'elaborazione delle nuove richieste di esecuzione è Abilitata. Questa impostazione consente l'elaborazione standard di tutti i tipi di trigger, incluse le esecuzioni manuali.
    • Le pipeline sospese consentono l'elaborazione delle richieste di esecuzione, ma tali richieste vengono accodate senza avviare effettivamente. Quando è abilitata la nuova elaborazione delle richieste, eseguire l'elaborazione riprende a partire dalla prima richiesta nella coda.
    • Le pipeline disabilitate impediscono agli utenti di avviare nuove esecuzioni. Anche tutti i trigger vengono disabilitati mentre questa impostazione viene applicata. Tutti i criteri di compilazione che usano una pipeline disabilitata visualizzeranno il messaggio "Impossibile accodare la compilazione" accanto ai criteri di compilazione nella finestra di panoramica della richiesta pull e lo stato dei criteri di compilazione verrà interrotto.

  • Percorso del file YAML: se è necessario indirizzare la pipeline all'uso di un file YAML diverso, è possibile specificare il percorso del file. Questa impostazione può essere utile anche se è necessario spostare o rinominare il file YAML.

  • Collegare automaticamente gli elementi di lavoro inclusi in questa esecuzione : le modifiche associate a una determinata esecuzione della pipeline possono avere elementi di lavoro associati. Selezionare questa opzione per collegare tali elementi di lavoro all'esecuzione. Quando si seleziona Collegamento automatico degli elementi di lavoro inclusi in questa esecuzione , è necessario specificare un ramo specifico o * per tutti i rami, ovvero l'impostazione predefinita. Se si specifica un ramo, gli elementi di lavoro sono associati solo alle esecuzioni di tale ramo. Se si specifica *, gli elementi di lavoro sono associati per tutte le esecuzioni.

    Screenshot of setting to automatically link work items included in this run.

Gestione della sicurezza

È possibile configurare la sicurezza delle pipeline a livello di progetto dalla pagina di destinazione Altre azioni nella pagina di destinazione delle pipeline e a livello di pipeline nella pagina dei dettagli della pipeline.

Screenshot of pipeline security menu options.

Per supportare la sicurezza delle operazioni della pipeline, è possibile aggiungere utenti a un gruppo di sicurezza predefinito, impostare singole autorizzazioni per un utente o un gruppo o aggiungere utenti a ruoli predefiniti. È possibile gestire la sicurezza per Azure Pipelines nel portale Web, sia dall'utente che dal contesto di amministratore. Per altre informazioni sulla configurazione della sicurezza delle pipeline, vedere Autorizzazioni della pipeline e ruoli di sicurezza.

Creare un elemento di lavoro in caso di errore

Le pipeline YAML non hanno un elemento di lavoro Crea elemento di lavoro in caso di errore , ad esempio le pipeline di compilazione classiche. Le pipeline di compilazione classiche sono una singola fase e l'elemento di lavoro Crea in caso di errore si applica all'intera pipeline. Le pipeline YAML possono essere multi-fase e un'impostazione a livello di pipeline potrebbe non essere appropriata. Per implementare Crea elemento di lavoro in caso di errore in una pipeline YAML, è possibile usare metodi come l'elemento di lavoro - Creare una chiamata API REST o il comando az boards work-item create dell'interfaccia della riga di comando di Azure DevOps nel punto desiderato nella pipeline.

L'esempio seguente include due processi. Il primo processo rappresenta il lavoro della pipeline, ma in caso di errore, il secondo processo viene eseguito e crea un bug nello stesso progetto della pipeline.

# When manually running the pipeline, you can select whether it
# succeeds or fails.
parameters:
- name: succeed
  displayName: Succeed or fail
  type: boolean
  default: false

trigger:
- main

pool:
  vmImage: ubuntu-latest

jobs:
- job: Work
  steps:
  - script: echo Hello, world!
    displayName: 'Run a one-line script'

  # This malformed command causes the job to fail
  # Only run this command if the succeed variable is set to false
  - script: git clone malformed input
    condition: eq(${{ parameters.succeed }}, false)

# This job creates a work item, and only runs if the previous job failed
- job: ErrorHandler
  dependsOn: Work
  condition: failed()
  steps: 
  - bash: |
      az boards work-item create \
        --title "Build $(build.buildNumber) failed" \
        --type bug \
        --org $(System.TeamFoundationCollectionUri) \
        --project $(System.TeamProject)
    env: 
      AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
    displayName: 'Create work item on failure'

Nota

Azure Boards consente di configurare il rilevamento degli elementi di lavoro usando diversi processi, ad esempio Agile o Basic. Ogni processo ha tipi di elemento di lavoro diversi e non tutti i tipi di elemento di lavoro sono disponibili in ogni processo. Per un elenco dei tipi di elementi di lavoro supportati da ogni processo, vedere Tipi di elemento di lavoro (WIT).

Nell'esempio precedente vengono usati i parametri di runtime per configurare se la pipeline ha esito positivo o negativo. Quando si esegue manualmente la pipeline, è possibile impostare il valore del succeed parametro . Il secondo script passaggio del primo processo della pipeline valuta il succeed parametro e viene eseguito solo quando succeed è impostato su false.

Il secondo processo nella pipeline ha una dipendenza dal primo processo e viene eseguito solo se il primo processo ha esito negativo. Il secondo processo usa il comando az boards work-item create dell'interfaccia della riga di comando di Azure DevOps per creare un bug. Per altre informazioni sull'esecuzione dei comandi dell'interfaccia della riga di comando di Azure DevOps da una pipeline, vedere Eseguire comandi in una pipeline YAML.

Questo esempio usa due processi, ma questo stesso approccio può essere usato in più fasi.

Nota

È anche possibile usare un'estensione del Marketplace, ad esempio Crea bug in caso di errore di rilascio , che include il supporto per le pipeline YAML in più fasi.

Passaggi successivi

Sono state apprese le nozioni di base sulla personalizzazione della pipeline. È quindi consigliabile ottenere altre informazioni sulla personalizzazione di una pipeline per il linguaggio usato:

In alternativa, per aumentare la pipeline di integrazione continua a una pipeline CI/CD, includere un processo di distribuzione con i passaggi per distribuire l'app in un ambiente.

Per altre informazioni sugli argomenti di questa guida, vedere Processi, attività, catalogo di attività, variabili, trigger o risoluzione dei problemi.

Per informazioni sulle altre operazioni che è possibile eseguire nelle pipeline YAML, vedere le informazioni di riferimento sullo schema YAML.