AutoBump

Automatically update CHANGELOG.md according to the Keep a Changelog (version 1.1.0) standard and the Semantic Versioning (version 2.0.0) standard, commit the changes, push the commits, and create a merge request/pull request on GitLab, Azure DevOps, or GitHub.

Supported Languages

AutoBump supports automatic language detection and version updates for:

• Go: Detects via go.mod; versions managed through git tags; APIs documented with Swagger (swaggo) also get the @version annotation in the entrypoint (main.go, cmd/main.go, or cmd/*/main.go) and the generated docs.go/swagger.json/swagger.yaml (under docs/, cmd/docs/, or cmd/*/docs/) updated
• Java: Detects via build.gradle, pom.xml, updates build.gradle and application.yaml
• Python: Detects via pyproject.toml, setup.py, updates __init__.py
• Terraform: Detects via *.tf, versions.tf; versions managed through git tags (no version file)
• TypeScript: Detects via package.json, tsconfig.json, updates package.json
• C#: Detects via *.sln, *.csproj, updates project files

Installation

Quick Install (Recommended)

Install autobump with a single command:

curl -fsSL https://raw.githubusercontent.com/rios0rios0/autobump/main/install.sh | sh

Or using wget:

wget -qO- https://raw.githubusercontent.com/rios0rios0/autobump/main/install.sh | sh

Installation Options

# Install specific version
curl -fsSL https://raw.githubusercontent.com/rios0rios0/autobump/main/install.sh | sh -s -- --version v1.0.0

# Install to custom directory
curl -fsSL https://raw.githubusercontent.com/rios0rios0/autobump/main/install.sh | sh -s -- --install-dir /usr/local/bin

# Show what would be installed without doing it
curl -fsSL https://raw.githubusercontent.com/rios0rios0/autobump/main/install.sh | sh -s -- --dry-run

# Force reinstallation
curl -fsSL https://raw.githubusercontent.com/rios0rios0/autobump/main/install.sh | sh -s -- --force

Download Pre-built Binaries

Download pre-built binaries from the releases page.

Configuration

Create a configuration file based on the example from configs/autobump.yaml and put it in ~/.config/autobump.yaml. You will need to configure at least one access token depending on which Git platform you use:

• GitLab: Set gitlab_access_token field with your GitLab personal access token (e.g., glpat-TOKEN)
• Azure DevOps: Set azure_devops_access_token field with your Azure DevOps personal access token
• GitHub: Set github_access_token field with your GitHub personal access token (e.g., ghp_TOKEN)

You can provide the token directly in the configuration file or specify a path to a file containing the token:

# Direct token (not recommended for security)
gitlab_access_token: "???"

# Or path to token file (recommended)
gitlab_access_token: ".secure_files/gitlab_access_token.key"

Optional GPG Key Signing

You can optionally configure GPG key signing for commits:

gpg_key_path: "/home/user/.gnupg/autobump.asc"

To export your GPG key:

gpg --export-secret-key --armor $(git config user.signingkey) > ~/.gnupg/autobump.asc

Optional SSH Authentication

When pushing to SSH remotes, AutoBump auto-detects the SSH agent from SSH_AUTH_SOCK and common socket paths (e.g., 1Password at ~/.1password/agent.sock). For environments without an SSH agent, you can configure an explicit SSH key:

# Path to SSH private key (supports ~ expansion)
ssh_key_path: '~/.ssh/id_ed25519'

# Passphrase for the key (optional, can be a file path)
ssh_key_passphrase: ''

# Or point to a custom SSH agent socket (e.g., 1Password)
ssh_auth_sock: '~/.1password/agent.sock'

Stale Branch Cleanup

Before creating the branch for a release, AutoBump deletes every remote branch carrying the bump prefix (chore/bump-*) and closes the pull request attached to each one — on Azure DevOps the pull request is abandoned. Without this, running AutoBump repeatedly on a repository nobody reviews leaves a trail of abandoned release branches and open pull requests.

Merged and unmerged branches are treated alike: a bump branch is disposable, because the branch needed for the current release is recreated immediately afterwards. Cleanup only runs once a bump is actually needed, so a pull request is never closed without a replacement being opened for it.

Cleanup is enabled by default. Turn it off permanently in the config:

# Keep the bump branches from previous runs
cleanup_stale_branches: false

# Customise the branch prefix used for both creation and cleanup
bump_branch_prefix: 'chore/bump-'

Or disable it for a single run with --skip-cleanup:

autobump run --skip-cleanup

Note: closing pull requests needs a token for the platform. Without one, AutoBump still deletes the branches and logs a warning that the pull requests were left open.

Usage

AutoBump has two main modes: local (single repository) and run (batch engine).

These flags work with every mode:

Flag	Description
-c, --config	Path to the config file (auto-detected when omitted)
-v, --verbose	Enable verbose output
--skip-cleanup	Keep the bump branches from earlier runs instead of deleting them and closing their PRs

1. Local Mode

Process a single repository. Run in the project directory or specify a path:

autobump local              # Current directory
autobump local /path/to/repo  # Specific path
autobump .                  # Shorthand for local mode

AutoBump will automatically detect the project language, update the version files, update the CHANGELOG.md file, and create a merge request/pull request on your Git platform (GitLab, Azure DevOps, or GitHub).

You can manually specify the project language using the -l or --language flag:

autobump local -l java

Available languages: go, java, python, terraform, typescript, cs

You can also specify a custom configuration file path:

autobump local -c /path/to/custom/config.yaml

2. Run Mode (Batch + Discover)

The run command processes repositories from a configuration file. It auto-detects the mode based on config content:

• If projects is configured, iterates the static project list
• If providers is configured, discovers repos via provider APIs
• If both are present, both are processed

Static Project List

Add a projects section to your configuration file:

projects:
  # Local repository path with auto-detected language
  - path: "/home/user/repo1"

  # Local repository with manually specified language
  - path: "/home/user/repo2"
    language: "Java"

  # Git URL - AutoBump will clone automatically into a temporary directory
  - path: "git@github.com:example/repo3.git"

  # Project with specific access token (overrides global token)
  - path: "https://gitlab.com/user/repo4.git"
    project_access_token: "???"

Provider Discovery

Add a providers section to your configuration file:

providers:
  # GitHub - discovers all repos in the specified organizations
  - type: "github"
    token: "ghp_TOKEN"
    organizations:
      - "my-github-org"

  # GitLab - discovers all projects in the specified groups (including subgroups)
  - type: "gitlab"
    token: "${GITLAB_TOKEN}"  # reads from environment variable
    organizations:
      - "my-gitlab-group"

  # Azure DevOps - discovers all repos in the specified organizations
  - type: "azuredevops"
    token: "/path/to/token/file"  # reads token from file
    organizations:
      - "my-azure-org"

The token field supports three formats:

• Inline: "ghp_TOKEN" -- the token value directly
• Environment variable: "${ENV_VAR}" -- reads the token from an environment variable
• File path: "/path/to/file" -- reads the token from a file on disk

Then run:

autobump run

AutoBump will process all configured sources (static project list and/or provider API discovery).

Per-Project Configuration (.autobump.yaml)

Drop a .autobump.yaml (or .autobump.yml, autobump.yaml, autobump.yml) at the root of any repository to override settings for that project only. AutoBump auto-detects the file from local, run, and discovery modes, so the global config in ~/.config/autobump.yaml does not need to know anything about it.

The keys recognized in a per-project file are:

Key	Purpose
changelog_path	Custom changelog filename relative to the project root (e.g. CHANGELOG_PROPRIETARY.md)
versioning	Versioning mode: semver (default), fork-dot, or fork-dash
detect_chlog	Set to false to ignore chlog fragments (detection is on by default)
languages	Per-language overrides for extensions, special_patterns, and version_files

# .autobump.yaml at the root of a fork repository
changelog_path: 'CHANGELOG_PROPRIETARY.md'
versioning: 'fork-dot'

The same keys can also be set at the global level in ~/.config/autobump.yaml (under the project entry, or as top-level defaults applied to every project). Project-level values always win over global ones.

Fragment-Based Changelogs (chlog)

chlog removes changelog merge conflicts by giving every change its own YAML file under .changes/unreleased/ instead of having developers edit a shared CHANGELOG.md. That leaves the [Unreleased] section permanently empty, which would otherwise make AutoBump conclude there is nothing to release.

AutoBump detects the layout and handles it automatically — no configuration, and no chlog binary required on the runner. A repository counts as a chlog user when it has a .chlog.yaml (or .chlog.yml) or a .changes/unreleased/ directory.

When fragments are pending, AutoBump:

• reads every fragment and turns it into ordinary ### <Kind> entries, so chlog's six default kinds (Added, Changed, Deprecated, Removed, Fixed, Security) land in the matching Keep a Changelog sections. A custom kind is filed under ### Changed rather than being dropped
• merges those entries with anything already written by hand in [Unreleased], so nothing is lost while a repository is migrating to chlog
• computes the next version with its own SemVer rules, not chlog's auto mapping. An Added entry means a minor bump, a **BREAKING CHANGE:** entry means a major bump, and anything else means a patch — the same rules every other repository gets. A release may therefore differ from what chlog batch auto would have chosen, which caps major bumps below 1.0.0 and treats Changed/Removed as breaking
• honours the changelogPath declared in .chlog.yaml, unless changelog_path overrides it
• deletes the consumed fragments and stages the removals in the same commit that publishes their content, so the next run does not release them twice

If chlog batch has already produced a .changes/v<version>.md that was never merged, AutoBump stops with an error instead of releasing on top of it: that file carries a version chlog already decided. Run chlog merge (or delete the file) and try again.

Set detect_chlog: false — globally or per project — to switch the behaviour off.

Versioning Modes

AutoBump supports three versioning strategies, selectable via the versioning key. All three honor the Keep a Changelog format; only the way the next version is computed differs.

Mode	Pattern	Example transition	When to use
semver	X.Y.Z	1.0.0 → 1.1.0	Default. Standard Semantic Versioning
fork-dot	X.Y.Z.N	3.3.0.16 → 3.3.0.17	Forks following the Forking Technique with a 4th increment digit
fork-dash	X.Y.Z-N	1.21.0-9 → 1.21.0-10	Forks where CI/CD does not accept four-segment versions

In fork modes, AutoBump:

• Reads the current version from the last non-Unreleased header in the changelog
• Increments only the trailing fork digit (N); the upstream X.Y.Z is preserved
• Skips language-specific version-file rewrites (forks typically maintain those manually or via separate pipelines)
• Still moves [Unreleased] content into a freshly dated ## [<next>] - YYYY-MM-DD section

Example fork repository:

# ~/.config/autobump.yaml
projects:
  - path: '~/Development/dev.azure.com/MyOrg/forks/opensearch-dashboards'
    changelog_path: 'CHANGELOG_PROPRIETARY.md'
    versioning: 'fork-dot'

  - path: '~/Development/dev.azure.com/MyOrg/forks/oui'
    changelog_path: 'CHANGELOG_PROPRIETARY.md'
    versioning: 'fork-dash'

Or, equivalently, place a .autobump.yaml in each fork's root:

# .autobump.yaml inside the opensearch-dashboards fork
changelog_path: 'CHANGELOG_PROPRIETARY.md'
versioning: 'fork-dot'

How It Works

1. Repository Discovery (run mode with providers): Queries GitHub, GitLab, and Azure DevOps APIs to find all repositories in configured organizations
2. Language Detection: AutoBump automatically detects the project language by looking for specific files (e.g., go.mod, package.json, pom.xml)
3. Version Detection: Reads the current version from CHANGELOG.md
4. Version Update: Determines the next version based on Semantic Versioning and updates language-specific version files
5. CHANGELOG Update: Moves unreleased changes to the new version section with the current date, deduplicating semantically overlapping entries and folding in any pending chlog fragments
6. Git Operations: Commits changes, creates a new branch, and pushes to remote
7. MR/PR Creation: Creates a merge request (GitLab), pull request (GitHub), or pull request (Azure DevOps) for review

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

See LICENSE for details.