Skip to content

Use the Symitar Connector

Azure DevOps ValidatePowerOn / SynchronizeDirectory and GitHub Actions validate-poweron-action / synchronize-symitar-action use one Symitar connector through Symitar SDK 1.30.0 in v2.2. In v2.2, the Symitar connector uses SSH to reach the native API. Both the AIX/SSH account and the Symitar user credentials are required, including for configurations that previously selected HTTPS.

SSH is the transport supported by this release, not a permanent restriction of the Symitar connector. Future protocol support will need an explicit configuration and migration contract; retained legacy values must not silently change how an existing pipeline connects.

The connector is chosen before connection. An authentication or permission failure fails the task; it does not replay the operation through SSH/HTTPS alternatives.

Azure DevOps input GitHub Actions input Status in v2.2
connectionType connection-type Deprecated; no-op in v2.2. Omitted, blank, legacy, and arbitrary values all use the Symitar connector. Retain it in existing YAML if convenient; omit it in new configurations.
symitarAppPort symitar-app-port Deprecated; no-op in v2.2. Not required, parsed, or validated.
sshPort ssh-port Active; defaults to 22. Use the SSH port, not the former application-server port.
ValidatePowerOn.syncMethod Validate action sync-method Accepts sftp or rsync, but non-PR comparisons use SFTP checksums. Invalid values still fail.
SynchronizeDirectory.syncMethod Synchronize action sync-method Active transfer choice: sftp or rsync.

Examples below use Azure DevOps names unless labeled GitHub Actions. The corresponding synchronization settings are:

Azure DevOps GitHub Actions
sshHostKey ssh-host-key
apiKey api-key
directoryType / syncMode directory-type / sync-mode
isDryRun / skipValidation dry-run / skip-validation
reinstallDependentPowerOns reinstall-dependent-powerons
Config installPowerOns Action input install-poweron-list
Config preserveServerFiles Action input preserve-server-files
pullPreservedOnly pull-preserved-only
createPullRequest / commitPulledChanges create-pull-request / commit-pulled-changes
filesInstalled / filesReinstalled outputs files-installed / files-reinstalled outputs

Retaining old field names avoids unnecessary YAML edits. It does not remove the requirement for working SSH and Symitar credentials, network access to sshPort, or host trust.

Configure Host Trust Once

The connector verifies the SSH server's identity before sending credentials. Use either:

  • A matching key already in the agent service account's ~/.ssh/known_hosts. The ssh-keygen command must be available to read this file, including hashed entries.
  • The sshHostKey input containing the base64 field of an administrator-approved SSH public key. This also works for fresh agents with no known_hosts file.

Obtain and verify the public key with the administrator responsible for the host. The input is not a private key, SHA256 fingerprint, or complete known_hosts line. For Azure DevOps, store the approved public value in a shared variable group and supply it to both tasks:

YAML
inputs:
  symitarHostname: $(symitarHostname)
  sshPort: $(sshPort)
  sshHostKey: $(sshHostKey)
  sshUsername: $(sshUsername)
  sshPassword: $(sshPassword)
  symitarUserNumber: $(symitarUserNumber)
  symitarUserPassword: $(symitarUserPassword)
  apiKey: $(apiKey)

For GitHub Actions, supply equivalent values under with:. Store passwords and the API key as secrets; the approved public key can be a repository or environment variable:

YAML
with:
  symitar-hostname: ${{ vars.SYMITAR_HOSTNAME }}
  sym-number: ${{ vars.SYM_NUMBER }}
  ssh-host-key: ${{ vars.SYMITAR_SSH_HOST_KEY }}
  ssh-username: ${{ secrets.SSH_USERNAME }}
  ssh-password: ${{ secrets.SSH_PASSWORD }}
  symitar-user-number: ${{ secrets.SYMITAR_USER_NUMBER }}
  symitar-user-password: ${{ secrets.SYMITAR_USER_PASSWORD }}
  api-key: ${{ secrets.API_KEY }}

There is no interactive yes prompt, automatic key acceptance, or write to known_hosts. Unknown, unreadable, or changed trust fails the task and is surfaced in its logs. Review a host-key rotation with the administrator before updating the trusted value.

apiKey remains required for real client pipelines. An organization ID alone is not a replacement; simulated licensing in Libum's test harness does not change the released integrations' authentication requirements.

Check Rsync Agent Prerequisites

SFTP is the default and does not require rsync tooling. If you retain syncMethod: rsync, install rsync and sshpass on the agent. On Windows, those tools must be available inside WSL along with Bash and setsid; the Windows workspace must be on a local drive accessible through WSL.

setsid starts the Windows/WSL transfer in its own process group. This lets cancellation or timeout stop rsync and its SSH child processes before recovery starts. It is part of the hardened rsync runner; default SFTP does not require it.

Check WSL under the same Windows account that runs the agent service, not just your interactive desktop account. This credential-free command should return promptly:

powershell
wsl --exec bash -c 'echo ready; command -v bash setsid rsync sshpass'

Confirm ready and a path for each tool. If it hangs or a tool is missing, repair the agent environment before running a live transfer. Do not repeatedly retry host authentication to diagnose WSL startup. A synchronization dry run uses SFTP planning and does not exercise rsync; verify an actual transfer with dedicated test files before rollout.

Understand Byte Verification and Rollback

Synchronization compares original bytes, so same-size edits and line-ending-only differences are detected. Transfers preserve CRLF, LF, binary data, and original encodings. Both transfer methods use SFTP for checksum planning, snapshots, and final verification; rsync remains a supported method for the planned transfers. Checksumming can read more data than a size-only comparison.

For an actual synchronization, the task captures the selected destination files, verifies that they have not changed before mutation, applies the plan, and checks the resulting bytes. Failures trigger compensating rollback and verification. This is not an atomic transaction: a failed rollback reports an unknown destination state that requires operator investigation. Do not automatically retry it.

Byte equality covers synchronized files and restored source files. Rebuilding a restored PowerOn verifies installation health and membership; it does not guarantee identical generated binaries or timestamps. Concurrent external writers can change files after verification. Use a controlled window for mirror operations on shared directories.

Validation also uses saved source bytes. Prepare PowerOn source and includes with LF endings through .gitattributes; the task does not normalize files during deployment. Review any repository normalization separately, and keep binary files out of text-normalization rules.

Review Dependent Reinstalls

The optional reinstallDependentPowerOns task input defaults to false. Enable it on both the release preview and deployment tasks when you want an uploaded include to trigger installation of its affected parents:

YAML
inputs:
  directoryType: powerOns
  syncMode: push
  isDryRun: true
  reinstallDependentPowerOns: true

This fragment supplements the normal artifact and connection inputs. In Azure DevOps, eligible parents must be explicitly listed in the artifact's .poweron-pipelines/config.yml:

YAML
installPowerOns:
  - ACCOUNT.PO

For the GitHub synchronization action, supply the equivalent settings directly as action inputs:

YAML
with:
  directory-type: powerOns
  sync-mode: push
  dry-run: true
  reinstall-dependent-powerons: true
  install-poweron-list: ACCOUNT.PO

If ACCOUNT.PO includes COMMON.PRO, which includes CONSTANTS.DEF, deploying changed bytes for CONSTANTS.DEF makes ACCOUNT.PO an installation candidate even if its own source is unchanged. Only listed, unpreserved parents are considered; pull and non-PowerOn tasks do not install anything.

Dry-run logs distinguish these actions:

Plain text
WOULD UPLOAD CONSTANTS.DEF — content changed or missing on host
WOULD REINSTALL ACCOUNT.PO — source unchanged; no upload; changed include: ACCOUNT.PO -> COMMON.PRO -> CONSTANTS.DEF
Dry-run plan: 1 uploads, 1 unchanged-parent reinstalls, 0 other installs, 0 deletions

An unchanged parent that is not installed yet is labeled WOULD INSTALL. Each parent is listed and installed once; filesReinstalled counts unchanged, previously installed parents and is included in filesInstalled.

The artifact must contain every eligible parent's complete include tree with exact filename casing. Missing or ambiguous files, cycles, and deletion of a still-referenced include fail before deployment. Preserved dependencies must match the artifact's bytes. Includes inside comments are considered because PowerOn still looks them up; # INCLUDE disables that directive. Parents outside the install list are not discovered automatically.

Actual runs transfer and verify the dependency bytes before installing parents. Installation still compiles the parent even if skipValidation is enabled. Recovery restores changed includes before rebuilding previously installed parents and removes newly installed parents. Concurrent changes to untouched parents/includes block recovery rather than being overwritten.

Keep Deployment in the Release Pipeline

Keep the existing lifecycle: feature branch → PR validation → merge → versioned artifact → release preview → approval → deployment. PR validation does not deploy the release. A release may contain several merged PRs.

The release compares the selected artifact with the current host. “Changed” means byte-different from the host, not “touched in the latest PR.” A dry run previews the current comparison; a later deployment recomputes and verifies its own plan. It does not freeze the earlier preview.

Use push when server-only files must remain. Use mirror only when deletions within the selected scope are intended, with appropriate preservation patterns. For Azure DevOps, extract the artifact to the path that artifactPath resolves to; see release examples. For GitHub Actions, download the chosen build artifact into the checkout workspace and point local-directory-path at its directory. Both should deploy the reviewed artifact rather than silently rebuilding different source.

Preserve Legacy Files While Managing a Prefix

In v2.2, ordered negation supports preserveServerFiles: '*,!CUSTOM.*': preserve all files, then allow normal pipeline operations for CUSTOM.*. Positive-only lists keep their behavior. Review older patterns starting with !, which now mean negation.

Use push to retain server-only files. Mirror can delete server-only files within the allowed prefix. With pullPreservedOnly: true, pull downloads the preserved legacy group instead. See the complete example and mode comparison.

Pull Preserved Files Back for Review

Use ordered preserveServerFiles patterns and pullPreservedOnly: true to capture server-managed changes. For example, RD.*,!RD.CUSTOM.PO preserves RD.* except the named customization. A preserved-only pull with no patterns transfers nothing.

createPullRequest and commitPulledChanges are mutually exclusive and apply only to pull. A dry run does not commit, push, or create a PR. Use PR creation for protected branches instead of granting policy bypass.

For Azure DevOps, the pipeline's Build Service identity, not the person queuing the run, needs repository Read, Contribute, Create branch, and Contribute to pull requests. Reusing a PR branch also needs Force push for that branch because updates use --force-with-lease; scope it to the generated branch. Preserve checkout credentials and provide System.AccessToken to the task. The pull example includes these inputs.

For GitHub Actions, grant the workflow contents: write to push the generated branch and pull-requests: write to open the PR. Supply github-token: ${{ secrets.GITHUB_TOKEN }} and retain checkout credentials. Check out the intended target branch before pulling, and configure pull-request-target-branch explicitly for tag/PR-triggered runs. Repository policies must permit the generated branch and PR; do not bypass protections on the target branch.

Roll Out to Existing Pipelines

  1. Confirm SSH/Symitar credentials, the target SYM, and agent-account host trust before updating the extension or pinned action version.
  2. For Azure DevOps, review the task reference and use ValidatePowerOn@2 / SynchronizeDirectory@2. For GitHub Actions, review each action README and pin the published v2.2.0 tag or its immutable commit once available.
  3. Preview a known artifact with isDryRun: true (GitHub: dry-run: true), checking uploads, deletions, and installation candidates.
  4. Leave dependent reinstalls disabled unless the install list and complete source trees are ready. Enable it in preview first.
  5. Exercise the release on a test SYM with representative source bytes and permissions before client rollout.

The known limitations describe the remaining boundaries. A successful dry run proves planning, not successful future transfers, compilation, or rollback.