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.
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
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.
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.
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.
# 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.