Maven release "Unable to tag SCM" in CI

The release plugin committed the release POMs and tried to create and push a git tag, but the SCM operation failed. The underlying git error (authentication, detached HEAD, or wrong remote) appears below the plugin summary.

What this error means

release:prepare fails with "Unable to tag SCM" followed by a git error such as "Authentication failed", "fatal: You are not currently on a branch", or "src refspec ... does not match any".

mvn output

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-release-plugin:3.0.1:prepare
(default-cli) on project app: Unable to tag SCM
[ERROR] Provider message: The git-push command failed.
[ERROR] Command output:
[ERROR] remote: Invalid username or password.
[ERROR] fatal: Authentication failed for 'https://github.com/acme/app.git/'

Common causes

CI checkout is on a detached HEAD

Most CI checkouts land on a detached commit, not a branch. release:prepare needs a branch to commit and tag, so the SCM step fails.

No push credentials for the remote

The runner has read-only or token-less git access, so the tag push is rejected with an authentication error.

How to fix it

Check out a branch with push permission

Fetch and check out the real branch (not a detached SHA) before releasing.
Give the job a token or deploy key with write access.
Configure git user identity so the release commit can be made.

.github/workflows/release.yml

- uses: actions/checkout@v4
  with:
    ref: main
    token: ${{ secrets.RELEASE_TOKEN }}
- run: |
    git config user.name ci-bot
    git config user.email ci-bot@example.com
    mvn -B release:prepare release:perform

Set the correct SCM developerConnection

Point the <scm><developerConnection> at a pushable URL so the plugin tags the right remote.

pom.xml

<scm>
  <developerConnection>scm:git:https://github.com/acme/app.git</developerConnection>
  <tag>HEAD</tag>
</scm>

How to prevent it

Check out a named branch, not a detached HEAD, for releases.
Grant the release job push credentials via a token or deploy key.
Set git user.name/user.email before running release:prepare.