sanitize-branch-name

A lightweight GitHub composite action that transforms any branch name into a safe, normalized slug — lowercase, alphanumeric characters only, hyphens as separators.

Ideal for generating Docker image tags, Kubernetes namespace names, S3 prefixes, Helm release names, or any resource that requires a predictable, URL-safe identifier.

---

Transformation rules

Step	Input example	Output example
Lowercase	Feature/My-Cool-Thing	feature/my-cool-thing
Non-alphanumeric → -	feature/my-cool-thing	feature-my-cool-thing
Collapse consecutive -	feature--my--cool	feature-my-cool
Strip leading/trailing -	-my-branch-	my-branch

---

Usage

Basic — sanitize the triggering branch

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: volumioteam/sanitize-branch-name@v1

      - run: echo "Safe name: ${{ steps.sanitize-branch-name.outputs.sanitized-branch-name }}"

With explicit id for referencing the output

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Sanitize branch name
        id: branches
        uses: volumioteam/sanitize-branch-name@v1

      - name: Build Docker image
        run: |
          docker build -t myapp:${{ steps.branches.outputs.sanitized-branch-name }} .

Override the input with a custom string

      - name: Sanitize branch name
        id: branches
        uses: volumioteam/sanitize-branch-name@v1
        with:
          branch-name: ${{ github.head_ref }}   # PR source branch

---

Inputs

Name	Required	Default	Description
branch-name	No	github.ref_name	Raw branch name to sanitize

Outputs

Name	Description
sanitized-branch-name	The cleaned, URL-safe branch slug

---

Real-world examples

Docker tag

- uses: volumioteam/sanitize-branch-name@v1
  id: branches

- run: docker build -t ghcr.io/volumioteam/app:${{ steps.branches.outputs.sanitized-branch-name }} .

Kubernetes namespace

- uses: volumioteam/sanitize-branch-name@v1
  id: branches

- run: kubectl create namespace ${{ steps.branches.outputs.sanitized-branch-name }} --dry-run=client -o yaml | kubectl apply -f -

Helm release name

- uses: volumioteam/sanitize-branch-name@v1
  id: branches

- run: helm upgrade --install ${{ steps.branches.outputs.sanitized-branch-name }} ./chart