big-release — One binary. Every language. Zero runtime.

Quickstart

From zero to automated releases

Pick your language. Copy the files. That's the setup.

Set up big-release for Go

Prerequisites: Go 1.22+, git, a GitHub repo with main branch

.big-release.yml release config

# big-release configuration
tagFormat: "v${version}"
initialVersion: "0.1.0"

plugins:
  - changelog
  - git
  - github

.github/workflows/release.yml CI release job

name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Install big-release
        run: |
          curl -sL https://github.com/danielvm-git/big-release/releases/latest/download/big-release-linux-amd64 -o big-release
          chmod +x big-release && sudo mv big-release /usr/local/bin/

      - name: Release
        run: big-release release --verbose
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

go.mod module

module github.com/your-org/your-app

go 1.22

terminal dry run

# preview the next release without publishing
big-release --dry-run

1
Commit with a convention
Use feat: / fix: prefixes. That's the whole contract.
2
Drop in .big-release.yml
Set tagFormat and pick your plugins. Copy the block above.
3
Add the release workflow
Install the binary, run big-release release after your tests.
4
Merge to main
big-release does the rest — tag, GitHub Release, changelog, deploy.

Troubleshooting

Missing VERSION file: big-release creates the git tag and GitHub Release automatically. A VERSION file is optional — only needed if your app reads it at runtime.

Protected branch rejection: big-release only pushes tags and creates Releases via the API — it never pushes to the branch. Protected branches work out of the box. If you also use the git plugin to commit changelogs back to the branch, you'll need to accommodate branch protection yourself.

Auth failures: Ensure GITHUB_TOKEN has contents: write permission. For private repos, use a personal access token or a GitHub App token.

Set up big-release for Node.js

Prerequisites: Node 18+, npm/pnpm, git, a GitHub repo with main branch

.big-release.yml release config

# big-release configuration
tagFormat: "v${version}"
initialVersion: "0.1.0"

plugins:
  - changelog
  - git
  - github

.github/workflows/release.yml CI release job

name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci
      - run: npm test

      - name: Install big-release
        run: |
          curl -sL https://github.com/danielvm-git/big-release/releases/latest/download/big-release-linux-amd64 -o big-release
          chmod +x big-release && sudo mv big-release /usr/local/bin/

      - name: Release
        run: big-release release --verbose
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package.json scripts

{
  "name": "your-app",
  "version": "0.1.0",
  "scripts": {
    "start": "node server.js",
    "test": "node --test"
  }
}

terminal dry run

# preview the next release without publishing
big-release --dry-run

1
Commit with a convention
Use feat: / fix: prefixes. That's the whole contract.
2
Drop in .big-release.yml
Set tagFormat and pick your plugins. Copy the block above.
3
Add the release workflow
Install the binary, run big-release release after npm test.
4
Merge to main
big-release does the rest — tag, GitHub Release, changelog, version bump.

Troubleshooting

package.json version out of sync: big-release manages the git tag, not package.json. If you publish to npm, add the npm publisher in .big-release.yml — it updates package.json and runs npm publish automatically.

Protected branch rejection: big-release only pushes tags and creates Releases via the API. Protected branches work out of the box.

Auth failures: Ensure GITHUB_TOKEN has contents: write permission.

Set up big-release for Python

Prerequisites: Python 3.12+, uv or pip, git, a GitHub repo with main branch

.big-release.yml release config

# big-release configuration
tagFormat: "v${version}"
initialVersion: "0.1.0"

plugins:
  - changelog
  - git
  - github

.github/workflows/release.yml CI release job

name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - run: pip install uv && uv sync
      - run: uv run pytest -q

      - name: Install big-release
        run: |
          curl -sL https://github.com/danielvm-git/big-release/releases/latest/download/big-release-linux-amd64 -o big-release
          chmod +x big-release && sudo mv big-release /usr/local/bin/

      - name: Release
        run: big-release release --verbose
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

pyproject.toml project

[project]
name = "your-app"
version = "0.1.0"
requires-python = ">=3.12"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

terminal dry run

# preview the next release without publishing
big-release --dry-run

1
Commit with a convention
Use feat: / fix: prefixes. That's the whole contract.
2
Drop in .big-release.yml
Set tagFormat and pick your plugins. Copy the block above.
3
Add the release workflow
Install the binary, run big-release release after uv run pytest.
4
Merge to main
big-release does the rest — tag, GitHub Release, changelog, deploy.

Troubleshooting

pyproject.toml version out of sync: big-release manages the git tag, not pyproject.toml. If you publish to PyPI, add the pypi publisher in .big-release.yml — it updates the version and runs twine upload automatically.

Protected branch rejection: big-release only pushes tags and creates Releases via the API. Protected branches work out of the box.

Auth failures: Ensure GITHUB_TOKEN has contents: write permission. For PyPI publishing, set PYPI_TOKEN as a repo secret.

Set up big-release for PHP

Prerequisites: PHP 8.3+, Composer, git, a GitHub repo with main branch

.big-release.yml release config

# big-release configuration
tagFormat: "v${version}"
initialVersion: "0.1.0"

plugins:
  - changelog
  - git
  - github

.github/workflows/release.yml CI release job

name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - uses: shivammathur/setup-php@v2
        with:
          php-version: "8.3"

      - run: composer install --no-interaction
      - run: composer test

      - name: Install big-release
        run: |
          curl -sL https://github.com/danielvm-git/big-release/releases/latest/download/big-release-linux-amd64 -o big-release
          chmod +x big-release && sudo mv big-release /usr/local/bin/

      - name: Release
        run: big-release release --verbose
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

composer.json package

{
  "name": "your-org/your-app",
  "type": "project",
  "require": {
    "php": ">=8.3"
  },
  "scripts": {
    "test": "phpunit"
  }
}

terminal dry run

# preview the next release without publishing
big-release --dry-run

1
Commit with a convention
Use feat: / fix: prefixes. That's the whole contract.
2
Drop in .big-release.yml
Set tagFormat and pick your plugins. Copy the block above.
3
Add the release workflow
Install the binary, run big-release release after composer test.
4
Merge to main
big-release does the rest — tag, GitHub Release, changelog, deploy.

Troubleshooting

composer.json version not updated: big-release manages the git tag, not composer.json. If you publish to Packagist, add the packagist publisher in .big-release.yml.

Protected branch rejection: big-release only pushes tags and creates Releases via the API. Protected branches work out of the box.

Auth failures: Ensure GITHUB_TOKEN has contents: write permission.

	big-release	semantic-release
Runtime	Single static binary, no runtime	Requires Node.js + npm install
Languages	Go, Node, Python, Rust, PHP, Java, Swift, Godot	Node-first (others via community plugins)
Protected branches	Works with zero config out of the box	Requires branch-protection accommodation
Config	One `.big-release.yml`	`.releaserc` + per-plugin npm installs
Conventional Commits	✓	✓
Multi-channel / prerelease	✓	✓
GitHub + GitLab Releases	✓	✓ (separate plugins)

Language	Publisher	Registry
JavaScript / TypeScript	`npm`	npmjs.com
JavaScript (pnpm)	`pnpm`	npm-compatible registries
Python	`pypi`	pypi.org
Rust	`crates`	crates.io
Go	`goproxy`	proxy.golang.org
PHP	`packagist`	packagist.org
Java	`maven`	maven central
Swift	`swift`	swiftpackageindex.com
Godot / GDScript	`godot`	GitHub Releases

One binary.
Every language.
Zero runtime.

Four real apps, versioned and deployed by big-release

go.bigbase.click

node.bigbase.click

python.bigbase.click

php.bigbase.click

One merge, three automatic moves

A conventional commit lands

big-release computes the bump

It tags, releases & deploys

One command, any platform

From zero to automated releases

Set up big-release for Go

Commit with a convention

Drop in `.big-release.yml`

Add the release workflow

Merge to `main`

Set up big-release for Node.js

Commit with a convention

Drop in `.big-release.yml`

Add the release workflow

Merge to `main`

Set up big-release for Python

Commit with a convention

Drop in `.big-release.yml`

Add the release workflow

Merge to `main`

Set up big-release for PHP

Commit with a convention

Drop in `.big-release.yml`

Add the release workflow

Merge to `main`

big-release vs semantic-release

Every bump is decided by a commit

9 languages, one workflow

Four real apps, versioned and deployed by big-release

go.bigbase.click

node.bigbase.click

python.bigbase.click

php.bigbase.click

One merge, three automatic moves

A conventional commit lands

big-release computes the bump

It tags, releases & deploys

One command, any platform

From zero to automated releases

Set up big-release for Go

Commit with a convention

Drop in .big-release.yml

Add the release workflow

Merge to main

Set up big-release for Node.js

Commit with a convention

Drop in .big-release.yml

Add the release workflow

Merge to main

Set up big-release for Python

Commit with a convention

Drop in .big-release.yml

Add the release workflow

Merge to main

Set up big-release for PHP

Commit with a convention

Drop in .big-release.yml

Add the release workflow

Merge to main

big-release vs semantic-release

Every bump is decided by a commit

9 languages, one workflow

Drop in `.big-release.yml`

Merge to `main`

Drop in `.big-release.yml`

Merge to `main`

Drop in `.big-release.yml`

Merge to `main`

Drop in `.big-release.yml`

Merge to `main`