Skip to content

Required Variables

Each referenced variable group must supply apiKey, symitarHostname, sshPort (normally 22), sshHostKey, symNumber, sshUsername, sshPassword, symitarUserNumber, and symitarUserPassword. Mark the API key and passwords as secrets. Use an administrator-approved SSH public key as described in host trust setup. Alternatively, omit sshHostKey only when the agent service account already trusts the host.

The explicit symNumber prevents a release pipeline's own branch from selecting the wrong SYM. Set it separately in each environment's variable group. These examples omit the deprecated connectionType and symitarAppPort inputs; v2.2 uses the Symitar connector over SSH.

Pull Request

Create an Azure DevOps pipeline from pr-pipeline.yml, then select it under Repos → Branches → target branch → Branch policies → Build validation. Set the policy to Automatic and Required to validate added or changed PowerOns whenever a PR is created or updated.

This example uses symitar-dev explicitly. Set that group's symNumber to the intended validation SYM. If branches need different environments, configure a validation pipeline and group for each policy. Do not select groups with a template expression using System.PullRequest.TargetBranch: that variable is unavailable in templates.

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

# Use an explicit validation SYM and credentials for this branch-policy pipeline.
variables:
  - 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@2
  displayName: 'Validate changed PowerOn files'
  inputs:
    apiKey: $(apiKey)
    symitarHostname: $(symitarHostname)
    sshPort: $(sshPort)
    sshHostKey: $(sshHostKey)
    symNumber: $(symNumber)
    sshUsername: $(sshUsername)
    sshPassword: $(sshPassword)
    symitarUserNumber: $(symitarUserNumber)
    symitarUserPassword: $(symitarUserPassword)
    preserveServerFiles: RD.*,PFR.*

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

Outside a PR, validation compares the checked-out source bytes with the selected SYM using SFTP checksums. It does not compare against the most recently merged PR.

Prepare an Artifact

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

YAML
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 explicit symNumber supplied by the selected variable group
- task: ValidatePowerOn@2
  displayName: 'Validate changed PowerOn files'
  inputs:
    apiKey: $(apiKey)
    symitarHostname: $(symitarHostname)
    sshPort: $(sshPort)
    sshHostKey: $(sshHostKey)
    symNumber: $(symNumber)
    sshUsername: $(sshUsername)
    sshPassword: $(sshPassword)
    symitarUserNumber: $(symitarUserNumber)
    symitarUserPassword: $(symitarUserPassword)
    preserveServerFiles: RD.*,PFR.*

- script: git archive --format=zip --output="$(Build.ArtifactStagingDirectory)/output.zip" HEAD
  displayName: 'Archive the exact tracked commit, including pipeline configuration'

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

Release

Deploy from the merge artifact in this release pipeline, not from the PR validation job. Configure Approvals and checks on the Azure DevOps Stage and Prod environments for the deployment jobs; the YAML environment name alone does not create approval requirements. The validation stages produce the preview first; an approver can then review those logs before allowing the corresponding deployment.

The example uses mirror, which can delete server-only files outside the preserved scope. Change both the preview and deployment to push when deletion is not intended. Both compare the artifact against the current host, not just the files in the last PR. A later deployment recomputes its plan; a dry run does not freeze the destination.

Each job downloads the selected build artifact and extracts it to $(System.ArtifactsDirectory)/repo, matching artifactPath: repo. Keep the same artifact run through preview and deployment.

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.

YAML
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:
      - job: ValidateStageSynchronization
        displayName: 'Validate PowerOn Synchronization in Stage'
        steps:
          - download: build
            artifact: output

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

          - task: SynchronizeDirectory@2
            displayName: 'Synchronize PowerOns to Stage (Dry Run)'
            inputs:
              directoryType: powerOns
              syncMode: mirror
              isDryRun: true
              artifactPath: 'repo'
              symitarHostname: $(symitarHostname)
              sshPort: $(sshPort)
              sshHostKey: $(sshHostKey)
              symNumber: $(symNumber)
              sshUsername: $(sshUsername)
              sshPassword: $(sshPassword)
              symitarUserNumber: $(symitarUserNumber)
              symitarUserPassword: $(symitarUserPassword)
              apiKey: $(apiKey)
              preserveServerFiles: RD.*,PFR.*

  - 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: '$(System.ArtifactsDirectory)/repo'

                - task: SynchronizeDirectory@2
                  displayName: 'Synchronize PowerOns to Stage'
                  inputs:
                    directoryType: powerOns
                    syncMode: mirror
                    isDryRun: false
                    artifactPath: 'repo'
                    symitarHostname: $(symitarHostname)
                    sshPort: $(sshPort)
                    sshHostKey: $(sshHostKey)
                    symNumber: $(symNumber)
                    sshUsername: $(sshUsername)
                    sshPassword: $(sshPassword)
                    symitarUserNumber: $(symitarUserNumber)
                    symitarUserPassword: $(symitarUserPassword)
                    apiKey: $(apiKey)
                    preserveServerFiles: RD.*,PFR.*

  # 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:
      - job: ValidateSynchronization
        displayName: 'Validate PowerOn Synchronization'
        steps:
          - download: build
            artifact: output

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

          - task: SynchronizeDirectory@2
            displayName: 'Synchronize PowerOns (Dry Run)'
            inputs:
              directoryType: powerOns
              syncMode: mirror
              isDryRun: true
              artifactPath: 'repo'
              symitarHostname: $(symitarHostname)
              sshPort: $(sshPort)
              sshHostKey: $(sshHostKey)
              symNumber: $(symNumber)
              sshUsername: $(sshUsername)
              sshPassword: $(sshPassword)
              symitarUserNumber: $(symitarUserNumber)
              symitarUserPassword: $(symitarUserPassword)
              apiKey: $(apiKey)
              preserveServerFiles: RD.*,PFR.*

  - 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: '$(System.ArtifactsDirectory)/repo'

                - task: SynchronizeDirectory@2
                  displayName: 'Synchronize PowerOns to Prod'
                  inputs:
                    directoryType: powerOns
                    syncMode: mirror
                    isDryRun: false
                    artifactPath: 'repo'
                    symitarHostname: $(symitarHostname)
                    sshPort: $(sshPort)
                    sshHostKey: $(sshHostKey)
                    symNumber: $(symNumber)
                    sshUsername: $(sshUsername)
                    sshPassword: $(sshPassword)
                    symitarUserNumber: $(symitarUserNumber)
                    symitarUserPassword: $(symitarUserPassword)
                    apiKey: $(apiKey)
                    preserveServerFiles: RD.*,PFR.*

Pull Server-Managed Files

This workflow pulls only files listed in preserveServerFiles, commits them to a reusable branch, and opens or updates an Azure Repos pull request. Use this when Symitar generates or rewrites files that should be reviewed before landing back in your repository.

YAML
trigger: none

pool:
  name: ci-symitar

variables:
  - group: symitar-prod

steps:
- checkout: self
  fetchDepth: 0
  persistCredentials: true

- task: SynchronizeDirectory@2
  displayName: 'Pull server-managed PowerOns'
  env:
    SYSTEM_ARTIFACTSDIRECTORY: $(Build.SourcesDirectory)
  inputs:
    directoryType: powerOns
    syncMode: pull
    isDryRun: false
    artifactPath: .
    repositoryPath: $(Build.SourcesDirectory)
    symitarHostname: $(symitarHostname)
    sshPort: $(sshPort)
    sshHostKey: $(sshHostKey)
    symNumber: $(symNumber)
    sshUsername: $(sshUsername)
    sshPassword: $(sshPassword)
    symitarUserNumber: $(symitarUserNumber)
    symitarUserPassword: $(symitarUserPassword)
    apiKey: $(apiKey)
    preserveServerFiles: RD.*,PFR.*
    pullPreservedOnly: true
    createPullRequest: true
    azureDevOpsAccessToken: $(System.AccessToken)
    pullRequestBranch: chore/symitar-pull
    pullRequestTargetBranch: main
    pullRequestTitle: 'chore: sync server-managed Symitar files'

The pull task resolves artifactPath: . against the checkout via the explicit SYSTEM_ARTIFACTSDIRECTORY environment override, allowing it to load the repository configuration. Pulled changes are written to repositoryPath and submitted using the pipeline Build Service identity. Configure the required Git permissions; do not grant policy bypass to make a rejected push succeed.

Preview Dependent Reinstalls

To include unchanged parents affected by an uploaded include, add reinstallDependentPowerOns: true to both SynchronizeDirectory steps for an environment: its dry-run preview and its actual deployment. The release artifact must contain the complete source trees for parents in installPowerOns.

YAML
# Additional inputs on the existing release synchronization tasks
reinstallDependentPowerOns: true

This is off by default. The preview names each affected parent and its direct or nested dependency path, explicitly distinguishing WOULD REINSTALL from WOULD UPLOAD. See dependent reinstalls for exclusions, failure behavior, and output counts.