rancher-system-agent is a daemon designed to run on a system and apply "plans" to the system. rancher-system-agent can support both local and remote plans, and was built to be integrated with the Rancher2 project for provisioning next-generation, CAPI driven clusters.
mainis the primary development branch and always contains the latest changes.- Tags from
mainare consumed by Rancher'smainbranch. - Each Rancher release line has a corresponding
release/vX.Ybranch, created frommain. - Release branches only receive bug fixes and security patches.
- Release branch tags increment only the patch suffix (
.x). - Release candidates (RCs) may also be created from release branches before a stable release.
- Release candidates (RCs) tag format is
vX.Y.Z-rc.MwhereMis incremented for each new RC.
Starting with releases after v0.3.16, system-agent minor versions are aligned with Rancher minor release lines:
| System-agent Branch | Rancher Release Line | Tag Format |
|---|---|---|
main |
main |
vX.Y.Z |
release/v2.15 |
v2.15 |
v0.15.x |
release/v2.14 |
v2.14 |
v0.14.x |
release/v2.13 |
v2.13 |
v0.13.x |
Note: The v0.3.x release line uses the legacy versioning scheme and is not aligned with Rancher release lines. v0.3.16 is the final release in that series.
When you create a new release/vX.Y branch, update these files on main:
| File | Change |
|---|---|
.github/workflows/daily-rc-tag.yaml |
Add the branch and its v0.<minor>. base pattern to the matrix. |
.github/workflows/bump-rancher-image-scheduled.yaml |
Add the branch to the matrix. Add it only if the branch has the integration tests. |
.github/renovate.json |
Add the branch to baseBranchPatterns and add a packageRules entry. |
| This README | Add the branch to the tables above. |
Schedules run only from the default branch, so do not copy the scheduled workflows to a release branch.
Also update the RANCHER_IMAGE and CATTLE_AGENT_IMAGE tags in .github/workflows/integration-tests.yaml,
scripts/integration-tests and scripts/fetch-provisioning-tests on the new branch to its Rancher line (for example v2.17-<sha>-head).
The bump workflow keeps the Rancher line of the current tag, and it does not change the line.
make
You can also
CROSS=true make if you want cross-compiled binaries for Darwin/Windows.
Release candidates are tagged automatically once per day when a configured branch has changed since its latest tag:
| Branch | Tag series |
|---|---|
main |
v0.16.N-rc.M |
release/v2.15 |
v0.15.N-rc.M |
release/v2.14 |
v0.14.N-rc.M |
release/v2.13 |
v0.13.N-rc.M |
Stable tags are created manually. When the next base version is ready, update
the corresponding base pattern in .github/workflows/daily-rc-tag.yaml; the
workflow then increments the patch number and continues the new -rc.M
series. A pushed tag runs the release
workflow, which publishes the images and release binaries and dispatches the
matching Rancher branch's System Agent upgrade workflow.
First, configure the agent by looking at the examples/configuration folder, then you can run the binary.
./bin/rancher-system-agent
Copyright (c) 2026 Rancher Labs, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.