Examples

Use these sample YAML files as boilerplate to get started with your workflows.

A few things before you get started

Each of these examples assume that your organization has a configured Agent Pool named ci-symitar with an agent online that has network access to your target Symitar host. Additionally, they are tailored to provide dynamic variables via Pipelines Library Variable Groups. Additionally, we recommend placing each of these pipelines in .ado/workflows from the root of your repository but you can place anywhere as long as they map correctly to the defined Azure Pipeline.

Pull Request

This pipeline (pr-pipeline.yml) is invoked whenever you create or update a Pull Request (PR). Its purpose is to test that each of the added or updated PowerOns are valid.

trigger: none # This pipeline is triggered by pull requests via Branch Policies

# Dynamic variable group selection based on target branch
# PRs to main use prod credentials, PRs to stage use stage credentials, all others use dev
variables:
  - ${{ if eq(variables['System.PullRequest.TargetBranch'], 'refs/heads/main') }}:
    - group: symitar-prod
  - ${{ elseif eq(variables['System.PullRequest.TargetBranch'], 'refs/heads/stage') }}:
    - group: symitar-stage
  - ${{ else }}:
    - group: symitar-dev

pool:
  name: ci-symitar

workspace:
  clean: all

steps:
- checkout: self
  fetchDepth: 0
  # In the PR context, this will only validate changes between target and source branches
- task: ValidatePowerOn@1
  displayName: 'Validate changed PowerOn files'
  inputs:
    connectionType: ssh
    apiKey: $(apiKey)
    symitarHostname: $(symitarHostname)
    sshUsername: $(sshUsername)
    sshPassword: $(sshPassword)
    symitarUserNumber: $(symitarUserNumber)
    symitarUserPassword: $(symitarUserPassword)

Merge Request

This pipeline (merge-pipeline.yml) is automatically invoked when PRs are merged to either main or stage branches and will do two things:

Validate Changed PowerOns

This is done by comparing the PR content relative to the target branch.

Prepare an Artifact

This will be referenced as "point in time" data to synchronize the Symitar host with during the release process

trigger:
  branches:
    include:
      - main
      - stage

# Dynamic variable group selection based on branch
variables:
  - ${{ if eq(variables['Build.SourceBranch'], 'refs/heads/main') }}:
    - group: symitar-prod
  - ${{ elseif eq(variables['Build.SourceBranch'], 'refs/heads/stage') }}:
    - group: symitar-stage
  - ${{ else }}:
    - group: symitar-dev

pool:
  name: ci-symitar

workspace:
  clean: all

steps:
- checkout: self
  fetchDepth: 0

  # In the build context, this will validate differences between current state and what exists
  # in the Sym number defined for the branch in .poweron-pipelines/config.yml
- task: ValidatePowerOn@1
  displayName: 'Validate changed PowerOn files'
  inputs:
    connectionType: ssh
    apiKey: $(apiKey)
    symitarHostname: $(symitarHostname)
    sshUsername: $(sshUsername)
    sshPassword: $(sshPassword)
    symitarUserNumber: $(symitarUserNumber)
    symitarUserPassword: $(symitarUserPassword)

- task: ArchiveFiles@2
  inputs:
    rootFolderOrFile: '$(Build.SourcesDirectory)'
    archiveFile: '$(Build.ArtifactStagingDirectory)/output.zip'
    includeRootFolder: false
    archiveType: zip
    archiveFilePatterns: |
      **/*
      !.git/**

- task: PublishBuildArtifacts@1
  displayName: 'Publish artifacts'
  inputs:
    pathtoPublish: '$(Build.ArtifactStagingDirectory)'
    artifactName: 'output'

Release

This pipeline (release-pipeline.yml) is automatically invoked at the successful completion of our symitar-merge build pipeline which is just pointing to the merge-pipeline.yml file above. You'll notice it only triggers on main branch, since this pipeline includes both Stage and Prod deployments.

This pipeline has a bit more to it but can be split up in the following way:

Stage Validation -> Stage Deployment

All that you need to know here is that we're effectively doing the exact same thing only the *Validation stage is executing the SynchronizeDirectory task with isDryRun set to true so that we can visualize the prescribed changes prior to deployment and get any approvals necessary along the way.

Prod Validation -> Prod Deployment

For this section, we're doing the same work but for a different environment, Prod.

trigger: none

resources:
  pipelines:
    - pipeline: build
      source: 'symitar-merge'
      trigger:
        branches:
          include:
            - main

stages:
  # Stage Environment - Validate and deploy to Stage Sym first
  - stage: StageValidation
    displayName: 'Stage Validation (Dry Run)'
    pool:
      name: ci-symitar
    variables:
      - group: symitar-stage
    jobs:
      - deployment: ValidateStageSynchronization
        displayName: 'Validate PowerOn Synchronization in Stage'
        environment: 'Stage'
        strategy:
          runOnce:
            deploy:
              steps:
                - download: build
                  artifact: output

                - task: ExtractFiles@1
                  inputs:
                    archiveFilePatterns: '$(Pipeline.Workspace)/build/output/output.zip'
                    destinationFolder: '$(Build.ArtifactStagingDirectory)/repo'

                - task: SynchronizeDirectory@1
                  displayName: 'Synchronize PowerOns to Stage (Dry Run)'
                  inputs:
                    directoryType: powerOns
                    syncMode: mirror
                    connectionType: ssh
                    isDryRun: true
                    artifactPath: 'repo'
                    symitarHostname: $(symitarHostname)
                    sshUsername: $(sshUsername)
                    sshPassword: $(sshPassword)
                    symitarUserNumber: $(symitarUserNumber)
                    symitarUserPassword: $(symitarUserPassword)
                    apiKey: $(apiKey)

  - stage: StageDeployment
    displayName: 'Stage Deployment'
    dependsOn: StageValidation
    condition: succeeded()
    pool:
      name: ci-symitar
    variables:
      - group: symitar-stage
    jobs:
      - deployment: SynchronizeStage
        displayName: 'Synchronize PowerOns to Stage'
        environment: 'Stage'
        strategy:
          runOnce:
            deploy:
              steps:
                - download: build
                  artifact: output

                - task: ExtractFiles@1
                  inputs:
                    archiveFilePatterns: '$(Pipeline.Workspace)/build/output/output.zip'
                    destinationFolder: '$(Build.ArtifactStagingDirectory)/repo'

                - task: SynchronizeDirectory@1
                  displayName: 'Synchronize PowerOns to Stage'
                  inputs:
                    directoryType: powerOns
                    syncMode: mirror
                    connectionType: ssh
                    isDryRun: false
                    artifactPath: 'repo'
                    symitarHostname: $(symitarHostname)
                    sshUsername: $(sshUsername)
                    sshPassword: $(sshPassword)
                    symitarUserNumber: $(symitarUserNumber)
                    symitarUserPassword: $(symitarUserPassword)
                    apiKey: $(apiKey)

  # Prod Environment - Requires manual approval via Azure DevOps Environment settings
  - stage: ProdValidation
    displayName: 'Prod Validation (Dry Run)'
    dependsOn: StageDeployment
    condition: succeeded()
    pool:
      name: ci-symitar
    variables:
      - group: symitar-prod
    jobs:
      - deployment: ValidateSynchronization
        displayName: 'Validate PowerOn Synchronization'
        environment: 'Prod'
        strategy:
          runOnce:
            deploy:
              steps:
                - download: build
                  artifact: output

                - task: ExtractFiles@1
                  inputs:
                    archiveFilePatterns: '$(Pipeline.Workspace)/build/output/output.zip'
                    destinationFolder: '$(Build.ArtifactStagingDirectory)/repo'

                - task: SynchronizeDirectory@1
                  displayName: 'Synchronize PowerOns (Dry Run)'
                  inputs:
                    directoryType: powerOns
                    syncMode: mirror
                    connectionType: ssh
                    isDryRun: true
                    artifactPath: 'repo'
                    symitarHostname: $(symitarHostname)
                    sshUsername: $(sshUsername)
                    sshPassword: $(sshPassword)
                    symitarUserNumber: $(symitarUserNumber)
                    symitarUserPassword: $(symitarUserPassword)
                    apiKey: $(apiKey)

  - stage: Prod
    displayName: 'Prod Deployment'
    dependsOn: ProdValidation
    condition: succeeded()
    pool:
      name: ci-symitar
    variables:
      - group: symitar-prod
    jobs:
      - deployment: SynchronizePowerOns
        displayName: 'Synchronize PowerOns in Prod'
        environment: 'Prod'
        strategy:
          runOnce:
            deploy:
              steps:
                - download: build
                  artifact: output

                - task: ExtractFiles@1
                  inputs:
                    archiveFilePatterns: '$(Pipeline.Workspace)/build/output/output.zip'
                    destinationFolder: '$(Build.ArtifactStagingDirectory)/repo'

                - task: SynchronizeDirectory@1
                  displayName: 'Synchronize PowerOns to Prod'
                  inputs:
                    directoryType: powerOns
                    syncMode: mirror
                    connectionType: ssh
                    isDryRun: false
                    artifactPath: 'repo'
                    symitarHostname: $(symitarHostname)
                    sshUsername: $(sshUsername)
                    sshPassword: $(sshPassword)
                    symitarUserNumber: $(symitarUserNumber)
                    symitarUserPassword: $(symitarUserPassword)
                    apiKey: $(apiKey)