[fivetran-paulharper]

Summary

The version file used to hold a full image tag, such as 1.2.9-ubuntu-26.04 or 1.2.9-windows-ltsc2022. That made rollbacks awkward: a user had to know the tag suffix for their container mode, and on Linux a bare 1.2.9 silently selected the legacy numeric tag instead of the Ubuntu one. This came up while reviewing the Docker rollback steps in the public docs (fivetran/engineering#286828).

The version file now holds the plain agent version (for example 1.2.9). The management scripts append the image tag suffix for the detected container mode when they start the container:

• Linux containers: <version>-ubuntu-26.04
• Windows containers: <version>-windows-<ltsc>

Changes

• install.sh and install.ps1 write the plain version to the version file, and the registry lookups return plain versions.
• proxy-agent-manager.sh and proxy-agent-manager.ps1 build the image tag from the pinned version at start and upgrade time. Legacy full tags in the version file are still accepted and rewritten to the plain version on the next start, restart, or upgrade. Invalid content fails with Invalid proxy agent version '<x>' in <file>. Expected <major>.<minor>.<patch>.
• The -WindowsVersion override is persisted as $WINDOWS_VERSION in settings.ps1 instead of in the pinned tag. A variant pinned by a legacy Windows tag is migrated there on first run. A legacy Windows tag under Linux containers still errors, as before.
• Get-ImageTagType, Get-ImageTagVariant, and Resolve-ImageTag are removed from proxy-agent-manager.ps1, along with the "switch to explicit Ubuntu tag" branch in upgrade, since a plain version now covers both cases.
• README updated to describe the version file as the pinned agent version and to note where the Windows override is stored.

Compatibility

Installs running the previous management scripts handle a plain version already: the bare numeric tag is the same Linux image as the Ubuntu tag, and proxy-agent-manager.ps1 already appended the LTSC suffix for Windows containers. So the docs can tell users to roll back with echo "1.2.7" > version regardless of which manager version they have.

Testing

• shellcheck and bash -n pass on both shell scripts.
• Smoke-tested proxy-agent-manager.sh with stubbed docker and curl: a legacy 1.2.9-ubuntu-26.04 pin starts 1.2.9-ubuntu-26.04 and rewrites the file to 1.2.9; upgrade picks 1.2.10 and ignores bare and Windows tags in the registry listing; a second upgrade is a no-op; echo 1.2.7 > version followed by start runs 1.2.7-ubuntu-26.04; 2.0 fails with the validation error.
• proxy-agent-manager.ps1 and install.ps1 are not tested yet. There is no PowerShell on the machine this was written on, so start and upgrade need a run on a Windows host before merge.

🤖 Generated with Claude Code

---

Stack

• main
  • Add CI with unit and integration tests for the install and management scripts #13
    • Pin the plain agent version in the version file #12 👈
    • feat(windows): honor HTTPS_PROXY, HTTP_PROXY and NO_PROXY in PowerShell scripts #14
    • Add a doctor command to the management scripts #16

[GiovanniMoya]

proxy-agent-manager.sh:204 and proxy-agent-manager.ps1:399 parse the version file before command dispatch, so a malformed non-empty version prevents stop, status, and logs from running. Defer parsing to commands that need the version.

[Copilot]

🟡 Changes recommended

The migration can corrupt settings without a trailing newline or lose the pinned variant, and accepted uppercase WindowsVersion values produce Docker tags that fail installation.

2 open issues

• Lowercase the Windows version before constructing Docker tags · New
• Insert a newline before appending migrated settings · New

What changed in this PR

This PR simplifies agent rollbacks by pinning a plain version in the version file and letting the management scripts select the image suffix for the container mode.

Changes:

• Return and store plain versions while migrating legacy image tags.
• Persist Windows LTSC overrides in settings.ps1.
• Update documentation and tests for exact version pins, migration, and rollback behavior.

File	Description
tests/​pwsh/​Manager.Tests.ps1	Covers plain pins, legacy migration, and Windows overrides.
tests/​pwsh/​Install.Tests.ps1	Checks plain versions and persisted Windows overrides.
tests/​integration/​windows.ps1	Verifies exact pins, legacy migration, and override persistence.
tests/​integration/​linux.sh	Verifies suffixed images and plain version migration.
tests/​bash/​manager.bats	Adds migration checks and exact version assertions.
README.md	Documents plain pins and Windows override storage.
proxy-agent-manager.sh	Normalizes pins and appends the Ubuntu image suffix.
proxy-agent-manager.ps1	Resolves image suffixes and migrates legacy Windows variants.
install.sh	Extracts plain versions from Ubuntu registry tags.
install.ps1	Stores plain versions and Windows overrides separately.

_{Review effort: Balanced}

[fivetran-paulharper]

@GiovanniMoya Thanks for catching this. Fixed in ce69b35: both managers now parse and validate the pinned version only for start, restart, and upgrade. I added regression tests showing stop, status, and logs still work with a malformed non-empty version file. The Bash and PowerShell unit tests are passing in CI.