--- title: "Tangled" description: "Use Tangled, a forge built on atproto: issues, pulls, comments, live events and webhooks." canonical_url: "https://forges.link/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, so those capabilities are `false`.
Detail Value
Import forges/tangled
Factories tangled() , tangledLite()
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://forges.link/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({}).create() const writer = tangled({ auth: { type: 'app_password', identifier: 'alice.example.com', password: process.env.TANGLED_APP_PASSWORD!, }, }).create() ``` 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. `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. 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`. 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. Tangled has no review step, so `approveAndMerge()` isn't available. `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.subscribe()` 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.subscribe({ 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 `SubscriptionClosedError` with the last cursor. The provider doesn't reconnect by itself, so call `subscribe()` 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.subscribe()` 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, }).create() 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.poll experimental ❌
sources.webhook ✅ ✅
sources.subscribe ✅ ✅
repos.get ✅ ✅
users.get ✅ ✅
users.me ✅ ❌
users.sponsorable ❌ ❌
users.events ✅ ✅
repos.list ✅ ❌
repos.byOwner ✅ ✅
repos.labels ✅ ✅
repos.createLabel ✅ ❌
repos.milestones ❌ ❌
repos.collaborators ✅ ✅
repos.contributors ❌ ❌
repos.contributorStats ❌ ❌
repos.templates ❌ ❌
repos.permissionFor ✅ ✅
repos.addCollaborator ✅ ❌
repos.assignableUsers ❌ ❌
repos.reviewerCandidates ❌ ❌
repos.events ❌ ❌
orgs.teams ❌ ❌
orgs.teamMembers ❌ ❌
threads.get issue, PR issue, PR
threads.list issue, PR issue, PR
threads.getMany ✅ ✅
threads.events issue, PR issue, PR
comments.list issue, PR issue, PR
comments.get issue (emulated), PR (emulated) issue (emulated), PR (emulated)
comments.edit issue, PR ❌
comments.delete issue, PR ❌
reactions.list issue, PR issue, PR
notifications.list experimental ❌
notifications.markRead experimental ❌
notifications.markDone ❌ ❌
notifications.unsubscribe ❌ ❌
notifications.markAllRead unverified ❌
notifications.markAllDone ❌ ❌
notifications.unreadCount unverified ❌
writes.comment issue, PR ❌
writes.upsertComment issue (emulated), PR (emulated) ❌
writes.close issue, PR ❌
writes.reopen issue, PR ❌
writes.create issue, PR ❌
writes.update issue, PR ❌
writes.setLabels issue, PR ❌
writes.addLabels issue, PR ❌
writes.removeLabels issue, PR ❌
writes.setMilestone ❌ ❌
writes.react issue, PR ❌
writes.setAssignees issue, PR ❌
writes.requestReview ❌ ❌
writes.merge ✅ ❌
writes.approveAndMerge ❌ ❌
writes.transfer ❌ ❌
writes.markDuplicate ❌ ❌
subscriptions.get issue, PR ❌
subscriptions.set issue, PR ❌
installations ❌ ❌
checks.thread ❌ ❌
checks.list ❌ ❌
checks.get ❌ ❌
checks.report ❌ ❌
checks.rerun ❌ ❌
ci.runs ❌ ❌
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 ❌ ❌
releases.get ❌ ❌
releases.latest ❌ ❌
releases.getByTag ❌ ❌
releases.downloadAsset ❌ ❌
releases.create ❌ ❌
releases.update ❌ ❌
webhooks.list ❌ ❌
webhooks.create ❌ ❌
webhooks.update ❌ ❌
webhooks.delete ❌ ❌
webhooks.rotateSecret ❌ ❌
webhooks.deliveries ❌ ❌
webhooks.redeliver ❌ ❌
search.threads ❌ ❌
search.repos ❌ ❌
search.commits ❌ ❌
search.code ❌ ❌
securityAlerts ❌ ❌
eventKinds native native
authKinds anonymous , app_password , oauth anonymous , app_password , oauth
limits unknown unknown
## Sitemap See the full [sitemap](https://forges.link/sitemap.md) for all pages.