GitHub Actions GITHUB_REF_NAME contains a slash and breaks tag-derived names

github.ref_name / GITHUB_REF_NAME is the short ref. For hierarchical branches or tags like release/1.2 it contains a slash, which breaks anything that expects a flat name - Docker tags, file names, and some downstream tools reject the slash.

What this error means

A Docker tag or artifact name built from github.ref_name fails because the value contains a slash.

invalid tag "myimage:release/1.2": invalid reference format
# github.ref_name was 'release/1.2'

Common causes

Hierarchical ref names contain slashes

Branch and tag names with slashes carry through to ref_name verbatim.

Downstream tools reject slashes

Docker tags and many identifiers disallow the slash character.

How to fix it

Sanitize the ref name before use

1. Replace slashes with a safe character in a run step.
2. Use the sanitized value for tags and file names.

- id: name
  run: |
    safe="${GITHUB_REF_NAME//\//-}"
    echo "tag=$safe" >> "$GITHUB_OUTPUT"

Use docker/metadata-action for tagging

1. Let the metadata action derive valid tags from refs.
2. It handles slash-containing refs safely.

How to prevent it

• Always sanitize ref_name before using it as a tag or filename.
• Prefer purpose-built actions for Docker tag derivation.

Related guides