GitBound
GitBound is a safety-first local identity manager for developers who use personal, work, client, or organization GitHub accounts on the same computer. It binds each repository to an explicit profile and checks the Git author, GitHub CLI account, SSH key, remote host, and optional owner policy before work leaves your machine.
GitBound delegates credentials to GitHub CLI, Git credential helpers, and OpenSSH. It never asks for, reads, or stores GitHub tokens.
GitBound ships a command-line tool, a Tauri 2 desktop application for Windows, macOS, and Linux, and a CI mode that lets a pipeline enforce the same identity policy before a change merges. The desktop app uses the same Rust safety layer and keeps GitHub CLI switching separate from repository binding.
Documentation
New to GitBound? Start with the user guide. The documentation index lists everything else.
| I want to... | Read |
|---|---|
| Set it up and use it | User guide |
| Enforce identity in a pipeline | Continuous integration |
| Build the desktop app from source | Building the desktop application |
| Understand how the code fits together | Architecture |
| Report a vulnerability, verify an asset | Security policy |
| Contribute a change | Contributing |
Install
Prebuilt Windows desktop artifacts are published on the
Releases page, each with a .sha256 for verification. They
are unsigned, so Windows warns on first run; see
SECURITY.md.
Install a Rust toolchain, then build from source:
cargo install --path .
gitbound --help
GitBound also expects git, gh, and ssh on PATH. Run gitbound doctor to inspect the local setup, or gitbound doctor --json for a structured report.
Build the desktop app from source. The frontend is checked-in static HTML, CSS, and JavaScript, so cargo is the entire toolchain - there is no Node, no npm, and no bundler:
cargo build --release -p gitbound-desktop
That produces a standalone executable. Building .msi and NSIS installers
additionally needs the Tauri CLI, itself installed through cargo:
cargo install tauri-cli --version "^2" --locked
cd desktop && cargo tauri build --bundles msi,nsis
For Windows prerequisites, EXE-only builds, installer output paths, and clean rebuild instructions, see Building the desktop application.
Quick start
Create profiles using flags or omit required flags in an interactive terminal to be prompted:
gitbound profile add personal \
--github-user alice \
--git-name "Alice Developer" \
--git-email alice@example.com \
--ssh-key ~/.ssh/id_ed25519_personal \
--allowed-owner alice
gitbound profile add work \
--github-user alice-company \
--git-name "Alice Developer" \
--git-email alice@company.example \
--ssh-key ~/.ssh/id_ed25519_company \
--allowed-owner company-name
Bind the current repository. Binding does not switch GitHub CLI unless requested explicitly:
gitbound bind work
gitbound bind work --switch
gitbound status
gitbound check
gitbound status --repo ../another-repository
Clone and bind a repository in one identity-safe operation. GitBound uses SSH
when the profile has an SSH key and HTTPS otherwise; override that choice with
--protocol:
gitbound clone work company-name/device-firmware
gitbound clone personal alice/project ./project --protocol https
GitBound validates the host and owner policy before cloning, switches GitHub CLI explicitly, and restores the previous account if cloning or binding fails.
Import an existing repository identity without reading credentials, then apply a
profile automatically to every repository under a directory using native Git
includeIf rules:
gitbound profile import existing-work
gitbound directory add work ~/work
gitbound directory list
gitbound directory sync work
gitbound directory remove ~/work
Directory rules write marked profile fragments beside GitBound's configuration and add an exact global include. Removal deletes only that exact include and only removes fragments carrying GitBound's marker.
The desktop app lists, adds, and removes the same rules under Settings, and shows
each rule's includeIf key so it can be checked against git config --global --list.
It also clones (Repositories → Clone) and audits commit authorship (repository
details → Commit authorship), so the CLI and the app now cover the same ground.
For HTTPS remotes, configure GitHub CLI as Git's credential helper:
gh auth setup-git --hostname github.com
For SSH remotes, GitBound writes a repository-local core.sshCommand using the profile key and IdentitiesOnly=yes.
Safety hooks
Hooks are opt-in and GitBound never replaces or chains an existing hook setup:
gitbound hooks install
gitbound hooks status
gitbound hooks uninstall
Each subcommand takes --repo <path> to target a repository other than the current directory. The desktop app offers the same three actions on a repository's details page, under Commit hooks.
The pre-commit hook performs local author and policy checks. The pre-push hook performs full GitHub CLI and SSH verification and fails closed when a network-dependent identity cannot be verified.
Continuous integration
The same checks run in a pipeline. verify is check with defaults suited to a
runner; audit inspects who actually authored a range of commits, which is
evidence a developer's machine does not have.
- uses: BitKiln/GitBound@v1
with:
version: "1.0.0"
command: both
sarif-file: gitbound.sarif
gitbound verify --format github --output sarif:gitbound.sarif
gitbound audit --range origin/main..HEAD
--format accepts human, json, sarif, junit, github, markdown, and
auto — which selects GitHub workflow commands inside a runner and human output
everywhere else. --output is repeatable and each entry may name its own format,
so one inspection can feed several consumers.
A repository can commit a .gitbound.toml declaring which addresses, hosts,
and owners it accepts. GitBound reads that file and never writes it, and an
absent file leaves behaviour unchanged. See docs/CI.md.
Configuration
Configuration is stored in the platform-native user configuration directory. Override the location with GITBOUND_CONFIG for portable or test setups.
= 3
= ["/home/alice/projects"]
[]
= "alice-company"
= "Alice Developer"
= "alice@company.example"
= "github.com"
= "github.com-company"
= "~/.ssh/id_ed25519_company"
= ["company-name"]
= "ABC123"
= "openpgp"
= true
hostname is the real GitHub host, and it is what the GitHub CLI, HTTPS remote
URLs, and the credential helper are keyed by. ssh_host is optional and holds
the Host alias from your SSH configuration when you keep one account per
alias; it is used only to build and match SSH remote URLs, and it defaults to
hostname when omitted. A configuration written before schema 3 that stored an
alias in hostname is migrated automatically on first read.
Profiles can require OpenPGP or SSH commit signing. Binding snapshots and applies
user.signingKey, gpg.format, and commit.gpgSign; unbinding restores their
original repository-local values exactly.
Generate shell completions without modifying shell configuration:
gitbound completions bash > gitbound.bash
gitbound completions powershell > _gitbound.ps1
Repository binding and rollback metadata live only in local Git configuration. gitbound unbind restores the exact values that existed before the first bind.
Exit codes
0: success1: identity or policy check failed2: invalid input or configuration3: missing dependency or subprocess failure
Development
cargo fmt --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo deny check
cargo build --release -p gitbound-desktop
Contributing
Pull requests are welcome. CONTRIBUTING.md covers the branch model, what CI runs, and the frontend/backend contract that the desktop app depends on; participation is governed by our Code of Conduct.
One rule is worth repeating outside that document: a check that reports ok
while the push would go out under the wrong identity is a security bug, not a
correctness nit. Report those privately through the
security policy.
License
MIT — see LICENSE. Third-party notices are recorded in NOTICE.