branch-names/README.md

branch-names

Get branch or tag information without the /ref/* prefix

Features

• Retrieve the current branch name without any prefix. (e.g. 'refs/heads/main' -> 'main')
• Retrieve the current tag with an option to strip the prefix (e.g. v0.0.1 -> v -> 0.0.1)
• Detect actions triggered by non default branches
• Detect actions triggered by the default branch
• Supports all valid git branch names

Usage

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
      
...
    steps:
      - name: Get branch name
        id: branch-name
        uses: tj-actions/branch-names@v5.1
        
      - name: Running on the default branch.
        if: steps.branch-name.outputs.is_default == 'true'
        run: |
          echo "Running on default: ${{ steps.branch-name.outputs.current_branch }}"          
        # Outputs: "Running on default: main".
      
      - name: Running on a pull request branch.
        if: steps.branch-name.outputs.is_default == 'false'
        run: |
          echo "Running on pr: ${{ steps.branch-name.outputs.current_branch }}"          
        # Outputs: "Running on pr: feature/test".

If you feel generous and want to show some extra appreciation:

Support this project with a ⭐

Outputs

OUTPUT	TYPE	DESCRIPTION
base_ref_branch	string	The target branch of a pull request e.g main
current_branch	string	Returns the value of the current branch which is consistent regardless of event_type e.g main, feature/test, v0.0.1.
default_branch	string
head_ref_branch	string	The source branch of a pull request e.g feature/test
is_default	string	Returns "true" if the current branch is the default else "false".
is_tag	string	Returns "true" if the current branch is a tag else "false".
ref_branch	string	The branch that triggered the workflow run. e.g 1/merge, main
tag	string	The tag that triggered the workflow run. e.g v0.0.1, 0.0.1

Output	type	Example	Description
is_default	boolean	true OR false	Detects wheter the workflow is running on a default branch
is_tag	boolean	true OR false	Detects wheter the workflow is running on a tag branch
current_branch	string	main OR feature/test OR v0.0.1	Always returns a valid branch name for a triggered workflow run.
base_ref_branch	string	main	The target branch of a pull request
head_ref_branch	string	feature/test	The source branch of a pull request
ref_branch	string	1/merge OR main	The branch that triggered the workflow run
tag	string	v0.0.1 OR 0.0.1	The tag that triggered the workflow run

Inputs

INPUT	TYPE	REQUIRED	DEFAULT	DESCRIPTION
strip_tag_prefix	string	false		The tag prefix to strip e.g v0.0.1 -> (strip v) -> 0.0.1

Input	type	default	Description
strip_tag_prefix	string	''	The tag prefix to strip e.g v0.0.1 -> v -> 0.0.1

Events

• push*

on:
  push:
    branches:
      - main

...
    steps:
      - name: Get branch names
        id: branch-name
        uses: tj-actions/branch-names@v5.1

      - name: Current branch name
        run: |
          echo "${{ steps.branch-name.outputs.current_branch }}"          
        # Outputs: "main" the branch that triggered the push event.

      - name: Running on the default branch.
        if: steps.branch-name.outputs.is_default == 'true'
        run: |
          echo "Running on default: ${{ steps.branch-name.outputs.current_branch }}"          
        # Outputs: "Running on default: main".
      
      - name: Running on the default branch (i.e non tag based branch).
        if: steps.branch-name.outputs.is_tag == 'false' && steps.branch-name.outputs.is_default == 'true'
        run: |
          echo "Running on branch: ${{ steps.branch-name.outputs.current_branch }}"          
        # Outputs: "Running on branch: main".
      
      - name: Get Ref brach name
        run: |
          echo "${{ steps.branch-name.outputs.ref_branch }}"          
        #  Outputs: "main"

• pull_request*

on:
  pull_request:
    branches:
      - main

...
    steps:
      - name: Get branch names
        id: branch-name
        uses: tj-actions/branch-names@v5.1
      
      - name: Current branch name
        run: |
          echo "${{ steps.branch-name.outputs.current_branch }}"          
        # Outputs: "feature/test" current PR branch.

      - name: Running on a non tag based branch and a PR branch.
        if: steps.branch-name.outputs.is_default == 'false'
        run: |
          echo "Running on branch: ${{ steps.branch-name.outputs.current_branch }}"          
        # Outputs: "Running on branch: feature/test".
      
      - name: Running on a pull request (i.e non tag based branch).
        if: steps.branch-name.outputs.is_tag == 'false' && steps.branch-name.outputs.is_default == 'false'
        run: |
          echo "Running on branch: ${{ steps.branch-name.outputs.current_branch }}"          
        # Outputs: "Running on branch: feature/test".
      
      - name: Get Ref brach name
        run: |
          echo "${{ steps.branch-name.outputs.ref_branch }}"          
        #  Outputs: "1/merge"

      - name: Get Head Ref branch name (i.e The current pull request branch)
        run: |
          echo "${{ steps.branch-name.outputs.head_ref_branch }}"          
        # Outputs: "feature/test" current PR branch.

      - name: Get Base Ref branch name (i.e The target of a pull request.)
        run: |
          echo "${{ steps.branch-name.outputs.base_ref_branch }}"          
        # Outputs: "main".

• tag*

on:
  push:
    tags:
      - '*'

...
    steps:
      - name: Get branch names
        id: branch-name
        uses: tj-actions/branch-names@v5.1
     
      - name: Running on a tag branch.
        if: steps.branch-name.outputs.is_tag == 'true'
        run: |
          echo "Running on: ${{ steps.branch-name.outputs.tag }}"          
        # Outputs: "Running on: v0.0.1".
        
      - name: Get the current tag
        if: steps.branch-name.outputs.is_tag == 'true'  # Replaces: startsWith(github.ref, 'refs/tags/')
        run: |
          echo "${{ steps.branch-name.outputs.tag }}"          
        # Outputs: "v0.0.1" OR "0.0.1"

Possible usage with actions/checkout@v2:

on:
  pull_request:
    branches:
      - develop
    
 jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Get branch names.
        id: branch-names
        uses: tj-actions/branch-names@v5.1
      - uses: actions/checkout@v2
        with:
          ref: ${{ steps.branch-names.outputs.head_ref_branch }}

• Free software: MIT license

Credits

This package was created with Cookiecutter.

Report Bugs

Report bugs at https://github.com/tj-actions/branch-names/issues.

If you are reporting a bug, please include:

• Your operating system name and version.
• Any details about your workflow that might be helpful in troubleshooting.
• Detailed steps to reproduce the bug.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Alejandro Loarca 💻

This project follows the all-contributors specification. Contributions of any kind welcome!