--- title: "Tangled" description: "Use Tangled, a forge built on atproto: issues, pulls, comments, live events and webhooks." canonical_url: "https://forgeslink-3mwmle35v-poetry.vercel.app/providers/tangled" --- # Tangled > Use Tangled, a forge built on atproto: issues, pulls, comments, live events and webhooks. The Tangled provider works with [Tangled](https://tangled.org), a forge built on atproto. It can read and write issues, pulls, comments, labels, assignees, reactions and collaborators, merge pulls, read profiles, read repository contents from the knot that hosts each repository, stream live events from Jetstream and verify incoming push webhooks. Tangled has no reviews, releases or security alerts, so those capabilities are `'not_applicable'`.
Detail Value
Import forges/tangled
Factories tangled()
Auth anonymous , app_password , oauth
The Tangled provider is experimental, because Tangled's lexicons are young and can still change. To learn what that means, see [Capabilities](https://forgeslink-3mwmle35v-poetry.vercel.app/concepts/capabilities). ## Authentication Reading is public and needs no credentials. Writing requires an atproto session, which you get from an app password or from an OAuth client: ```ts import { tangled } from 'forges/tangled' const reader = tangled({}) const writer = tangled({ auth: { type: 'app_password', identifier: 'alice.example.com', password: process.env.TANGLED_APP_PASSWORD!, }, }) ``` With `app_password`, the provider creates a session on the PDS (personal data server) of the account. It looks for the PDS in this order: 1. The `pds` option, if you pass it. 2. The DID document, if `identifier` is a DID. 3. `https://bsky.social`. With `oauth`, you pass the `did`, the `pds` and a `fetch` from an atproto OAuth client that signs requests: ```ts tangled({ auth: { type: 'oauth', did: session.did, pds: session.pds, fetch: session.fetch, }, }) ``` ## Instance and services The `baseUrl` defaults to `https://tangled.org`. The provider uses it for web links and as the instance. Tangled records are stored on many servers, so the provider has to read from several services. You can change each one of them with an option:
Option Reads Default
plcUrl DID documents, to find the PDS of each author https://plc.directory
backlinksUrl Records that point at a thread, such as comments https://constellation.microcosm.blue
handleResolverUrl The DID for a handle, when the owner of a ref is a handle https://public.api.bsky.app
recordsUrl Records, through a Slingshot-compatible cache The PDS of each author
jetstreamUrl The live event stream A public Bluesky Jetstream instance
None Repository contents, from the knot that the repo record names The repo's knot
apiUrl request() , listSource: 'index' , and star and fork counts https://api.tangled.org
## Refs and numbers Issues and pulls are atproto records, and they are identified by their AT-URI. In a `ThreadRef`, the AT-URI is both the `number` and the `externalId`. The `owner` of a repo is the DID of its owner, and `RepoRef.externalId` is the DID of the repo. In the refs that the provider returns, the `name` of a repo is the key of its repo record. For newer repos, that key differs from the name that people see, which `Repo.displayName` holds. You can also pass a ref that has a handle as `owner` and the visible name as `name`, which is what `parseUrl()` returns for a URL such as `https://tangled.org/@acme.example.com/widgets`. The provider resolves the handle and finds the record by its name, so the ref that it returns can differ from the one you passed. `parseUrl()` reads repository pages and the pages for threads (`/issues/{number}` and `/pulls/{number}`), commits (`/commit/{sha}`), files (`/blob/{ref}/{path}`) and comparisons (`/compare/{base}...{head}` or `/compare/{base}..{head}`). Tangled names a repository by the handle of its owner, so the provider reads the handle from the owner's DID document and reports it as `RepoRef.ownerHandle` and as the `login` of `Repo.owner`. The `owner` stays the DID, so that a repository is found the same way whichever is known. An owner whose DID document claims no handle is named by its DID, which Tangled redirects to the handle. `repos.byOwner()` reads the repo records of an account, which you name by its handle or DID. Every Tangled repo is public, and the records come back in their own order, so if you pass `sort`, you get a `sort_unsupported` warning. `repos.get()` also reports `stars` and `forks`, from `sh.tangled.feed.countStars` and `sh.tangled.repo.countForks` on the index at `apiUrl`. The index can lag behind the appview, so these counts can be lower than the ones in the Tangled UI. Each count is absent when the index can't return it. Listings of repositories don't include them. ## Thread numbers The numbers that you see in the Tangled UI and in webhooks come from the appview, because the records themselves don't store them. The provider reports them as `displayNumber`. The appview numbers a repository's issues and pulls separately. The provider reads the number from the appview's list of the repository's threads, at `/{owner}/{repo}/issues` and `/{owner}/{repo}/pulls`, and finds a thread in it by the account that opened it and by its title, and, where several threads share those, by the moment the appview saw them. A thread that the list does not name, or names ambiguously, has no `displayNumber` and no `url`. The list costs a request per hundred threads, plus one to reach its end, and is cached for the repository. To read one thread, the provider reads the list of the threads that its author opened first, and the whole list only when that one does not name it. Pass a `displayNumber` in the ref you give to `threads.get()` to use the number you know, such as the one a webhook carried. The web page of a thread carries that number, so `Thread.url` and the URLs of comments point at the page that the appview serves. In text, a thread is mentioned as `#`, which is the display number: the record's AT-URI is not known from the text alone, so `parseReferences()` returns a ref that carries `displayNumber`. `urlFor()` links that ref, and `referenceFor()` writes it back as `#`, or `owner/name#` for another repository, with the owner's handle where the ref carries one. A ref from a webhook has no `number` until it is matched to a record. To fill in `number` during `webhooks.ingest()`, pass a `resolveDisplayNumber(repo, kind, displayNumber)` function that returns the AT-URI. ## Thread state The state of a thread is the latest state record that was written by the author of the thread, the owner of the repo or a collaborator. The provider ignores state records from other accounts. If another account calls `close()` or `reopen()`, the call throws `InsufficientScopeError` and writes no record. `close()` and `reopen()` read the thread after writing the state record, and resolve with it in the state they wrote, even while the backlink index still lists the earlier state. ## Labels and assignees Labels are `sh.tangled.label.definition` records, and a thread's labels are the label ops that the owner of the repo or a collaborator wrote for it, applied in order. A label with a value, such as `priority`, appears as `priority:high`. Tangled stores assignees as an `assignee` label whose values are DIDs, so they appear in `assignees` rather than in `labels`. Each call to `setLabels()`, `addLabels()`, `removeLabels()` or `setAssignees()` writes one label op with what it adds and removes. `update()` packs `labels` and `assignees` into a single op too, and writes it before the state record and the thread edit, so a name the repo doesn't have stops it before anything changes. Only the owner of the repo or a collaborator can write one that counts, so for any other account these calls throw `InsufficientScopeError`. A name must match a label that the repo record lists, or the call throws `NotFoundError`. `createLabel()` writes a definition that applies to issues and pulls and adds it to the repo record, so only the owner of the repo can call it. The backlink index can take a while to list a new label op, so `setLabels()`, `addLabels()`, `removeLabels()` and `setAssignees()` don't read the labels back. They resolve with what the op leaves, worked out from the label ops they read before writing it. `repos.collaborators()` lists the owner of the repo with the role `admin` and each collaborator with the role `write`. `permissionFor()` returns `read` for any other account, because every Tangled repo is public. ## Listing threads By default, `threads.list()` reads every record and works out the state of each thread, which takes several requests per thread. If you set `listSource: 'index'`, it lists from the index at `apiUrl` instead. The index takes one request per page, but its states can lag behind the records, so every listing from the index has an `index_possibly_stale` warning. The index has no labels or assignees, so its threads have none, and it ignores the `labels` and `assignee` filters with a `filter_unsupported` warning. ## Repository contents The `contents` verbs read files, trees, branches, tags and commits from the knot that the repo record names, so they need no credentials. Knots list one level of a tree at a time, so `tree()` with `recursive` returns one level and a `recursive_unsupported` warning. Knots don't filter commits, so `commits()` ignores `path`, `author`, `since` and `until`, and warns with `filter_unsupported`. A pull carries its changes as a patch rather than as a branch. `threads.files()` and `threads.commits()` read the patch of the latest round. When several commits in the patch change the same file, that file's counts and patch are those of each commit together, and the listing has a `files_approximate` warning. ## Notifications Notifications use the `org.tangled.temp.notification.*` lexicons. These lexicons are in Tangled's temporary namespace and can change. To enable notifications, pass `auth` and set `notificationsUrl` to the base URL of the notification service. The notification capabilities are `'experimental'` then. Stars and follows have no thread. They appear with `kind: 'other'`, and `typeRaw` contains the type of the notification. ## Pulls and merging A pull carries a patch rather than a branch. `threads.create()` with `kind: 'pull_request'` asks the knot for the `git format-patch` of the commits that `head` has and `base` lacks, uploads it to your PDS and writes the pull record. `head` must be a branch of the same repository; pulls from forks and drafts aren't supported. `merge()` sends the patch of the latest round to the knot, which applies its commits to the target branch with `git am`, and then writes a `merged` status record. Because the commits are applied as they are, `rebase` is the only merge method, and `title` and `message` are ignored. Only the owner of the repository or a collaborator can merge. `repos.addCollaborator()` asks the knot to give an account push access. Tangled has a single collaborator role, so `role` must be `write`. ## Live events `sources.stream()` streams events from Jetstream, and each item has a `cursor`. To resume a stream later, save the cursor and pass it back: ```ts for await (const { event, cursor } of reader.sources.stream({ cursor: saved, signal, })) { console.log(event.kind, event.summary) saved = cursor } ``` To close the connection, abort the signal or break out of the loop. If the connection drops, the iterator throws `StreamClosedError` with the last cursor. The provider doesn't reconnect by itself, so call `stream()` again with that cursor. ## Activity feeds An account's issues, pull requests, comments, state changes, reactions and label changes are records in its own repository, so `users.events()` reads them from its PDS. It takes a handle or a DID. Each page lists every collection the account has records in, and merges them by record key, which orders them by when they were written. The events are the ones `sources.stream()` yields for the same records, with `source: 'poll'`. The first page's `etag` pairs the repository's revision with a digest of the records on that page. Pass it back as `cursor: { etag }`, with the same `perPage`, and you get a `notModified` page when nothing on it changed. An untouched revision takes a single request. A Bluesky post or a like moves the revision too, so the feed lists the records again, sees the same page and still answers `notModified` before it resolves a single thread. A chatty Bluesky account doesn't cost a full read on every poll. An edit to a record on the page does count as a change. The feed lists the records as they are now, so deleted records don't appear, and an edited record appears once. Tangled has no feed of a repository's activity, because each contributor's records are in their own repository, and pushes go to the knot. `repos.events()` isn't available. ## Webhooks To verify deliveries, set `webhookSecret` to the secret that you configured on the hook: ```ts const forge = tangled({ webhookSecret: process.env.TANGLED_WEBHOOK_SECRET, }) const events = await forge.webhooks.ingest({ headers: request.headers, body: await request.text(), }) ``` With each delivery, Tangled sends these headers:
Header Content
X-Tangled-Signature-256 sha256= followed by the hex HMAC-SHA256 of the body
X-Tangled-Event The event name
X-Tangled-Delivery The delivery ID
A `push` delivery becomes a `push` or `ref` event. Tangled has no API to register hooks, so the management methods of `webhooks` aren't available. ## Capabilities
Capability Support Without credentials
experimental ✅ ✅
sources.stream ✅ ✅
repos.get ✅ ✅
users.get ✅ ✅
users.me ✅ ❌
users.sponsorable ❌ ❌
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 issue, PR issue, PR
threads.comments issue, PR issue, PR
threads.getComment issue (emulated), PR (emulated) issue (emulated), PR (unverified)
threads.createComment issue, PR ❌
threads.updateComment issue, PR ❌
threads.deleteComment issue, PR ❌
threads.hideComment ∅ ∅
threads.reactions issue, PR issue, PR
threads.react issue, PR ❌
threads.create issue, PR ❌
threads.update issue, PR ❌
threads.close issue, PR ❌
threads.reopen issue, PR ❌
threads.lock ∅ ∅
threads.setLabels issue, PR ❌
threads.addLabels issue, PR ❌
threads.removeLabels issue, PR ❌
threads.setMilestone ❌ ❌
threads.setIssueType ∅ ∅
threads.setAssignees issue, PR ❌
threads.requestReview ∅ ∅
threads.merge ✅ ❌
threads.updateBranch ∅ ∅
threads.transfer ❌ ❌
threads.markDuplicate ❌ ❌
threads.subscription issue, PR ❌
threads.subscribe issue, PR ❌
threads.checks ∅ ∅
threads.files ✅ ✅
threads.commits ✅ ✅
threads.reviews ∅ ∅
threads.getReview ∅ ∅
threads.createReview ∅ ∅
threads.submitReview ∅ ∅
threads.approve ∅ ∅
threads.replyToReviewComment ∅ ∅
threads.reviewThreads ∅ ∅
threads.resolveReviewThread ∅ ∅
notifications.list experimental ❌
notifications.markRead experimental ❌
notifications.markDone ❌ ❌
notifications.unsubscribe ❌ ❌
notifications.markAllRead unverified ❌
notifications.markAllDone ❌ ❌
notifications.unreadCount unverified ❌
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 anonymous , app_password , oauth anonymous , app_password , oauth
limits unknown unknown
## Sitemap See the full [sitemap](https://forgeslink-3mwmle35v-poetry.vercel.app/sitemap.md) for all pages.