Expose target=human-readable to Github Action workflow or provide verbose flag

[matthiashermsen]

What is this feature about?

It would be great to see some optional debug information when running the workflow. In some validated environments I've seen workflow steps similiar to this one

          - name: Validate next version
            if: ${{ steps.get_next_version.outputs.hasNextVersion == 'true' }}
            run: |
              NEXT_VERSION="${{ steps.get_next_version.outputs.version }}"
              LATEST_VERSION=$(git tag --list \
                | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' \
                | sort -V \
                | tail -n 1)

              echo "Latest release tag: $LATEST_VERSION"
              echo "Next version:       $NEXT_VERSION"

              if git rev-parse "refs/tags/$NEXT_VERSION" >/dev/null 2>&1; then
                echo "::error::Version $NEXT_VERSION already exists as a Git tag."
                exit 1
              fi

              if [ -n "$LATEST_VERSION" ] && \
                [ "$(printf '%s\n' "$LATEST_VERSION" "$NEXT_VERSION" | sort -V | head -n 1)" != "$LATEST_VERSION" ]; then
                echo "::error::Next version $NEXT_VERSION is not greater than latest release $LATEST_VERSION."
                exit 1
              fi

              echo "Version $NEXT_VERSION is valid."

which basically only ensures that this action is working correctly... It feels redundant and could be omitted by adding a verbose flag or having some human readable output.

Using the CLI one can use target=human-readable but the Github Action only writes to the Github Actions output stream.

What do you think about this feature?

What needs to be done to implement this feature?

• Update GitHub Action to accept a verbose flag printing some result information.

with:
  # e.g.
  verbose: true #defaults to false

What else should we know?

One could simply add a repository secret ACTIONS_STEP_DEBUG with the value true to see the expected output

##[debug]Docker Action run completed with exit code 0
##[debug]Set output version = 1.2.3
##[debug]Set output hasNextVersion = true
##[debug]Finishing: Get next version

but now every step is running in debug mode.

[goloroden]

Hi @matthiashermsen 👋

Thanks a lot for this – we took a close look at it, and it turned out to be a more interesting issue than it appears at first sight. Let us share what we found.

First: target=human-readable doesn't exist 🙈

You wrote that one can use target=human-readable from the CLI. That's not the case – the only valid targets are github-action, json and version, and the default (version) prints nothing but the bare version string:

$ get-next-version
2.7.7

This is our fault: the README claims "By default, output will be printed to the console in a human-readable format", which has been wrong since 2022. We'll fix that regardless of what we decide here.

What we think you actually want

Reading your issue again, the key sentence for us is:

It feels redundant and could be omitted

You don't primarily want more output – you want to delete that step. That's a question of trust in the result, not of visibility. And this is exactly why we believe a verbose flag would not actually solve your problem: logging doesn't assert anything. You'd end up keeping the validation step and having more noise in your logs.

Your validation step is not redundant

This is the part we'd like to push back on, because we think it matters for you either way. get-next-version calculates the next version relative to the last release reachable from HEAD – not relative to the latest release of the project. Those two coincide as long as you release linearly from one branch, which is why nobody notices. When they diverge, you get this:

git commit -m "chore: Initial" && git tag 1.0.0
git commit -m "fix: A"         && git tag 1.0.1
git commit -m "feat: B"        && git tag 1.1.0
git checkout -b feature 1.0.0
git commit -m "fix: C"

$ get-next-version
1.0.1     # already exists as a tag, and is lower than 1.1.0

That's your check firing, and rightly so. It is not tautological.

Conversely, here's a case your step does not catch – a full clone without tags:

$ get-next-version
1.0.0     # instead of 2.7.8

Since no tags are present, your LATEST_VERSION is empty, the comparison is skipped, and git rev-parse refs/tags/1.0.0 fails – so both checks pass and the wrong version goes through silently.

So the honest summary is: your step guards against something real, and it has a blind spot. Neither of those gets better with a verbose flag. What both cases have in common is that we silently pick a base version and never tell you which one.

What we'd rather build

Effort is not the deciding factor for us here – we'd rather build the right thing than the cheap thing. These are the directions we're considering, and we'd value your opinion on them:

1. Make the base version explicit. Something like --base=reachable|highest. With highest, the next version is computed against the highest release tag in the repository, which makes "the version went backwards" structurally impossible rather than merely detectable. This addresses the root cause instead of its symptoms. The trade-off: for maintenance branches, reachable is the correct semantics, so this has to stay a choice.

2. Let the tool assert the result (--strict). This is your shell block, implemented once, in Go, with tests, instead of copy-pasted into every repository: fail with a clear message if the computed version is not greater than every existing tag. Opt-in, because backport workflows are legitimate.

3. Warn when we're unsure. Not general verbosity, but a warning in exactly the two cases where the result can surprise you: no semver tags found at all, and the base tag we picked is not the highest tag in the repository. As a ::warning:: annotation when running as a GitHub Action, so it surfaces in the run summary rather than being buried in the log. No flag needed, which means it also helps everyone who would never set one.

4. Expose facts as outputs, not prose. If you still want to assert things yourself, additional outputs like latestVersion and changeLevel would turn your 25-line block into a one-liner – and it'd be parseable instead of something you have to read.

5. Fix the worst error message we have. A shallow clone (missing fetch-depth: 0, by far the most common misconfiguration) currently fails with object not found, which helps nobody. We can detect that reliably and say what's actually wrong.

We're inclined to do 3 and 5 in any case, since they help everyone without requiring any configuration, and to discuss 1 and 2 properly, since those are the ones that would genuinely let you drop your step.

Does that match what you were after? And in particular: would --base=highest cover your use case, or is there a reason you'd need the assertion on top? 😊