Go library and CLI for working with git forges. Supports GitHub, GitLab, Gitea/Forgejo, and Bitbucket Cloud through a single interface.
brew install git-pkgs/git-pkgs/forge
Or with Go:
go install github.com/git-pkgs/forge/cmd/forge@latest
The CLI detects which forge to use from your git remote, or you can set it with --forge-type.
forge repo view
forge issue list --state open
forge pr create --title "Fix bug" --head fix-branch
forge pr review approve 42
forge pr reviewer request 42 alice bob
forge release list
forge ci list
forge ci log 67890
forge branch list
forge label list
forge notification list --unread
forge notification read --id 123
forge api repos/{owner}/{repo}
Run forge --help for the full command list.
Store tokens with forge auth login:
forge auth login # interactive: asks domain + token
forge auth login --domain github.com --token ghp_abc123
forge auth login --domain gitea.example.com --token abc123 --type gitea
forge auth login --domain github.com --token-cmd 'rbw get github-token'
--token-cmd stores a shell command instead of a literal token; the command
is run each time the token is needed (see token commands below).
When prompted for a token interactively, press Ctrl+E as the first key to enter a command instead:
Token for github.com (Ctrl+E first for command):
Command for token (e.g. rbw get github.com): rbw get github-token
Check what's configured with forge auth status.
Tokens are resolved in this order: CLI flags, environment variables (FORGE_TOKEN, GITHUB_TOKEN/GH_TOKEN, GITLAB_TOKEN, FORGEJO_TOKEN/GITEA_TOKEN, BITBUCKET_TOKEN), then the config file at ~/.config/forge/config. The target host is inferred from the current directory's git remote; use --host or FORGE_HOST to override it (for example forge --host gitea.com repo list someone).
Two config files, both INI-style:
~/.config/forge/config stores tokens and user preferences (respects XDG_CONFIG_HOME):
[default] output = json [github.com] token = ghp_abc123 [gitea.example.com] type = gitea token = abc123
Instead of a literal token, use token-cmd to specify a shell command.
The command is executed via sh -c (Unix) or %COMSPEC% /c (Windows) each
time forge needs the token and its stdout is used as the value. This lets you
fetch secrets from a password manager instead of storing them in plain text:
[github.com] token-cmd = rbw get github-token [gitlab.com] token-cmd = pass show forge/gitlab [myhostedgitlab.example.com] token-cmd = rbw get --raw myhostedgitlab | jq -r '.fields | map(select(.name == "token"))[0].value'
The variable FORGE_DOMAIN is set to the domain name when the command runs
(reference it as $FORGE_DOMAIN on Unix, %FORGE_DOMAIN% on Windows), so a
single command can serve multiple domains:
[github.com] token-cmd = pass show forge/$FORGE_DOMAIN [myhostedgitlab.example.com] token-cmd = pass show forge/$FORGE_DOMAIN
forge auth login sets this up interactively (Ctrl+E at the token prompt).
forge auth status shows the command source instead of the resolved value.
.forge in the repo root is for per-project settings, committed to the repo, no tokens:
[default] forge-type = gitlab [gitlab.internal.dev] type = gitlab
This tells forge that the project uses GitLab and that gitlab.internal.dev is a GitLab instance, so contributors don't each need --forge-type or FORGE_HOST.
Precedence from highest to lowest: CLI flags, environment variables, .forge, ~/.config/forge/config, built-in defaults.
import "github.com/git-pkgs/forge"
client := forges.NewClient( forges.WithToken("github.com", os.Getenv("GITHUB_TOKEN")), forges.WithToken("gitlab.com", os.Getenv("GITLAB_TOKEN")), ) repo, err := client.FetchRepository(ctx, "https://github.com/octocat/hello-world")
The Forge interface exposes services for repos, issues, pull requests, reviews, releases, CI, branches, labels, milestones, deploy keys, secrets, notifications, files, collaborators, and commit statuses. Each backend implements these using its native SDK.
f, _ := client.ForgeFor("github.com") issues, _ := f.Issues().List(ctx, "octocat", "hello-world", forges.ListIssueOpts{State: "open"}) pr, _ := f.PullRequests().Get(ctx, "octocat", "hello-world", 42)
Self-hosted instances can be registered explicitly or detected automatically:
import ( "github.com/git-pkgs/forge/gitea" "github.com/git-pkgs/forge/gitlab" ) client := forges.NewClient( forges.WithForge("gitea.example.com", gitea.New("https://gitea.example.com", token, nil)), forges.WithForge("gitlab.internal.dev", gitlab.New("https://gitlab.internal.dev", token, nil)), ) // or auto-detect the forge type err := client.RegisterDomain(ctx, "git.example.com", token, forges.ForgeBuilders{ GitHub: github.NewWithBase, GitLab: gitlab.New, Gitea: gitea.New, })
PURL support via github.com/git-pkgs/purl:
p, _ := purl.Parse("pkg:npm/lodash?repository_url=https://github.com/lodash/lodash") repo, err := client.FetchRepositoryFromPURL(ctx, p)
MIT. See LICENSE.