Version Updates

Backstage Version Updates

This guide covers the process of updating Backstage target and minimum versions for your plugins in the overlay repository.

---

Version Concepts

Target Backstage Version

The version of Backstage that the target platform is built on. Defined in versions.json:

{
  "backstage": "1.45.3",
  "node": "22.19.0",
  "cli": "1.9.1",
  "cliPackage": "@red-hat-developer-hub/cli"
}

Supported Versions (in metadata)

The Backstage version your plugin is compatible with:

spec:
  backstage:
    supportedVersions: 1.42.5  # Plugin was built/tested against this version

Source Backstage Version

The Backstage version the source repository uses:

{
  "repo-backstage-version": "1.45.0"
}

---

Version Compatibility Rules

Rule 1: Source ≤ Target

Your plugin's source Backstage version should be less than or equal to the target:

source repo-backstage-version ≤ versions.json backstage
            1.45.0            ≤      1.45.3     ✅

Rule 2: Best-Effort Matching

The automation performs best-effort version matching:

Scenario	Result
Exact match available	✅ Used directly
Older version available	⚠️ Used with warning
Newer only available	❌ Blocked

Warning: Best-effort matches require additional testing. A bot comment will appear on PRs with version mismatches.

---

When to Update

Rather than following a fixed calendar cadence, update when concrete signals indicate it is needed:

• The Backstage Compatibility Report shows your workspace as incompatible
• A new platform release branch is being created and your plugin blocks it
• Automated discovery PRs fail the compatibility check for your workspace
• Upstream has released a version built against the current target Backstage version
• Security advisories affect your plugin's dependencies

When any of these signals appear:

1. Check the target Backstage version in versions.json
2. Find a compatible plugin release
3. Update source.json:repo-ref and repo-backstage-version
4. Update metadata/*.yaml:spec.version and spec.backstage.supportedVersions
5. Test with /publish and /smoketest

---

Step-by-Step Update Process

Step 1: Check Current Target Version

cat versions.json | jq '.backstage'
# "1.45.3"

Step 2: Find Compatible Plugin Version

# For community-plugins, list available versions
git ls-remote --tags https://github.com/backstage/community-plugins \
  | grep "@backstage-community/plugin-your-plugin@" \
  | tail -10

For Backstage core plugins, check the Backstage releases.

Step 3: Verify Backstage Version in Plugin Release

# Check what Backstage version the plugin release uses
curl -s "https://raw.githubusercontent.com/backstage/community-plugins/@backstage-community/plugin-your-plugin@1.2.3/workspaces/your-workspace/backstage.json" | jq '.version'

Step 4: Update source.json

{
  "repo": "https://github.com/backstage/community-plugins",
  "repo-ref": "@backstage-community/plugin-your-plugin@1.2.3",
  "repo-flat": false,
  "repo-backstage-version": "1.45.0"
}

Step 5: Update Metadata Files

For each file in metadata/*.yaml:

spec:
  version: 1.2.3                    # Match new plugin version
  backstage:
    supportedVersions: 1.45.0       # Match source Backstage version

Step 6: Verify and Test

# Create PR and trigger build
git checkout -b update-your-plugin-version
git add .
git commit -m "chore: update your-plugin to 1.2.3 (Backstage 1.45.0)"
git push origin update-your-plugin-version

# Open PR, then comment:
# /publish
# /smoketest
# or: /smoketest pr-4929-90eff067

/smoketest <tag> resolves to quay.io/rhdh-community/rhdh:<tag> for the smoke-test run. Allowed tags include pr-4907, pr-4929-90eff067, next, next-1.10-244a2755, and next-8a0d43e7.

---

Handling Breaking Backstage Updates

When the target Backstage version introduces breaking changes that affect your plugin:

1. Check if upstream has already released a compatible version of your plugin
2. If a compatible version exists, update source.json:repo-ref to that version
3. If no compatible version exists yet:
   • Request or contribute a fix upstream
   • As a temporary measure, create a patch to restore compatibility (see 06 - Patch Management)
4. Test with /publish and /smoketest before merging
5. Document any migration notes or known limitations in the PR description

---

Overriding Backstage Compatibility via PR Command

When a workspace's source Backstage version (source.json:repo-backstage-version) differs from the target version (versions.json:backstage), you can use the /override-backstage PR command instead of manually creating files.

What It Does

The command atomically:

1. Creates (or updates) backstage.json in the workspace with the target Backstage version
2. Rewrites all metadata/*.yaml OCI tags from bs_<old>__ to bs_<target>__
3. Commits both changes to the PR branch

Usage

Comment on your workspace PR:

/override-backstage

When to Use

• After the daily automation creates a PR with a plugin whose source Backstage version is older than the target
• After manually adding a workspace with a version mismatch
• When /publish fails with metadata validation errors about OCI tag mismatches

Example

Before	After
No backstage.json	backstage.json with {"version": "1.49.4"}
dynamicArtifact: oci://...:bs_1.48.3__7.0.1!...	dynamicArtifact: oci://...:bs_1.49.4__7.0.1!...

Note: Metadata files with local paths (e.g., ./dynamic-plugins/dist/...) are left unchanged.

---

Version Fields Reference

versions.json (Repository-Wide)

{
  "backstage": "1.45.3",        // Target Backstage version for all plugins
  "node": "22.19.0",            // Node.js version for builds
  "cli": "1.9.1",               // CLI tool version
  "cliPackage": "@red-hat-developer-hub/cli"  // CLI package name
}

source.json (Per Workspace)

{
  "repo": "https://github.com/backstage/community-plugins",
  "repo-ref": "@backstage-community/plugin-x@1.2.3",  // Exact version tag
  "repo-flat": false,
  "repo-backstage-version": "1.45.0"  // Backstage version at this ref
}

metadata/*.yaml (Per Plugin)

spec:
  version: 1.2.3                    # Plugin version (must match source)
  backstage:
    role: backend-plugin            # Plugin role
    supportedVersions: 1.45.0       # Backstage version compatibility

---

Automated Version Updates

Daily Workflow (main branch only)

The update-plugins-repo-refs.yaml workflow runs daily on the main branch only and:

1. Enumerates plugin package names from all existing workspaces in the overlay repository (by scanning each workspace's source repo tree)
2. Queries npm (npm view) for published versions of each discovered package
3. Checks Backstage version compatibility against the target version
4. Additionally runs npm search to discover new plugins under auto-discovery scopes
5. Creates/updates PRs with version bumps

This means all existing workspaces are updated regardless of their npm scope — including third-party plugins like @immobiliarelabs/, @pagerduty/, or @dynatrace/. What the overlay-first approach avoids is the regexp-based npm search step for package name discovery; actual version data still comes from npm.

Note: Release branches (release-x.y) do not have a scheduled automatic update. Updates to release branches must be triggered manually (see below).

Manual Trigger

To update a specific existing workspace (works for any scope — preferred for updates):

gh workflow run update-plugins-repo-refs.yaml \
  -f workspace-path="workspaces/your-workspace" \
  -f single-branch="main"

To add a new workspace via npm discovery (see Trigger Workflow Manually for details on quoting):

gh workflow run update-plugins-repo-refs.yaml \
  -f regexps="'@backstage-community/plugin-your-plugin'" \
  -f single-branch="main" \
  -f allow-workspace-addition=true

---

Compatibility Check Badge

The repository displays a compatibility badge:

This badge shows whether mandatory plugins are compatible with the target version.

When Badge is Red

• Some mandatory plugins are incompatible
• Release branch creation is blocked
• Requires version updates or patches

---

Troubleshooting Version Issues

Error: "Backstage version X is higher than target Y"

Cause: Plugin requires newer Backstage than the target platform supports

Solutions:

1. Find an older plugin version compatible with target
2. Wait for the target platform to update its Backstage version
3. Create a patch to backport compatibility (advanced)

Error: "No compatible version found"

Cause: Plugin hasn't released a version for target Backstage

Solutions:

1. Request upstream release for target Backstage version
2. Use commit SHA instead of tag (less preferred)
3. Create a fork with backported changes (last resort)

Warning: "Best-effort version match"

Cause: Exact Backstage version match not available

Action:

1. Review the version gap
2. Test thoroughly for compatibility issues
3. Document any known limitations
4. PR will have a bot comment explaining risks

---

Release Branch Considerations

main Branch

• Tracks the next platform release
• Can accept new workspaces
• Should use latest compatible plugin versions

release-x.y Branches

• Track specific platform releases
• Only accept updates to existing workspaces
• Must maintain compatibility with that release's Backstage version
• No scheduled automatic updates — must be triggered manually

Updating Release Branches

Option 1: Trigger the workflow manually (preferred)

Use the workflow with workspace-path and single-branch to update a specific workspace on a release branch:

gh workflow run update-plugins-repo-refs.yaml \
  -f workspace-path="workspaces/your-workspace" \
  -f single-branch="release-1.6"

This will find the latest compatible version and create/update a PR against that release branch.

Option 2: Manual PR

For cases where you need full control over the version (e.g., pinning to a specific commit):

# Checkout release branch
git checkout release-1.6

# Update plugin version (use version compatible with release-1.6's Backstage)
# Edit source.json and metadata files

# Create PR against release branch
git checkout -b backport-plugin-update-1.6
git commit -m "chore: backport plugin-x update to release-1.6"
git push origin backport-plugin-update-1.6

---

Version Update Checklist

## Version Update Checklist - [Plugin Name] - [Date]

### Pre-Update
- [ ] Identified target Backstage version from versions.json
- [ ] Found compatible plugin release
- [ ] Verified plugin's Backstage version is ≤ target

### Updates
- [ ] Updated source.json:repo-ref
- [ ] Updated source.json:repo-backstage-version
- [ ] Updated all metadata/*.yaml:spec.version
- [ ] Updated all metadata/*.yaml:spec.backstage.supportedVersions
- [ ] Verified patches still apply (if any exist)

### Validation
- [ ] Created PR
- [ ] /publish completed successfully
- [ ] /smoketest passed
- [ ] Manual testing completed (if best-effort match)
- [ ] PR approved and merged

---

Next Steps

• 06 - Patch Management – When version updates require patches
• 03 - Plugin Owner Responsibilities – Full ownership guide