bitcoin-core/gui: the staging tree where Bitcoin Core's interface is developed

A staging tree with no releases, and why that is the point

The bitcoin-core/gui repository is used exclusively for the development of the GUI. That single sentence, plus the sentence that follows it, explains the whole repository. Its master branch is identical in all monotree repositories, and release branches and tags do not exist there, so the documentation asks you not to fork the repository unless it is for development reasons.

The distinction matters more than it first appears. A normal project repository accumulates tags, release branches and long lived maintenance lines, because users and distributors point at them. This one is a staging area, a place where interface work happens and from which changes flow back into the main tree. The README of the main project at github.com/bitcoin/bitcoin is the one that carries the releases.

The project itself is Bitcoin Core, which connects to the Bitcoin peer to peer network to download and fully validate blocks and transactions, and which also includes a wallet and a graphical user interface that can be optionally built. The interface is therefore a component of a node rather than a product in its own right, and the separate repository reflects that: the same people, the same review process, one tree for interface work.

The master branch is built and tested but is explicitly not guaranteed stable

The development process section is where the real expectations are set. The master branch is regularly built and tested, with the build instructions in the doc/build-*.md files, but it is not guaranteed to be completely stable. Tags are created regularly from release branches to indicate new official, stable release versions of Bitcoin Core.

That is a deliberate separation between two things that are often confused. A green build on master means the code compiles and passes the automated checks, not that the binary you could build from it is something to hand to someone else. The tagged releases come from release branches, and those are the artifacts that get published.

For an immediately usable binary version, the README points readers to the download page at bitcoincore.org instead. That pointer is worth reading carefully if you are new to the project, because building from a staging branch is a development activity, not an installation method. The MIT licence covers the code, and the further information is in the doc folder.

Two test systems: ctest for units and a Python runner for behaviour

The testing section is the most detailed part of the documentation, and it describes two separate systems.

Unit tests are the first, with developers strongly encouraged to write them for new code and to submit tests for old code as well. They are compiled and run with ctest, assuming they were not disabled while the build system was generated, and the details of running and extending them are in src/test/README.md. The presence of CTestConfig.cmake and the CMakePresets.json at the root show that the build system is CMake based, with the presets file there to make the configuration reproducible.

The second system is the regression and integration tests, written in Python and living in the test/ directory. They are run with build/test/functional/test_runner.py, which assumes build is your build directory, and they need the test dependencies installed. The distinction in purpose is the standard one, with unit tests covering the code and the functional tests covering whether the whole program behaves.

Continuous integration runs every pull request on Windows, Linux and macOS, and the documentation is strict about the merge rule: the CI must pass on all commits before merge, so that a new pull request does not inherit unrelated failures. The vcpkg.json file at the root handles the C++ dependency side, and depends/ and contrib/ hold the packaged and contributed tooling.

Review and manual testing are the real constraint, not writing the code

The documentation says something here that is unusual to read in a README, and it is worth quoting. Testing and code review is the bottleneck for development, the project gets more pull requests than it can review and test on short notice, and it asks people to be patient and help out by testing other people's pull requests. It also reminds contributors to remember that this is a security critical project where any mistake might cost people lots of money.

The manual quality assurance section adds a second rule. Changes should be tested by somebody other than the developer who wrote the code, which the documentation singles out as especially important for large or high risk changes. It also suggests adding a test plan to the pull request description when testing is not straightforward, which is a practical way to let a reviewer know what a change should have been exercised against.

Together, these two sections describe the real cost of contributing here. Writing the patch is the cheap part. The expensive part is getting a second person to install the build, exercise the change, and report what happened, which is why the project asks for help with testing other people's work rather than only with your own. SECURITY.md, CONTRIBUTING.md, doc/developer-notes.md and the ci/ directory are the places where the mechanics of that process are written down.

Translations arrive from Transifex, and pull requests for them are refused

The translation workflow has one rule that will save you a wasted pull request. Changes to translations and new translations go to Bitcoin Core's Transifex page, translations are periodically pulled from Transifex and merged into the git repository, and the project does not accept translation changes as GitHub pull requests, because the next pull from Transifex would automatically overwrite them again.

The mechanism has visible artefacts in the tree. The .tx/ directory is the Transifex client configuration, and the doc/translation_process.md file describes how the cycle works. The .editorconfig and .style.yapf files cover the formatting conventions for the different file types, and ruff.toml does the same for the Python side, which matters for the functional test suite and any tooling written in Python.

The C++ side is organised under src/, with the top level CMakeLists.txt, the cmake/ directory of modules, share/ holding the data files, and the .github/ directory holding the workflows that run the CI matrix. There is also an INSTALL.md at the root, and a .python-version file that pins the interpreter the Python tooling expects.

Where using this repository directly is the wrong move

The clearest wrong-tool case is using this tree as a source of releases. Tags are created from release branches in the main repository, and this one has no release branches and no tags, so there is nothing here to point an installer at. The README sends users who want a usable binary to the download page, and that is the right destination for them.

The second case is forking for a custom build to distribute. The documentation asks you not to fork the repository unless it is for development reasons, and the reasoning is practical. A fork of a staging tree of a security critical project carries the risk of drifting from the upstream tree without anyone noticing, and the master branch is described as not guaranteed to be completely stable, so a distributed fork inherits that instability with no release discipline behind it.

The third case is treating the GUI as a separate application you can pick and choose. The interface is an optional build of the node, and the interface work happens inside the same review process and the same monotree as the rest of the code. That is why the interface is developed in a separate repository at all, and not because it is a separable product.

Editorial conclusion

Adopt this repository if you intend to contribute to the Bitcoin Core graphical interface, since the interface work is developed here and the branch mirrors the monotree repositories, but do not treat it as a place to track releases, because the documentation states that release branches and tags do not exist there and asks you not to fork it unless the reason is development. Before you build anything, read the build instructions in the doc folder, remember that the master branch is built and tested regularly but is not guaranteed to be completely stable, and plan for a review bottleneck that the project itself describes, where testing and code review are the limiting factor and a mistake in this codebase may cost people money.

Frequently asked questions

Official sources

1. bitcoin-core/gui on GitHub
2. Issues
3. License: MIT
4. Project website
5. README