How to keep version numbers in sync across many files in a project?

[blackears]

🏷️ Discussion Type

Question

Body

I have a project that has several different text and script files that need to be updated to the project's version number before I release (https://github.com/blackears/cyclopsLevelBuilder). Some of this is having some Github action workflows that need to have the right version number to run, and also two .cfg configuration files that need to be updated.

What's a good way to go about this? I'd like to have an automated solution so I make sure I don't overlook anything. What's a good way to do this? I've been reading some articles on having a "source of authority", but most of those only affect versioning within the code base itself and doesn't take into account the config files and support scripts.

Guidelines

• I have read and understood this category's guidelines before making this post.

[kittimzhe]

Hi @blackears 👋

The principle is a single source of truth (as the earlier reply said), but let me make it concrete for your exact setup — version in GitHub Actions workflows + two .cfg files + script files.

1. For GitHub Actions — don't store the version in the workflow at all. Trigger releases from a git tag and read the version from the tag, so the workflow never needs editing per release:

on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Read version from tag
        run: echo "VERSION=${GITHUB_REF_NAME#v}" >> "$GITHUB_ENV"

Then reference ${{ env.VERSION }} (or ${{ github.ref_name }}) anywhere a step needs the number. Tag v1.2.3 → version 1.2.3.

2. For the .cfg and script files, keep one canonical VERSION file and rewrite the rest with a small script. Example VERSION:

1.2.3

scripts/sync_version.sh (run as part of tagging):

#!/usr/bin/env bash
set -euo pipefail
VER="$(cat VERSION)"

# update the .cfg files (adjust the pattern to your real format)
sed -i -E "s/^(version\s*=\s*).*/\1${VER}/" path/to/one.cfg
sed -i -E "s/^(version\s*=\s*).*/\1${VER}/" path/to/two.cfg
# any other file carrying the version
sed -i -E "s/@@VERSION@@/${VER}/g" scripts/any_script.py

git add -A
git commit -m "chore: bump to ${VER}" || true
git tag "v${VER}"

3. Release with one command so a file can't be overlooked:

# edit VERSION, then:
./scripts/sync_version.sh && git push origin "v$(cat VERSION)"

4. Add a CI guard that fails if any file still holds a stale version — this is what actually prevents forgetting:

- name: Check versions are in sync
  run: |
    VER="${GITHUB_REF_NAME#v}"
    grep -q "version = ${VER}" path/to/one.cfg
    grep -q "version = ${VER}" path/to/two.cfg

If you also want to automate which version comes next, setuptools-scm (Python) or release-it/commitizen can derive it from tags — but the
source-of-truth + sync-script + CI-guard pattern above is the core and works regardless of the tool.

Happy to tailor the sed patterns if you share the exact format of your two .cfg files 👍