--- title: "GitBucket" description: "Use a self-hosted GitBucket server through the part of GitHub's REST API that it serves: issues, pull requests, statuses, releases and webhooks." canonical_url: "https://forges.link/providers/gitbucket" --- # GitBucket > Use a self-hosted GitBucket server through the part of GitHub's REST API that it serves: issues, pull requests, statuses, releases and webhooks. The GitBucket provider works with self-hosted GitBucket servers. GitBucket is a Git platform written in Scala, and it isn't related to Atlassian's [Bitbucket](https://forges.link/providers/bitbucket). It serves part of GitHub's REST API v3, so this provider runs the code of the [GitHub provider](https://forges.link/providers/github) against it and leaves out what GitBucket doesn't serve. Refs from this provider have `forge: 'gitbucket'`.
Detail Value
Import forges/gitbucket
Factories gitbucket()
Auth token , anonymous
The capabilities on this page are verified against recordings of a GitBucket 4.48.0 server. Other versions of GitBucket can serve more or less of the API. To learn what the levels mean, see [Capabilities](https://forges.link/concepts/capabilities). ## Authentication The provider accepts a personal access token, which you create under **Account settings > Applications** on your server. GitBucket tokens have no scopes, so a token can do whatever its account can: ```ts import { gitbucket } from 'forges/gitbucket' const forge = gitbucket({ baseUrl: 'https://gitbucket.example.com', auth: { type: 'token', token: process.env.GITBUCKET_TOKEN! }, }) ``` If you leave out `auth`, the provider makes anonymous reads of public data. ## Instance GitBucket has no public instance, so `baseUrl` is required. Set it to the root of your server, including the context path if GitBucket runs under one, such as `https://example.com/gitbucket`. The provider appends `/api/v3` itself. The `instance` in every ref defaults to the host of the server. Two GitBucket servers on one host, under different context paths, need an `instance` each, because a [registry](https://forges.link/guides/multiple-forges) takes one provider per forge and instance. Give it the shape of a host, without a slash, since refs and keys carry it: ```ts import { createForges, gitbucket } from 'forges' const forges = createForges([ gitbucket({ baseUrl: 'https://example.com/team', instance: 'team.example.com' }), gitbucket({ baseUrl: 'https://example.com/lab', instance: 'lab.example.com' }), ]) ``` ## What GitBucket leaves out GitBucket has no GraphQL, no check runs, no Actions, no reviews, no reactions and no search. It doesn't serve notifications, activity feeds, contributors, branch rules, comparisons, trees or commit comments either. `support()` reports each of those as `false`, or as `'not_applicable'` where GitBucket has no such feature at all, and calling one rejects with `UnsupportedOperationError` before any request goes out. The [capability matrix](https://forges.link/reference/capability-matrix) has the full list. Some operations that GitBucket does serve still aren't supported, because the provider couldn't do what they promise. They reject with `UnsupportedOperationError` before any request goes out as well, and this is what GitBucket's endpoints do with them: - `threads.setAssignees()` and `setMilestone()`, and `update()`, `close()` and `reopen()` on an issue, need GitBucket to edit an issue, which its API can't do. A pull request is different: `update()`, `close()` and `reopen()` work, for its title, body and state. - `threads.create()` of a pull request with `labels` or `assignees`, and `threads.update()` of a pull request with either: GitBucket can't set them as part of the change. Open or update the pull request without them, then set its labels with `setLabels()`. - `threads.deleteComment()`: GitBucket deletes the comment, but responds with the comment's id as the HTTP status code, so a deletion looks like a failed request. - `repos.collaborators()` and `repos.addCollaborator()`: GitBucket lists collaborators without a role, and fails with a `500` for the roles that GitHub has beyond read, write and admin. - `releases.create()` and `releases.update()`: GitBucket creates a release without its tag and drops `draft`, `prerelease` and `target`, and it updates a release only when it gets the whole of it. - `webhooks.update()` and `webhooks.rotateSecret()`: GitBucket updates a hook only when it gets the whole of it, while the provider sends only what changes. ## Listing threads GitBucket lists issues and pull requests apart, so pass `kind` to `threads.list()`. Without it, you get the issues and a `kind_unsupported` warning. GitBucket returns 25 threads to a page, whatever `perPage` asks for, and filters milestones by their title. It has no `since` or `involves` filter, so those come back with a `filter_unsupported` warning. GitBucket ignores `sort` and `direction`, so the provider sorts each page itself. The pages themselves come in GitBucket's order, so a thread on the second page can sort before one on the first. `threads.getMany()` reads each thread on its own, since GitBucket has no GraphQL to batch the reads with. ## Commits GitBucket skips commits from the second page of a listing on, so `commits.list()` returns a single page. When that page is full, the result has no cursor and carries a `commits_truncated` warning. To see further back, narrow the listing with `since`, `until` or `path`, or raise `perPage`, up to 100. ## Checks GitBucket has commit statuses but no check runs, so the `checks` of a pull request are its statuses, and their `url` is the pull request's page, where GitBucket shows them. ## Releases GitBucket gives a release no id, so the `id` of a release ref is its tag. `releases.get()` reads the release by that tag. ## Merging `merge()` takes the `merge`, `squash` and `rebase` methods. Without a `method`, GitBucket creates a merge commit. GitBucket writes the first line of the commit message itself, so `title` goes above `message` in the body of the message. GitBucket responds to every merge with HTTP `200` and puts the real outcome in the response body. The provider reads that outcome, so a conflict rejects with `MergeConflictError`. A closed or draft pull request, or a method that the repository doesn't allow, rejects with `MergeBlockedError`. GitBucket ignores the head a merge expects and has no auto-merge, so `sha` and `whenChecksPass` reject with `UnsupportedOperationError`. ## Labels GitBucket fails with a `500` when it adds a label that the thread already has. `threads.addLabels()` reads the labels first and sends only the ones that the thread lacks, and `threads.removeLabels()` sends only the ones that it has. Both read the labels again afterwards, because GitBucket responds with only the labels that it changed. ## Webhooks GitBucket signs its deliveries like GitHub, with `X-Hub-Signature-256`, so `webhooks.verify()` and `webhooks.ingest()` work as they do on GitHub. It sends comments, review comments, issue and pull request changes, pushes, new branches and tags, and wiki edits, so `webhooks.create()` subscribes only to those. It accepts a few more event names that it never sends, and responds to a name it doesn't know with a `500`. ## Capabilities
Capability Support Without credentials
experimental ❌ ❌
sources.stream ❌ ❌
repos.get ✅ ✅
users.get ✅ ✅
users.me ✅ ❌
users.sponsorable ∅ ∅
users.sponsorableMany ∅ ∅
users.events ❌ ❌
users.block ∅ ∅
repos.list ❌ ❌
repos.byOwner ✅ ✅
repos.labels ✅ ✅
repos.createLabel ✅ ❌
repos.milestones ✅ ✅
repos.issueTypes ∅ ∅
repos.collaborators ❌ ❌
repos.contributors ❌ ❌
repos.contributorStats ❌ ❌
repos.templates ✅ ✅
repos.permissionFor ❌ ❌
repos.branchRules ❌ ❌
repos.addCollaborator ❌ ❌
repos.assignableUsers ❌ ❌
repos.reviewerCandidates ∅ ∅
repos.events ❌ ❌
orgs.teams ∅ ∅
orgs.teamMembers ∅ ∅
orgs.block ∅ ∅
threads.get issue, PR issue, PR
threads.list issue, PR issue, PR
threads.getMany ✅ ✅
threads.closingIssues ❌ ❌
threads.closingPullRequests ❌ ❌
threads.events ❌ ❌
threads.comments issue, PR issue, PR
threads.getComment issue, PR issue, PR
threads.createComment issue, PR ❌
threads.updateComment issue, PR ❌
threads.deleteComment ❌ ❌
threads.hideComment ∅ ∅
threads.reactions ∅ ∅
threads.react ∅ ∅
threads.create issue, PR ❌
threads.update PR ❌
threads.close PR ❌
threads.reopen PR ❌
threads.lock ∅ ∅
threads.setLabels issue, PR ❌
threads.addLabels issue, PR ❌
threads.removeLabels issue, PR ❌
threads.setMilestone ❌ ❌
threads.setIssueType ∅ ∅
threads.setAssignees ❌ ❌
threads.requestReview ∅ ∅
threads.merge ✅ ❌
threads.updateBranch ❌ ❌
threads.transfer ∅ ∅
threads.markDuplicate ∅ ∅
threads.subscription ❌ ❌
threads.subscribe ❌ ❌
threads.checks PR PR
threads.files ❌ ❌
threads.commits ✅ ✅
threads.reviews ❌ ❌
threads.getReview ❌ ❌
threads.createReview ❌ ❌
threads.submitReview ❌ ❌
threads.approve ❌ ❌
threads.replyToReviewComment ❌ ❌
threads.reviewThreads ❌ ❌
threads.resolveReviewThread ❌ ❌
notifications.list ❌ ❌
notifications.markRead ❌ ❌
notifications.markDone ❌ ❌
notifications.unsubscribe ❌ ❌
notifications.markAllRead ❌ ❌
notifications.markAllDone ❌ ❌
notifications.unreadCount ❌ ❌
installations.list ❌ ❌
checks.list ✅ ✅
checks.get ∅ ∅
checks.report ✅ ❌
checks.rerun ∅ ∅
ci.runs ∅ ∅
ci.getRun ∅ ∅
ci.jobs ∅ ∅
ci.getJob ∅ ∅
ci.log ∅ ∅
ci.rerunFailed ∅ ∅
contents.getFile ✅ ✅
contents.tree ❌ ❌
contents.branches ✅ ✅
contents.tags ✅ ✅
contents.resolveRef ✅ ✅
contents.compare ❌ ❌
contents.commitFiles ❌ ❌
commits.list ✅ ✅
commits.get ✅ ✅
commits.comments ❌ ❌
commits.getComment ❌ ❌
commits.createComment ❌ ❌
commits.updateComment ❌ ❌
commits.deleteComment ❌ ❌
commits.hideComment ∅ ∅
releases.list ✅ ✅
releases.get ✅ ✅
releases.latest ✅ ✅
releases.getByTag ✅ ✅
releases.downloadAsset ❌ ❌
releases.create ❌ ❌
releases.update ❌ ❌
webhooks.ingest ✅ ✅
webhooks.list ✅ ❌
webhooks.create ✅ ❌
webhooks.update ❌ ❌
webhooks.delete ✅ ❌
webhooks.rotateSecret ❌ ❌
webhooks.deliveries ❌ ❌
webhooks.redeliver ❌ ❌
search.threads ❌ ❌
search.repos ❌ ❌
search.commits ❌ ❌
search.code ❌ ❌
securityAlerts.list ∅ ∅
eventKinds native native
authKinds token , anonymous token , anonymous
limits body 65536, comment 65536, label 50 body 65536, comment 65536, label 50
## Sitemap See the full [sitemap](https://forges.link/sitemap.md) for all pages.