Using the official action

The easiest way to use FerrFlow in GitHub Actions is the FerrLabs/ferrflow@v1 action. It installs the binary and runs ferrflow release automatically.

name: Release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write   # required to push tags and create releases
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0          # full history needed for commit scanning
          token: ${{ secrets.GITHUB_TOKEN }}

      - uses: FerrLabs/ferrflow@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Permissions

FerrFlow needs contents: write to:

• Push version bump commits
• Create and push git tags
• Create GitHub Releases

If your repository has branch protection rules, create a dedicated token with the necessary permissions and pass it as FERRFLOW_TOKEN or configure the action's token input.

Accessing the release output

The action exposes the new version as an output you can use in downstream steps:

- uses: FerrLabs/ferrflow@v1
  id: ferrflow
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

- name: Build Docker image
  if: steps.ferrflow.outputs.version != ''
  run: |
    docker build -t myimage:${{ steps.ferrflow.outputs.version }} .
    docker push myimage:${{ steps.ferrflow.outputs.version }}

Skip CI on release commits

FerrFlow commits version bumps with [skip ci] in the message by default to prevent infinite loops. No extra configuration needed.

Monorepo example

In a monorepo, FerrFlow releases each changed package in a single run:

- uses: FerrLabs/ferrflow@v1
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# Creates api@v1.3.0 and site@v0.5.1 in one step if both changed