bgt

Bitcoin Guix Tag Builder

About

bgt is a tool to perform automated or semi-automated Guix builds of Bitcoin Core.

These can be manually initiated, or trigger when a new tag is detected via polling the GitHub API.

It can build, attest, and codesign tagged Bitcoin Core releases.

Requirements

• You will need to install and setup Guix for Bitcoin Core by following Bitcoin Core's INSTALL.md.
• (optional) For attesting (signing) you will need a GPG key configured in your default keyring.
• You will need a fork of the bitcoin-core/guix.sigs repository.
  • For pull requests to this repository, you will need your GPG key to be in the guix.sigs builder-keys which can be done via a pull request.
• (optional) To use --auto mode (automatically open pull requests against guix.sigs) you will need a GitHub personal access token. Set it via the GITHUB_BGT_TOKEN environment variable or github_token in the config file.
  • Classic token (recommended): The public_repo scope is sufficient and allows creating PRs against upstream repos.
  • Fine-grained token: Not recommended - these tokens cannot create PRs on repos they don't have explicit access to, even for public repos.

Installation

To install bgt-builder, you need to have Rust and Cargo installed on your system. Then, you can install it either using Cargo:

cargo install bgt

Or from source:

git clone https://github.com/bitcoin-dev-tools/bgt-builder.git bgt
cd bgt
cargo install --path .

Usage

After installation, you can use the bgt command to interact with the tool.

To see the available commands run:

bgt

Setup

Run the setup wizard to configure bgt:

bgt setup

This will guide you through setting up your GPG key short ID, signer name, and other necessary configurations.

Build

Build a specific tag of Bitcoin Core:

bgt build <tag>

Replace <tag> with the specific version tag you want to build, e.g., v27.1.

Attest

Attest to non-codesigned build outputs:

bgt attest <tag> [--auto]

The --auto flag will automatically sign using GPG and open a PR on GitHub.

Codesign

Attach codesignatures to existing non-codesigned outputs and attest:

bgt codesign <tag> [--auto]

The --auto flag will automatically sign using GPG and open a PR on GitHub.

Watch

Run a continuous watcher to monitor for new tags and automatically build them:

bgt watch start [--auto] [--dry-run] [--log-file <PATH>]

Where:

• --auto automatically signs using GPG and opens PRs on GitHub
• --dry-run monitors for new tags without performing builds or signing
• --log-file <PATH> writes logs to the specified file instead of stderr

This command will poll the GitHub API for new tags and automatically build, attest, and codesign new releases.

To run in the background, use a process manager like systemd, supervisor, or tmux (see Running as a background service below).

Clean

Clean up Guix build directories while leaving caches intact:

bgt clean

Show Config

View the current configuration settings:

bgt show-config

Warmup

Guix build current master to populate Guix caches:

bgt warmup

Additional Options

• --multi-package: Use JOBS=1 ADDITIONAL_GUIX_COMMON_FLAGS='--max-jobs=8' for building. This can be added to any command.
• --debug: Enable debug log level. This can be added to any command.

Logging

bgt uses environment variables for logging configuration. You can set the RUST_LOG environment variable to control the log level. For example:

RUST_LOG=debug bgt build v27.1

This will run the build command with debug-level logging.

Running as a background service

To run the watcher in the background, use a process manager. Here are some options:

Using systemd (Linux)

Create a user service file at ~/.config/systemd/user/bgt-watch.service:

[Unit]
Description=BGT Bitcoin Guix Builder Watcher
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/path/to/bgt watch start --auto
Restart=on-failure
RestartSec=30

[Install]
WantedBy=default.target

Then enable and start it:

systemctl --user daemon-reload
systemctl --user enable bgt-watch
systemctl --user start bgt-watch
systemctl --user status bgt-watch

View logs with:

journalctl --user -u bgt-watch -f

Using tmux or screen

# tmux
tmux new-session -d -s bgt 'bgt watch start --auto'

# screen
screen -dmS bgt bgt watch start --auto

With log file

For any method, you can use --log-file to write logs to a file:

bgt watch start --auto --log-file ~/.config/bgt/watch.log

Contributing

Contributions to bgt are welcome! Please feel free to submit issues and pull requests on our GitHub repository.

License

See license.

Plans

• implement Guix building
• permit building a specified tag
• enable signing
• add advanced GPG signing solutions (tbd)
• remove some dependencies