--- title: "Sourcehut" description: "Use Sourcehut: repositories, file contents, issues (todo.sr.ht), patchsets (lists.sr.ht) and builds." canonical_url: "https://forges.link/providers/sourcehut" --- # Sourcehut > Use Sourcehut: repositories, file contents, issues (todo.sr.ht), patchsets (lists.sr.ht) and builds. The Sourcehut provider works with [Sourcehut](https://sr.ht), a suite of small services that share one account and one OAuth 2.0 token. Reading a repository uses `git.sr.ht`, its issues use `todo.sr.ht`, its patches use `lists.sr.ht`, its builds use `builds.sr.ht`, and accounts use `meta.sr.ht`. The provider fans requests out across those services for you and normalises them into the shared [data model](https://forges.link/concepts/data-model).
Detail Value
Import forges/sourcehut
Factories sourcehut() , sourcehutLite()
Auth token
This provider is read-only. It declares every write, notification and subscription change unsupported, and it does not create, edit or delete anything. ## Authentication Create a [personal access token](https://meta.sr.ht/oauth2) and grant it the scopes of the services you need, one grant per service and scope, such as `git.sr.ht/REPOSITORIES:RO` or `todo.sr.ht/TICKETS:RO`. The provider sends the token as `Authorization: Bearer `: ```ts import { sourcehut } from 'forges/sourcehut' const forge = sourcehut({ auth: { type: 'token', token: process.env.SOURCEHUT_TOKEN! }, }).create() ``` An OAuth 2.0 bearer token works too. Every service refuses reads without a token, so unlike most providers there are no anonymous reads. ## Instance The `baseUrl` defaults to `https://sr.ht`. Each service is a subdomain of that host, so `https://sr.ht` gives `git.sr.ht`, `todo.sr.ht`, `lists.sr.ht`, `builds.sr.ht` and `meta.sr.ht`. On a self-hosted instance, set `baseUrl` to the instance root and the services are derived the same way. Sourcehut usernames are written with a leading tilde, so a repository ref's `owner` is `~sircmpwn` and a slug is `~sircmpwn/scdoc`. ## Repositories and contents `repos.get()`, `repos.list()` and `repos.byOwner()` read `git.sr.ht`. `contents.file()`, `contents.tree()`, `contents.branches()`, `contents.tags()`, `contents.resolveRef()`, `contents.commits()` and `contents.commit()` read the same service. Sourcehut has no compare resolver, so `contents.compare()` is unsupported. `repos.labels()` and `repos.permissionFor()` are `'emulated'` from the repository's `todo.sr.ht` tracker and its `git.sr.ht` access list. The access list is served only to the repository's owner and collaborators, so for anyone else `permissionFor()` falls back to what the repository's visibility allows. Sourcehut has no milestones, contributors, contributors statistics, assignable users or reviewer candidates. ## Issues Issues live in a `todo.sr.ht` tracker whose name matches the repository, so `~sircmpwn/scdoc` reads the tracker `~sircmpwn/scdoc`. `threads.get()`, `threads.list()`, `threads.comments()`, `threads.events()` and `threads.getMany()` all work on them, and `threads.subscription()` reports whether the account is subscribed. Comments are the comment entries of a ticket's events, which is the endpoint the API exposes. Sourcehut has no reactions and no comment editing over the API. ## Patchsets Sourcehut's equivalent of a pull request is a patchset on a mailing list. There is no way to tell which list belongs to a repository, so a patch ref's `repo` names the **mailing list**, not the git repository. `threads.get()` reads a patchset by id, `threads.list()` lists a list's patchsets, and `threads.comments()` and `threads.events()` read the replies to its thread. Patchsets carry no reviews, files, commits or checks. ## Builds `builds.sr.ht` lists the builds of the authenticated account, not of one repository, so `ci.runs()` is `'emulated'` and warns that it ignores the repository. `ci.run()` reads one build, `ci.jobs()` lists its tasks, and `ci.log()` streams a task's log. A job ref must name its run, because a task has no top-level resolver. ## Accounts `users.get(login)` and `users.me()` read `meta.sr.ht`. Both need the token, because `meta.sr.ht`'s account resolvers reject a token on the anonymous query and require one on the authenticated query. Sourcehut has no sponsorship, follow feeds or repository events. ## Webhooks Sourcehut signs deliveries with its own ed25519 key rather than a shared secret: `X-Payload-Signature` is the signature of the raw body followed by the `X-Payload-Nonce` header. The provider verifies it against the instance's published public key, which defaults to `sr.ht`'s and can be overridden with `webhookPublicKey` for another instance. Because a Sourcehut webhook sends the result of a GraphQL query that you register with it, the provider translates the shape it documents for repository and push events. Managing hooks is not implemented. The webhook code is separate, so `sourcehutLite()` creates the same provider without it, for a browser bundle. ## Capabilities
Capability Support Without credentials
experimental ❌ ❌
sources.poll ❌ ❌
sources.webhook ✅ ❌
sources.subscribe ❌ ❌
repos.get ✅ ❌
users.get ✅ ❌
users.me ✅ ❌
users.sponsorable ❌ ❌
users.events ❌ ❌
users.block ❌ ❌
repos.list ✅ ❌
repos.byOwner ✅ ❌
repos.labels emulated ❌
repos.createLabel ❌ ❌
repos.milestones ❌ ❌
repos.collaborators ✅ ❌
repos.contributors ❌ ❌
repos.contributorStats ❌ ❌
repos.templates ❌ ❌
repos.permissionFor emulated ❌
repos.addCollaborator ❌ ❌
repos.assignableUsers ❌ ❌
repos.reviewerCandidates ❌ ❌
repos.events ❌ ❌
orgs.teams ❌ ❌
orgs.teamMembers ❌ ❌
orgs.block ❌ ❌
threads.get issue, PR ❌
threads.list issue, PR ❌
threads.getMany ✅ ❌
threads.closingIssues ❌ ❌
threads.closingPullRequests ❌ ❌
threads.events issue, PR ❌
comments.list issue, PR ❌
comments.get issue, PR ❌
comments.edit ❌ ❌
comments.delete ❌ ❌
comments.hide ❌ ❌
reactions.list ❌ ❌
notifications.list ❌ ❌
notifications.markRead ❌ ❌
notifications.markDone ❌ ❌
notifications.unsubscribe ❌ ❌
notifications.markAllRead ❌ ❌
notifications.markAllDone ❌ ❌
notifications.unreadCount ❌ ❌
writes.comment ❌ ❌
writes.upsertComment ❌ ❌
writes.close ❌ ❌
writes.reopen ❌ ❌
writes.lock ❌ ❌
writes.create ❌ ❌
writes.update ❌ ❌
writes.setLabels ❌ ❌
writes.addLabels ❌ ❌
writes.removeLabels ❌ ❌
writes.setMilestone ❌ ❌
writes.react ❌ ❌
writes.setAssignees ❌ ❌
writes.requestReview ❌ ❌
writes.merge ❌ ❌
writes.approveAndMerge ❌ ❌
writes.updateBranch ❌ ❌
writes.transfer ❌ ❌
writes.markDuplicate ❌ ❌
subscriptions.get issue ❌
subscriptions.set ❌ ❌
installations ❌ ❌
checks.thread ❌ ❌
checks.list ❌ ❌
checks.get ❌ ❌
checks.report ❌ ❌
checks.rerun ❌ ❌
ci.runs emulated ❌
ci.run ✅ ❌
ci.jobs ✅ ❌
ci.job ✅ ❌
ci.log ✅ ❌
contents.file ✅ ❌
contents.tree ✅ ❌
contents.branches ✅ ❌
contents.tags ✅ ❌
contents.resolveRef ✅ ❌
contents.commits ✅ ❌
contents.commit ✅ ❌
contents.compare ❌ ❌
contents.commitFiles ❌ ❌
contents.threadFiles ❌ ❌
contents.threadCommits ❌ ❌
reviews.list ❌ ❌
reviews.get ❌ ❌
reviews.create ❌ ❌
reviews.submit ❌ ❌
reviews.approve ❌ ❌
reviews.reply ❌ ❌
reviews.resolveThread ❌ ❌
releases.list emulated ❌
releases.get emulated ❌
releases.latest emulated ❌
releases.getByTag emulated ❌
releases.downloadAsset emulated ❌
releases.create ❌ ❌
releases.update ❌ ❌
webhooks.list ❌ ❌
webhooks.create ❌ ❌
webhooks.update ❌ ❌
webhooks.delete ❌ ❌
webhooks.rotateSecret ❌ ❌
webhooks.deliveries ❌ ❌
webhooks.redeliver ❌ ❌
search.threads ❌ ❌
search.repos emulated ❌
search.commits ❌ ❌
search.code experimental ❌
securityAlerts ❌ ❌
eventKinds native native
authKinds token token
limits unknown unknown
## Sitemap See the full [sitemap](https://forges.link/sitemap.md) for all pages.