alice.pds.demo.boltless.dev / core
This repository has no description
0
Fork 0

Configure Feed

Select the types of activity you want to include in your feed.

core / docs / DOCS.md
68 kB 2315 lines
1--- 2title: Tangled docs 3author: The Tangled Contributors 4date: 21 Sun, Dec 2025 5abstract: | 6 Tangled is a decentralized code hosting and collaboration 7 platform. Every component of Tangled is open-source and 8 self-hostable. [tangled.org](https://tangled.org) also 9 provides hosting and CI services that are free to use. 10 11 There are several models for decentralized code 12 collaboration platforms, ranging from ActivityPub’s 13 (Forgejo) federated model, to Radicle’s entirely P2P model. 14 Our approach attempts to be the best of both worlds by 15 adopting the AT Protocol—a protocol for building decentralized 16 social applications with a central identity 17 18 Our approach to this is the idea of “knots”. Knots are 19 lightweight, headless servers that enable users to host Git 20 repositories with ease. Knots are designed for either single 21 or multi-tenant use which is perfect for self-hosting on a 22 Raspberry Pi at home, or larger “community” servers. By 23 default, Tangled provides managed knots where you can host 24 your repositories for free. 25 26 The appview at tangled.org acts as a consolidated "view" 27 into the whole network, allowing users to access, clone and 28 contribute to repositories hosted across different knots 29 seamlessly. 30--- 31 32# Quick start guide 33 34## Login or sign up 35 36You can [login](https://tangled.org) by using your AT Protocol 37account. If you are unclear on what that means, simply head 38to the [signup](https://tangled.org/signup) page and create 39an account. By doing so, you will be choosing Tangled as 40your account provider (you will be granted a handle of the 41form `user.tngl.sh`). 42 43In the AT Protocol network, users are free to choose their account 44provider (known as a "Personal Data Service", or PDS), and 45login to applications that support AT accounts. 46 47You can think of it as "one account for all of the atmosphere"! 48 49If you already have an AT account (you may have one if you 50signed up to Bluesky, for example), you can login with the 51same handle on Tangled (so just use `user.bsky.social` on 52the login page). 53 54## Add an SSH key 55 56Once you are logged in, you can start creating repositories 57and pushing code. Tangled supports pushing git repositories 58over SSH. 59 60First, you'll need to generate an SSH key if you don't 61already have one: 62 63```bash 64ssh-keygen -t ed25519 -C "foo@bar.com" 65``` 66 67When prompted, save the key to the default location 68(`~/.ssh/id_ed25519`) and optionally set a passphrase. 69 70Copy your public key to your clipboard: 71 72```bash 73# on X11 74cat ~/.ssh/id_ed25519.pub | xclip -sel c 75 76# on wayland 77cat ~/.ssh/id_ed25519.pub | wl-copy 78 79# on macos 80cat ~/.ssh/id_ed25519.pub | pbcopy 81``` 82 83Now, navigate to 'Settings' -> 'Keys' and hit 'Add Key', 84paste your public key, give it a descriptive name, and hit 85save. 86 87## Create a repository 88 89Once your SSH key is added, create your first repository: 90 911. Hit the green `+` icon on the topbar, and select 92 repository 932. Enter a repository name 943. Add a description 954. Choose a knotserver to host this repository on 965. Hit create 97 98Knots are self-hostable, lightweight Git servers that can 99host your repository. Unlike traditional code forges, your 100code can live on any server. Read the [Knots](TODO) section 101for more. 102 103## Configure SSH 104 105To ensure Git uses the correct SSH key and connects smoothly 106to Tangled, add this configuration to your `~/.ssh/config` 107file: 108 109``` 110Host tangled.org 111 Hostname tangled.org 112 User git 113 IdentityFile ~/.ssh/id_ed25519 114 AddressFamily inet 115``` 116 117This tells SSH to use your specific key when connecting to 118Tangled and prevents authentication issues if you have 119multiple SSH keys. 120 121Note that this configuration only works for knotservers that 122are hosted by tangled.org. If you use a custom knot, refer 123to the [Knots](TODO) section. 124 125## Push your first repository 126 127Initialize a new Git repository: 128 129```bash 130mkdir my-project 131cd my-project 132 133git init 134echo "# My Project" > README.md 135``` 136 137Add some content and push! 138 139```bash 140git add README.md 141git commit -m "Initial commit" 142git remote add origin git@tangled.org:user.tngl.sh/my-project 143git push -u origin main 144``` 145 146That's it! Your code is now hosted on Tangled. 147 148## Migrating an existing repository 149 150Moving your repositories from GitHub, GitLab, Bitbucket, or 151any other Git forge to Tangled is straightforward. You'll 152simply change your repository's remote URL. At the moment, 153Tangled does not have any tooling to migrate data such as 154GitHub issues or pull requests. 155 156First, create a new repository on tangled.org as described 157in the [Quick Start Guide](#create-a-repository). 158 159Navigate to your existing local repository: 160 161```bash 162cd /path/to/your/existing/repo 163``` 164 165You can inspect your existing Git remote like so: 166 167```bash 168git remote -v 169``` 170 171You'll see something like: 172 173```bash 174origin git@github.com:username/my-project.git (fetch) 175origin git@github.com:username/my-project.git (push) 176``` 177 178Update the remote URL to point to tangled: 179 180```bash 181git remote set-url origin git@tangled.org:user.tngl.sh/my-project 182``` 183 184Verify the change: 185 186```bash 187git remote -v 188``` 189 190You should now see: 191 192```bash 193origin git@tangled.org:user.tngl.sh/my-project (fetch) 194origin git@tangled.org:user.tngl.sh/my-project (push) 195``` 196 197Push all your branches and tags to Tangled: 198 199```bash 200git push -u origin --all 201git push -u origin --tags 202``` 203 204Your repository is now migrated to Tangled! All commit 205history, branches, and tags have been preserved. 206 207## Mirroring a repository to Tangled 208 209If you want to maintain your repository on multiple forges 210simultaneously, for example, keeping your primary repository 211on GitHub while mirroring to Tangled for backup or 212redundancy, you can do so by adding [multiple remotes](https://git-scm.com/docs/git-push#_remotes). 213 214You can configure your local repository to push to both 215Tangled and, say, GitHub. You may already have the following 216setup: 217 218```bash 219$ git remote -v 220origin git@github.com:username/my-project.git (fetch) 221origin git@github.com:username/my-project.git (push) 222``` 223 224Now add Tangled as an additional push URL to the same 225remote: 226 227```bash 228git remote set-url --add --push origin git@tangled.org:user.tngl.sh/my-project 229``` 230 231You also need to re-add the original URL as a push 232destination (Git will now use the original URL to fetch only): 233 234```bash 235git remote set-url --add --push origin git@github.com:username/my-project.git 236``` 237 238Verify your configuration: 239 240```bash 241$ git remote -v 242origin git@github.com:username/my-project.git (fetch) 243origin git@tangled.org:user.tngl.sh/my-project (push) 244origin git@github.com:username/my-project.git (push) 245``` 246 247Notice that there's one fetch URL (the primary remote) and 248two push URLs. Now, whenever you push, Git will 249automatically push to both remotes: 250 251```bash 252git push origin main 253``` 254 255This single command pushes your `main` branch to both GitHub 256and Tangled simultaneously. 257 258To push all branches and tags: 259 260```bash 261git push origin --all 262git push origin --tags 263``` 264 265If you prefer more control over which remote you push to, 266you can maintain separate remotes: 267 268```bash 269git remote add github git@github.com:username/my-project.git 270git remote add tangled git@tangled.org:user.tngl.sh/my-project 271``` 272 273Then push to each explicitly: 274 275```bash 276git push github main 277git push tangled main 278``` 279 280# Hosting websites on Tangled 281 282You can serve static websites directly from your git repositories on 283Tangled. If you've used GitHub Pages or Codeberg Pages, this should feel 284familiar. 285 286## Overview 287 288Every user gets a sites domain. If you signed up through Tangled's own 289PDS (`tngl.sh`), your sites domain is automatically 290`<your-handle>.tngl.sh` no setup needed. Otherwise, you can claim a 291`<subdomain>.tngl.io` domain from your settings. 292 293You can serve multiple sites per domain: 294 295- One **index site** served at the root of your domain (e.g. 296 `alice.tngl.sh`) 297- Any number of **sub-path sites** served under the repository name 298 (e.g. `alice.tngl.sh/my-project`) 299 300## Claiming a domain 301 302If you don't have a `tngl.sh` handle, you need to claim a domain before 303publishing sites: 304 3051. Go to **Settings → Sites** 3062. Enter a subdomain (e.g. `alice` to claim `alice.tngl.io`) 3073. Click **claim** 308 309You can only hold one domain at a time. Releasing a domain puts it in a 31030-day cooldown before anyone else can claim it. 311 312## Configuring a site for a repository 313 3141. Navigate to your repository 3152. Go to **Settings → Sites** 3163. Choose a **branch** to deploy from 3174. Set the **deploy directory** — the path within the repository 318 containing your `index.html`. Use `/` for the root, or a subdirectory 319 like `/docs` or `/public` 3205. Choose the **site type**: 321 - **Index site** — served at the root of your domain (e.g. 322 `alice.tngl.sh`) 323 - **Sub-path site** — served under the repository name (e.g. 324 `alice.tngl.sh/my-project`) 3256. Click **save** 326 327The site will be deployed automatically. You can see the status of your 328previous deploys in the **Recent Deploys** section at the bottom of the 329page. 330 331Sites are redeployed automatically on every push to the configured 332branch. 333 334## Custom domains 335 336Tangled currently doesn't support custom domains for sites. This will be 337added in a future update. 338 339## Deploy directory 340 341The deploy directory is the path within your repository that Tangled 342serves as the site root. It must contain an `index.html`. 343 344| Deploy directory | Result | 345|---|---| 346| `/` | Serves the repository root | 347| `/docs` | Serves the `docs/` subdirectory | 348| `/public` | Serves the `public/` subdirectory | 349 350Directories are served with automatic `index.html` resolution -- a 351request to `/about` will serve `/about/index.html` if it exists. 352 353## Site types 354 355| Type | URL | 356|---|---| 357| Index site | `alice.tngl.sh` | 358| Sub-path site | `alice.tngl.sh/my-project` | 359 360Only one repository can be the index site for a given domain at a time. 361If another repository already holds the index site, you will see a 362notice in the settings and only the sub-path option will be available. 363 364## Deploy triggers 365 366A deployment is triggered automatically when: 367 368- You push to the configured branch 369- You change the site configuration (branch, deploy directory, or site 370 type) 371 372## Disabling a site 373 374To stop serving a site, go to **Settings → Sites** in your repository 375and click **Disable**. This removes the site configuration and stops 376serving the site. The deployed files are also deleted from storage. 377 378Releasing your domain from **Settings → Sites** at the account level 379will disable all sites associated with it and delete their files. 380 381 382# Knot self-hosting guide 383 384So you want to run your own knot server? Great! Here are a few prerequisites: 385 3861. A server of some kind (a VPS, a Raspberry Pi, etc.). Preferably running a Linux distribution of some kind. 3872. A (sub)domain name. People generally use `knot.example.com`. 3883. A valid SSL certificate for your domain. 389 390## NixOS 391 392Refer to the [knot 393module](https://tangled.org/tangled.org/core/blob/master/nix/modules/knot.nix) 394for a full list of options. Sample configurations: 395 396- [The test VM](https://tangled.org/tangled.org/core/blob/master/nix/vm.nix#L85) 397- [@pyrox.dev/nix](https://tangled.org/pyrox.dev/nix/blob/d19571cc1b5fe01035e1e6951ec8cf8a476b4dee/hosts/marvin/services/tangled.nix#L15-25) 398 399## Docker 400 401Refer to 402[@tangled.org/knot-docker](https://tangled.org/@tangled.org/knot-docker). 403Note that this is community maintained. 404 405## Manual setup 406 407First, clone this repository: 408 409``` 410git clone https://tangled.org/@tangled.org/core 411``` 412 413Then, build the `knot` CLI. This is the knot administration 414and operation tool. For the purpose of this guide, we're 415only concerned with these subcommands: 416 417- `knot server`: the main knot server process, typically 418 run as a supervised service 419- `knot guard`: handles role-based access control for git 420 over SSH (you'll never have to run this yourself) 421- `knot keys`: fetches SSH keys associated with your knot; 422 we'll use this to generate the SSH 423 `AuthorizedKeysCommand` 424 425``` 426cd core 427export CGO_ENABLED=1 428go build -o knot ./cmd/knot 429``` 430 431Next, move the `knot` binary to a location owned by `root` -- 432`/usr/local/bin/` is a good choice. Make sure the binary itself is also owned by `root`: 433 434``` 435sudo mv knot /usr/local/bin/knot 436sudo chown root:root /usr/local/bin/knot 437``` 438 439This is necessary because SSH `AuthorizedKeysCommand` requires [really 440specific permissions](https://stackoverflow.com/a/27638306). The 441`AuthorizedKeysCommand` specifies a command that is run by `sshd` to 442retrieve a user's public SSH keys dynamically for authentication. Let's 443set that up. 444 445``` 446sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF 447Match User git 448 AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys 449 AuthorizedKeysCommandUser nobody 450EOF 451``` 452 453Then, reload `sshd`: 454 455``` 456sudo systemctl reload ssh 457``` 458 459Next, create the `git` user. We'll use the `git` user's home directory 460to store repositories: 461 462``` 463sudo adduser git 464``` 465 466Create `/home/git/.knot.env` with the following, updating the values as 467necessary. The `KNOT_SERVER_OWNER` should be set to your 468DID, you can find your DID in the [Settings](https://tangled.sh/settings) page. 469 470``` 471KNOT_REPO_SCAN_PATH=/home/git 472KNOT_SERVER_HOSTNAME=knot.example.com 473APPVIEW_ENDPOINT=https://tangled.org 474KNOT_SERVER_OWNER=did:plc:foobar 475KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444 476KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555 477``` 478 479If you run a Linux distribution that uses systemd, you can 480use the provided service file to run the server. Copy 481[`knotserver.service`](https://tangled.org/tangled.org/core/blob/master/systemd/knotserver.service) 482to `/etc/systemd/system/`. Then, run: 483 484``` 485systemctl enable knotserver 486systemctl start knotserver 487``` 488 489The last step is to configure a reverse proxy like Nginx or Caddy to front your 490knot. Here's an example configuration for Nginx: 491 492``` 493server { 494 listen 80; 495 listen [::]:80; 496 server_name knot.example.com; 497 498 location / { 499 proxy_pass http://localhost:5555; 500 proxy_set_header Host $host; 501 proxy_set_header X-Real-IP $remote_addr; 502 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 503 proxy_set_header X-Forwarded-Proto $scheme; 504 } 505 506 # wss endpoint for git events 507 location /events { 508 proxy_set_header X-Forwarded-For $remote_addr; 509 proxy_set_header Host $http_host; 510 proxy_set_header Upgrade websocket; 511 proxy_set_header Connection Upgrade; 512 proxy_pass http://localhost:5555; 513 } 514 # additional config for SSL/TLS go here. 515} 516 517``` 518 519Remember to use Let's Encrypt or similar to procure a certificate for your 520knot domain. 521 522You should now have a running knot server! You can finalize 523your registration by hitting the `verify` button on the 524[/settings/knots](https://tangled.org/settings/knots) page. This simply creates 525a record on your PDS to announce the existence of the knot. 526 527### Custom paths 528 529(This section applies to manual setup only. Docker users should edit the mounts 530in `docker-compose.yml` instead.) 531 532Right now, the database and repositories of your knot lives in `/home/git`. You 533can move these paths if you'd like to store them in another folder. Be careful 534when adjusting these paths: 535 536- Stop your knot when moving data (e.g. `systemctl stop knotserver`) to prevent 537 any possible side effects. Remember to restart it once you're done. 538- Make backups before moving in case something goes wrong. 539- Make sure the `git` user can read and write from the new paths. 540 541#### Database 542 543As an example, let's say the current database is at `/home/git/knotserver.db`, 544and we want to move it to `/home/git/database/knotserver.db`. 545 546Copy the current database to the new location. Make sure to copy the `.db-shm` 547and `.db-wal` files if they exist. 548 549``` 550mkdir /home/git/database 551cp /home/git/knotserver.db* /home/git/database 552``` 553 554In the environment (e.g. `/home/git/.knot.env`), set `KNOT_SERVER_DB_PATH` to 555the new file path (_not_ the directory): 556 557``` 558KNOT_SERVER_DB_PATH=/home/git/database/knotserver.db 559``` 560 561#### Repositories 562 563As an example, let's say the repositories are currently in `/home/git`, and we 564want to move them into `/home/git/repositories`. 565 566Create the new folder, then move the existing repositories (if there are any): 567 568``` 569mkdir /home/git/repositories 570# move all DIDs into the new folder; these will vary for you! 571mv /home/git/did:plc:wshs7t2adsemcrrd4snkeqli /home/git/repositories 572``` 573 574In the environment (e.g. `/home/git/.knot.env`), update `KNOT_REPO_SCAN_PATH` 575to the new directory: 576 577``` 578KNOT_REPO_SCAN_PATH=/home/git/repositories 579``` 580 581Similarly, update your `sshd` `AuthorizedKeysCommand` to use the updated 582repository path: 583 584``` 585sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF 586Match User git 587 AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys -git-dir /home/git/repositories 588 AuthorizedKeysCommandUser nobody 589EOF 590``` 591 592Make sure to restart your SSH server! 593 594#### MOTD (message of the day) 595 596To configure the MOTD used ("Welcome to this knot!" by default), edit the 597`/home/git/motd` file: 598 599``` 600printf "Hi from this knot!\n" > /home/git/motd 601``` 602 603Note that you should add a newline at the end if setting a non-empty message 604since the knot won't do this for you. 605 606## Secure Mode 607 608Secure Mode isolates each `git` subprocess to the repository it is 609operating on, using two mechanisms: 610 611- **Linux Landlock** restricts the filesystem paths the subprocess 612 can access -- it can only read/write its own repository and the 613 system directories it needs to run. 614- **UID isolation** runs each subprocess as a virtual UID assigned 615 to the repository owner, so that repositories belonging to 616 different owners are isolated from each other at the OS level 617 even if Landlock were somehow bypassed. 618 619Secure Mode requires: 620 621- Linux kernel >= 5.19 (Landlock V2). This is the minimum needed 622 for `git push` to work, because receive-pack's quarantine 623 migration uses cross-directory rename which requires the 624 Landlock `REFER` access right (added in V2). Kernels 5.13-5.18 625 support Landlock V1 and clones will work, but pushes will fail 626 with cross-device link errors. On kernels without any Landlock 627 support (< 5.13), the sandbox call is a no-op: UID isolation 628 still applies but no filesystem restriction is enforced. 629- `CAP_SETUID`, `CAP_SETGID`, and `CAP_CHOWN` available to the 630 knot process. The NixOS module grants these automatically; for 631 manual setups see the `setcap` step below. 632 633### NixOS 634 635Add `server.secureMode = true;` to your knot module configuration: 636 637```nix 638services.tangled.knot = { 639 server.secureMode = true; 640 # ... other options 641}; 642``` 643 644The NixOS module handles everything else automatically: 645 646- Grants the required capabilities to the knot service via 647 `AmbientCapabilities` in the systemd unit. 648- Installs a capability-bearing wrapper at 649 `/run/wrappers/bin/knot` via `security.wrappers`, so that 650 SSH-invoked git operations (pushes) also run under the correct 651 UID without requiring the service to run as root. 652- Runs `knot migrate-isolation` at service start to chown 653 existing repositories to their virtual UIDs. 654 655### Manual setup 656 657**Step 1.** Grant the required capabilities to the knot binary. 658This allows the knot process to switch to virtual UIDs at runtime 659without running as root. You will need to repeat this step 660whenever the binary is updated. 661 662``` 663sudo setcap cap_setuid,cap_setgid,cap_chown+eip /usr/local/bin/knot 664``` 665 666**Step 2.** Run the migration tool to assign virtual UIDs to all 667existing repositories and set their filesystem permissions. This 668must be run as root: 669 670``` 671sudo knot migrate-isolation \ 672 --git-dir /home/git \ 673 --db /home/git/knotserver.db \ 674 --internal-api 127.0.0.1:5444 675``` 676 677You can re-run this at any time with `--force` to reapply 678permissions (e.g. after a manual repair or after updating the 679binary). 680 681**Step 2a.** Ensure the home directory is traversable by 682non-group users. Git subprocesses run as virtual UIDs that are 683not in the git group, and they need to resolve 684`$HOME/.config/git/config` to load the global config: 685 686``` 687sudo chmod o+x /home/git 688``` 689 690This adds only the execute bit, not read -- the virtual UIDs can 691traverse to known paths but cannot list directory contents. 692 693**Step 3.** Enable Secure Mode in your environment file: 694 695``` 696KNOT_SERVER_SECURE_MODE=true 697``` 698 699Or pass it as a flag: 700 701``` 702knot server --secure-mode 703``` 704 705**Step 4.** Regenerate the `AuthorizedKeysCommand` with the 706`-secure-mode` flag. This causes `knot keys` to emit guard 707command lines that include `-secure-mode`, so SSH pushes also 708get UID isolation: 709 710``` 711sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF 712Match User git 713 AuthorizedKeysCommand /usr/local/bin/knot keys \ 714 -o authorized-keys -secure-mode 715 AuthorizedKeysCommandUser nobody 716EOF 717``` 718 719Reload `sshd` after making this change. 720 721> **Note:** the server will refuse to start in Secure Mode if any 722> repositories have not yet been isolation-migrated. Re-run 723> `migrate-isolation` if you see this error. 724 725## Troubleshooting 726 727If you run your own knot, you may run into some of these 728common issues. You can always join the 729[IRC](https://web.libera.chat/#tangled) or 730[Discord](https://chat.tangled.org/) if this section does 731not help. 732 733### Unable to push 734 735If you are unable to push to your knot or repository: 736 7371. First, ensure that you have added your SSH public key to 738 your account 7392. Check to see that your knot has synced the key by running 740 `knot keys` 7413. Check to see if git is supplying the correct private key 742 when pushing: `GIT_SSH_COMMAND="ssh -v" git push ...` 7434. Check to see if `sshd` on the knot is rejecting the push 744 for some reason: `journalctl -xeu ssh` (or `sshd`, 745 depending on your machine). These logs are unavailable if 746 using docker. 7475. Check to see if the knot itself is rejecting the push, 748 depending on your setup, the logs might be in one of the 749 following paths: 750 - `/tmp/knotguard.log` 751 - `/home/git/log` 752 - `/home/git/guard.log` 753 754# Spindles 755 756## Pipelines 757 758Spindle workflows allow you to write CI/CD pipelines in a 759simple format. They're located in the `.tangled/workflows` 760directory at the root of your repository, and are defined 761using YAML. 762 763The fields are: 764 765- [Trigger](#trigger): A **required** field that defines 766 when a workflow should be triggered. 767- [Engine](#engine): A **required** field that defines which 768 engine a workflow should run on. 769- [Clone options](#clone-options): An **optional** field 770 that defines how the repository should be cloned. 771- [Dependencies](#dependencies): An **optional** field that 772 allows you to list dependencies you may need. 773- [Environment](#environment): An **optional** field that 774 allows you to define environment variables. 775- [Steps](#steps): An **optional** field that allows you to 776 define what steps should run in the workflow. 777 778### Trigger 779 780The first thing to add to a workflow is the trigger, which 781defines when a workflow runs. This is defined using a `when` 782field, which takes in a list of conditions. Each condition 783has the following fields: 784 785- `event`: This is a **required** field that defines when 786 your workflow should run. It's a list that can take one or 787 more of the following values: 788 - `push`: The workflow should run every time a commit is 789 pushed to the repository. 790 - `pull_request`: The workflow should run every time a 791 pull request is made or updated. 792 - `manual`: The workflow can be triggered manually. 793- `branch`: Defines which branches the workflow should run 794 for. If used with the `push` event, commits to the 795 branch(es) listed here will trigger the workflow. If used 796 with the `pull_request` event, updates to pull requests 797 targeting the branch(es) listed here will trigger the 798 workflow. This field has no effect with the `manual` 799 event. Supports glob patterns using `*` and `**` (e.g., 800 `main`, `develop`, `release-*`). Either `branch` or `tag` 801 (or both) must be specified for `push` events. 802- `tag`: Defines which tags the workflow should run for. 803 Only used with the `push` event - when tags matching the 804 pattern(s) listed here are pushed, the workflow will 805 trigger. This field has no effect with `pull_request` or 806 `manual` events. Supports glob patterns using `*` and `**` 807 (e.g., `v*`, `v1.*`, `release-**`). Either `branch` or 808 `tag` (or both) must be specified for `push` events. 809 810For example, if you'd like to define a workflow that runs 811when commits are pushed to the `main` and `develop` 812branches, or when pull requests that target the `main` 813branch are updated, or manually, you can do so with: 814 815```yaml 816when: 817 - event: ["push", "manual"] 818 branch: ["main", "develop"] 819 - event: ["pull_request"] 820 branch: ["main"] 821``` 822 823You can also trigger workflows on tag pushes. For instance, 824to run a deployment workflow when tags matching `v*` are 825pushed: 826 827```yaml 828when: 829 - event: ["push"] 830 tag: ["v*"] 831``` 832 833You can even combine branch and tag patterns in a single 834constraint (the workflow triggers if either matches): 835 836```yaml 837when: 838 - event: ["push"] 839 branch: ["main", "release-*"] 840 tag: ["v*", "stable"] 841``` 842 843### Engine 844 845Next is the engine on which the workflow should run, defined 846using the **required** `engine` field. The currently 847supported engines are: 848 849- `nixery`: This uses an instance of 850 [Nixery](https://nixery.dev) to run steps, which allows 851 you to add [dependencies](#dependencies) from 852 Nixpkgs (https://github.com/NixOS/nixpkgs). You can 853 search for packages on https://search.nixos.org, and 854 there's a pretty good chance the package(s) you're looking 855 for will be there. 856 857Example: 858 859```yaml 860engine: "nixery" 861``` 862 863### Clone options 864 865When a workflow starts, the first step is to clone the 866repository. You can customize this behavior using the 867**optional** `clone` field. It has the following fields: 868 869- `skip`: Setting this to `true` will skip cloning the 870 repository. This can be useful if your workflow is doing 871 something that doesn't require anything from the 872 repository itself. This is `false` by default. 873- `depth`: This sets the number of commits, or the "clone 874 depth", to fetch from the repository. For example, if you 875 set this to 2, the last 2 commits will be fetched. By 876 default, the depth is set to 1, meaning only the most 877 recent commit will be fetched, which is the commit that 878 triggered the workflow. 879- `submodules`: If you use Git submodules 880 (https://git-scm.com/book/en/v2/Git-Tools-Submodules) 881 in your repository, setting this field to `true` will 882 recursively fetch all submodules. This is `false` by 883 default. 884 885The default settings are: 886 887```yaml 888clone: 889 skip: false 890 depth: 1 891 submodules: false 892``` 893 894### Dependencies 895 896Usually when you're running a workflow, you'll need 897additional dependencies. The `dependencies` field lets you 898define which dependencies to get, and from where. It's a 899key-value map, with the key being the registry to fetch 900dependencies from, and the value being the list of 901dependencies to fetch. 902 903The registry URL syntax can be found [on the nix 904manual](https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix3-registry-add). 905 906Say you want to fetch Node.js and Go from `nixpkgs`, and a 907package called `my_pkg` you've made from your own registry 908at your repository at 909`https://tangled.org/@example.com/my_pkg`. You can define 910those dependencies like so: 911 912```yaml 913dependencies: 914 # nixpkgs 915 nixpkgs: 916 - nodejs 917 - go 918 # unstable 919 nixpkgs/nixpkgs-unstable: 920 - bun 921 # custom registry 922 git+https://tangled.org/@example.com/my_pkg: 923 - my_pkg 924``` 925 926Now these dependencies are available to use in your 927workflow! 928 929### Environment 930 931The `environment` field allows you define environment 932variables that will be available throughout the entire 933workflow. **Do not put secrets here, these environment 934variables are visible to anyone viewing the repository. You 935can add secrets for pipelines in your repository's 936settings.** 937 938Example: 939 940```yaml 941environment: 942 GOOS: "linux" 943 GOARCH: "arm64" 944 NODE_ENV: "production" 945 MY_ENV_VAR: "MY_ENV_VALUE" 946``` 947 948By default, the following environment variables are set: 949 950- `CI` - Always set to `true` to indicate a CI environment 951- `TANGLED_PIPELINE_ID` - The AT URI of the current pipeline 952- `TANGLED_PIPELINE_KIND` - One of `push`, `pull_request` or 953 `manual` 954- `TANGLED_REPO_KNOT` - The repository's knot hostname 955- `TANGLED_REPO_DID` - The DID of the repository owner 956- `TANGLED_REPO_NAME` - The name of the repository 957- `TANGLED_REPO_DEFAULT_BRANCH` - The default branch of the 958 repository 959- `TANGLED_REPO_URL` - The full URL to the repository 960 961These variables are only available when the pipeline is 962triggered by a push: 963 964- `TANGLED_REF` - The full git reference (e.g., 965 `refs/heads/main` or `refs/tags/v1.0.0`) 966- `TANGLED_REF_NAME` - The short name of the reference 967 (e.g., `main` or `v1.0.0`) 968- `TANGLED_REF_TYPE` - The type of reference, either 969 `branch` or `tag` 970- `TANGLED_SHA` - The commit SHA that triggered the pipeline 971- `TANGLED_COMMIT_SHA` - Alias for `TANGLED_SHA` 972 973These variables are only available when the pipeline is 974triggered by a pull request: 975 976- `TANGLED_PR_SOURCE_BRANCH` - The source branch of the pull 977 request 978- `TANGLED_PR_TARGET_BRANCH` - The target branch of the pull 979 request 980- `TANGLED_PR_SOURCE_SHA` - The commit SHA of the source 981 branch 982 983### Steps 984 985The `steps` field allows you to define what steps should run 986in the workflow. It's a list of step objects, each with the 987following fields: 988 989- `name`: This field allows you to give your step a name. 990 This name is visible in your workflow runs, and is used to 991 describe what the step is doing. 992- `command`: This field allows you to define a command to 993 run in that step. The step is run in a Bash shell, and the 994 logs from the command will be visible in the pipelines 995 page on the Tangled website. The 996 [dependencies](#dependencies) you added will be available 997 to use here. 998- `environment`: Similar to the global 999 [environment](#environment) config, this **optional** 1000 field is a key-value map that allows you to set 1001 environment variables for the step. **Do not put secrets 1002 here, these environment variables are visible to anyone 1003 viewing the repository. You can add secrets for pipelines 1004 in your repository's settings.** 1005 1006Example: 1007 1008```yaml 1009steps: 1010 - name: "Build backend" 1011 command: "go build" 1012 environment: 1013 GOOS: "darwin" 1014 GOARCH: "arm64" 1015 - name: "Build frontend" 1016 command: "npm run build" 1017 environment: 1018 NODE_ENV: "production" 1019``` 1020 1021### Complete workflow 1022 1023```yaml 1024# .tangled/workflows/build.yml 1025 1026when: 1027 - event: ["push", "manual"] 1028 branch: ["main", "develop"] 1029 - event: ["pull_request"] 1030 branch: ["main"] 1031 1032engine: "nixery" 1033 1034# using the default values 1035clone: 1036 skip: false 1037 depth: 1 1038 submodules: false 1039 1040dependencies: 1041 # nixpkgs 1042 nixpkgs: 1043 - nodejs 1044 - go 1045 # custom registry 1046 git+https://tangled.org/@example.com/my_pkg: 1047 - my_pkg 1048 1049environment: 1050 GOOS: "linux" 1051 GOARCH: "arm64" 1052 NODE_ENV: "production" 1053 MY_ENV_VAR: "MY_ENV_VALUE" 1054 1055steps: 1056 - name: "Build backend" 1057 command: "go build" 1058 environment: 1059 GOOS: "darwin" 1060 GOARCH: "arm64" 1061 - name: "Build frontend" 1062 command: "npm run build" 1063 environment: 1064 NODE_ENV: "production" 1065``` 1066 1067If you want another example of a workflow, you can look at 1068the one [Tangled uses to build the 1069project](https://tangled.org/@tangled.org/core/blob/master/.tangled/workflows/build.yml). 1070 1071## Self-hosting guide 1072 1073### Prerequisites 1074 1075- Go 1076- Docker (the only supported backend currently) 1077 1078### Configuration 1079 1080Spindle is configured using environment variables. The following environment variables are available: 1081 1082- `SPINDLE_SERVER_LISTEN_ADDR`: The address the server listens on (default: `"0.0.0.0:6555"`). 1083- `SPINDLE_SERVER_DB_PATH`: The path to the SQLite database file (default: `"spindle.db"`). 1084- `SPINDLE_SERVER_HOSTNAME`: The hostname of the server (required). 1085- `SPINDLE_SERVER_JETSTREAM_ENDPOINT`: The endpoint of the Jetstream server (default: `"wss://jetstream1.us-west.bsky.network/subscribe"`). 1086- `SPINDLE_SERVER_DEV`: A boolean indicating whether the server is running in development mode (default: `false`). 1087- `SPINDLE_SERVER_OWNER`: The DID of the owner (required). 1088- `SPINDLE_SERVER_LOG_DIR`: The directory to store workflow logs (default: `"/var/log/spindle"`). 1089- `SPINDLE_SERVER_DOCKER_SOCKET`: Path to Docker socket to expose to invoked Spindle containers (default: `""`). 1090- `SPINDLE_PIPELINES_NIXERY`: The Nixery URL (default: `"nixery.tangled.sh"`). 1091- `SPINDLE_PIPELINES_WORKFLOW_TIMEOUT`: The default workflow timeout (default: `"5m"`). 1092 1093### Running spindle 1094 10951. **Set the environment variables.** For example: 1096 1097 ```shell 1098 export SPINDLE_SERVER_HOSTNAME="your-hostname" 1099 export SPINDLE_SERVER_OWNER="your-did" 1100 ``` 1101 11022. **Build the Spindle binary.** 1103 1104 ```shell 1105 cd core 1106 go mod download 1107 go build -o cmd/spindle/spindle cmd/spindle/main.go 1108 ``` 1109 11103. **Create the log directory.** 1111 1112 ```shell 1113 sudo mkdir -p /var/log/spindle 1114 sudo chown $USER:$USER -R /var/log/spindle 1115 ``` 1116 11174. **Run the Spindle binary.** 1118 1119 ```shell 1120 ./cmd/spindle/spindle 1121 ``` 1122 1123Spindle will now start, connect to the Jetstream server, and begin processing pipelines. 1124 1125## Architecture 1126 1127Spindle is a small CI runner service. Here's a high-level overview of how it operates: 1128 1129- Listens for [`sh.tangled.spindle.member`](/lexicons/spindle/member.json) and 1130 [`sh.tangled.repo`](/lexicons/repo.json) records on the Jetstream. 1131- When a new repo record comes through (typically when you add a spindle to a 1132 repo from the settings), spindle then resolves the underlying knot and 1133 subscribes to repo events (see: 1134 [`sh.tangled.pipeline`](/lexicons/pipeline.json)). 1135- The spindle engine then handles execution of the pipeline, with results and 1136 logs beamed on the spindle event stream over WebSocket 1137 1138### The engine 1139 1140At present, the only supported backend is Docker (and Podman, if Docker 1141compatibility is enabled, so that `/run/docker.sock` is created). spindle 1142executes each step in the pipeline in a fresh container, with state persisted 1143across steps within the `/tangled/workspace` directory. 1144 1145The base image for the container is constructed on the fly using 1146[Nixery](https://nixery.dev), which is handy for caching layers for frequently 1147used packages. 1148 1149The pipeline manifest is [specified here](https://docs.tangled.org/spindles.html#pipelines). 1150 1151## Secrets with openbao 1152 1153This document covers setting up spindle to use OpenBao for secrets 1154management via OpenBao Proxy instead of the default SQLite backend. 1155 1156### Overview 1157 1158Spindle now uses OpenBao Proxy for secrets management. The proxy handles 1159authentication automatically using AppRole credentials, while spindle 1160connects to the local proxy instead of directly to the OpenBao server. 1161 1162This approach provides better security, automatic token renewal, and 1163simplified application code. 1164 1165### Installation 1166 1167Install OpenBao from Nixpkgs: 1168 1169```bash 1170nix shell nixpkgs#openbao # for a local server 1171``` 1172 1173### Setup 1174 1175The setup process can is documented for both local development and production. 1176 1177#### Local development 1178 1179Start OpenBao in dev mode: 1180 1181```bash 1182bao server -dev -dev-root-token-id="root" -dev-listen-address=127.0.0.1:8201 1183``` 1184 1185This starts OpenBao on `http://localhost:8201` with a root token. 1186 1187Set up environment for bao CLI: 1188 1189```bash 1190export BAO_ADDR=http://localhost:8200 1191export BAO_TOKEN=root 1192``` 1193 1194#### Production 1195 1196You would typically use a systemd service with a 1197configuration file. Refer to 1198[@tangled.org/infra](https://tangled.org/@tangled.org/infra) 1199for how this can be achieved using Nix. 1200 1201Then, initialize the bao server: 1202 1203```bash 1204bao operator init -key-shares=1 -key-threshold=1 1205``` 1206 1207This will print out an unseal key and a root key. Save them 1208somewhere (like a password manager). Then unseal the vault 1209to begin setting it up: 1210 1211```bash 1212bao operator unseal <unseal_key> 1213``` 1214 1215All steps below remain the same across both dev and 1216production setups. 1217 1218#### Configure openbao server 1219 1220Create the spindle KV mount: 1221 1222```bash 1223bao secrets enable -path=spindle -version=2 kv 1224``` 1225 1226Set up AppRole authentication and policy: 1227 1228Create a policy file `spindle-policy.hcl`: 1229 1230```hcl 1231# Full access to spindle KV v2 data 1232path "spindle/data/*" { 1233 capabilities = ["create", "read", "update", "delete"] 1234} 1235 1236# Access to metadata for listing and management 1237path "spindle/metadata/*" { 1238 capabilities = ["list", "read", "delete", "update"] 1239} 1240 1241# Allow listing at root level 1242path "spindle/" { 1243 capabilities = ["list"] 1244} 1245 1246# Required for connection testing and health checks 1247path "auth/token/lookup-self" { 1248 capabilities = ["read"] 1249} 1250``` 1251 1252Apply the policy and create an AppRole: 1253 1254```bash 1255bao policy write spindle-policy spindle-policy.hcl 1256bao auth enable approle 1257bao write auth/approle/role/spindle \ 1258 token_policies="spindle-policy" \ 1259 token_ttl=1h \ 1260 token_max_ttl=4h \ 1261 bind_secret_id=true \ 1262 secret_id_ttl=0 \ 1263 secret_id_num_uses=0 1264``` 1265 1266Get the credentials: 1267 1268```bash 1269# Get role ID (static) 1270ROLE_ID=$(bao read -field=role_id auth/approle/role/spindle/role-id) 1271 1272# Generate secret ID 1273SECRET_ID=$(bao write -f -field=secret_id auth/approle/role/spindle/secret-id) 1274 1275echo "Role ID: $ROLE_ID" 1276echo "Secret ID: $SECRET_ID" 1277``` 1278 1279#### Create proxy configuration 1280 1281Create the credential files: 1282 1283```bash 1284# Create directory for OpenBao files 1285mkdir -p /tmp/openbao 1286 1287# Save credentials 1288echo "$ROLE_ID" > /tmp/openbao/role-id 1289echo "$SECRET_ID" > /tmp/openbao/secret-id 1290chmod 600 /tmp/openbao/role-id /tmp/openbao/secret-id 1291``` 1292 1293Create a proxy configuration file `/tmp/openbao/proxy.hcl`: 1294 1295```hcl 1296# OpenBao server connection 1297vault { 1298 address = "http://localhost:8200" 1299} 1300 1301# Auto-Auth using AppRole 1302auto_auth { 1303 method "approle" { 1304 mount_path = "auth/approle" 1305 config = { 1306 role_id_file_path = "/tmp/openbao/role-id" 1307 secret_id_file_path = "/tmp/openbao/secret-id" 1308 } 1309 } 1310 1311 # Optional: write token to file for debugging 1312 sink "file" { 1313 config = { 1314 path = "/tmp/openbao/token" 1315 mode = 0640 1316 } 1317 } 1318} 1319 1320# Proxy listener for spindle 1321listener "tcp" { 1322 address = "127.0.0.1:8201" 1323 tls_disable = true 1324} 1325 1326# Enable API proxy with auto-auth token 1327api_proxy { 1328 use_auto_auth_token = true 1329} 1330 1331# Enable response caching 1332cache { 1333 use_auto_auth_token = true 1334} 1335 1336# Logging 1337log_level = "info" 1338``` 1339 1340#### Start the proxy 1341 1342Start OpenBao Proxy: 1343 1344```bash 1345bao proxy -config=/tmp/openbao/proxy.hcl 1346``` 1347 1348The proxy will authenticate with OpenBao and start listening on 1349`127.0.0.1:8201`. 1350 1351#### Configure spindle 1352 1353Set these environment variables for spindle: 1354 1355```bash 1356export SPINDLE_SERVER_SECRETS_PROVIDER=openbao 1357export SPINDLE_SERVER_SECRETS_OPENBAO_PROXY_ADDR=http://127.0.0.1:8201 1358export SPINDLE_SERVER_SECRETS_OPENBAO_MOUNT=spindle 1359``` 1360 1361On startup, spindle will now connect to the local proxy, 1362which handles all authentication automatically. 1363 1364### Production setup for proxy 1365 1366For production, you'll want to run the proxy as a service: 1367 1368Place your production configuration in 1369`/etc/openbao/proxy.hcl` with proper TLS settings for the 1370vault connection. 1371 1372### Verifying setup 1373 1374Test the proxy directly: 1375 1376```bash 1377# Check proxy health 1378curl -H "X-Vault-Request: true" http://127.0.0.1:8201/v1/sys/health 1379 1380# Test token lookup through proxy 1381curl -H "X-Vault-Request: true" http://127.0.0.1:8201/v1/auth/token/lookup-self 1382``` 1383 1384Test OpenBao operations through the server: 1385 1386```bash 1387# List all secrets 1388bao kv list spindle/ 1389 1390# Add a test secret via the spindle API, then check it exists 1391bao kv list spindle/repos/ 1392 1393# Get a specific secret 1394bao kv get spindle/repos/your_repo_path/SECRET_NAME 1395``` 1396 1397### How it works 1398 1399- Spindle connects to OpenBao Proxy on localhost (typically 1400 port 8200 or 8201) 1401- The proxy authenticates with OpenBao using AppRole 1402 credentials 1403- All spindle requests go through the proxy, which injects 1404 authentication tokens 1405- Secrets are stored at 1406 `spindle/repos/{sanitized_repo_path}/{secret_key}` 1407- Repository paths like `did:plc:alice/myrepo` become 1408 `did_plc_alice_myrepo` 1409- The proxy handles all token renewal automatically 1410- Spindle no longer manages tokens or authentication 1411 directly 1412 1413### Troubleshooting 1414 1415**Connection refused**: Check that the OpenBao Proxy is 1416running and listening on the configured address. 1417 1418**403 errors**: Verify the AppRole credentials are correct 1419and the policy has the necessary permissions. 1420 1421**404 route errors**: The spindle KV mount probably doesn't 1422exist—run the mount creation step again. 1423 1424**Proxy authentication failures**: Check the proxy logs and 1425verify the role-id and secret-id files are readable and 1426contain valid credentials. 1427 1428**Secret not found after writing**: This can indicate policy 1429permission issues. Verify the policy includes both 1430`spindle/data/*` and `spindle/metadata/*` paths with 1431appropriate capabilities. 1432 1433Check proxy logs: 1434 1435```bash 1436# If running as systemd service 1437journalctl -u openbao-proxy -f 1438 1439# If running directly, check the console output 1440``` 1441 1442Test AppRole authentication manually: 1443 1444```bash 1445bao write auth/approle/login \ 1446 role_id="$(cat /tmp/openbao/role-id)" \ 1447 secret_id="$(cat /tmp/openbao/secret-id)" 1448``` 1449 1450# Webhooks 1451 1452Webhooks allow you to receive HTTP POST notifications when events occur in your repositories. This enables you to integrate Tangled with external services, trigger CI/CD pipelines, send notifications, or automate workflows. 1453 1454## Overview 1455 1456Webhooks send HTTP POST requests to URLs you configure whenever specific events happen. Currently, Tangled supports push events, with more event types coming soon. 1457 1458## Configuring webhooks 1459 1460To set up a webhook for your repository: 1461 14621. Navigate to your repository 14632. Go to **Settings → Hooks** 14643. Click **new webhook** 14654. Configure your webhook: 1466 - **Payload URL**: The endpoint that will receive the webhook POST requests 1467 - **Secret**: An optional secret key for verifying webhook authenticity (leave blank to send unsigned webhooks) 1468 - **Events**: Select which events trigger the webhook (currently only push events) 1469 - **Active**: Toggle whether the webhook is enabled 1470 1471## Webhook payload 1472 1473### Push 1474 1475When a push event occurs, Tangled sends a POST request with a JSON payload of the format: 1476 1477```json 1478{ 1479 "after": "7b320e5cbee2734071e4310c1d9ae401d8f6cab5", 1480 "before": "c04ddf64eddc90e4e2a9846ba3b43e67a0e2865e", 1481 "pusher": { 1482 "did": "did:plc:hwevmowznbiukdf6uk5dwrrq" 1483 }, 1484 "ref": "refs/heads/main", 1485 "repository": { 1486 "clone_url": "https://tangled.org/did:plc:hwevmowznbiukdf6uk5dwrrq/some-repo", 1487 "created_at": "2025-09-15T08:57:23Z", 1488 "description": "an example repository", 1489 "fork": false, 1490 "full_name": "did:plc:hwevmowznbiukdf6uk5dwrrq/some-repo", 1491 "html_url": "https://tangled.org/did:plc:hwevmowznbiukdf6uk5dwrrq/some-repo", 1492 "name": "some-repo", 1493 "open_issues_count": 5, 1494 "owner": { 1495 "did": "did:plc:hwevmowznbiukdf6uk5dwrrq" 1496 }, 1497 "ssh_url": "ssh://git@tangled.org/did:plc:hwevmowznbiukdf6uk5dwrrq/some-repo", 1498 "stars_count": 1, 1499 "updated_at": "2025-09-15T08:57:23Z" 1500 } 1501} 1502``` 1503 1504## HTTP headers 1505 1506Each webhook request includes the following headers: 1507 1508- `Content-Type: application/json` 1509- `User-Agent: Tangled-Hook/<short-sha>` — User agent with short SHA of the commit 1510- `X-Tangled-Event: push` — The event type 1511- `X-Tangled-Hook-ID: <webhook-id>` — The webhook ID 1512- `X-Tangled-Delivery: <uuid>` — Unique delivery ID 1513- `X-Tangled-Signature-256: sha256=<hmac>` — HMAC-SHA256 signature (if secret configured) 1514 1515## Verifying webhook signatures 1516 1517If you configured a secret, you should verify the webhook signature to ensure requests are authentic. For example, in Go: 1518 1519```go 1520package main 1521 1522import ( 1523 "crypto/hmac" 1524 "crypto/sha256" 1525 "encoding/hex" 1526 "io" 1527 "net/http" 1528 "strings" 1529) 1530 1531func verifySignature(payload []byte, signatureHeader, secret string) bool { 1532 // Remove 'sha256=' prefix from signature header 1533 signature := strings.TrimPrefix(signatureHeader, "sha256=") 1534 1535 // Compute expected signature 1536 mac := hmac.New(sha256.New, []byte(secret)) 1537 mac.Write(payload) 1538 expected := hex.EncodeToString(mac.Sum(nil)) 1539 1540 // Use constant-time comparison to prevent timing attacks 1541 return hmac.Equal([]byte(signature), []byte(expected)) 1542} 1543 1544func webhookHandler(w http.ResponseWriter, r *http.Request) { 1545 // Read the request body 1546 payload, err := io.ReadAll(r.Body) 1547 if err != nil { 1548 http.Error(w, "Bad request", http.StatusBadRequest) 1549 return 1550 } 1551 1552 // Get signature from header 1553 signatureHeader := r.Header.Get("X-Tangled-Signature-256") 1554 1555 // Verify signature 1556 if signatureHeader != "" && verifySignature(payload, signatureHeader, yourSecret) { 1557 // Webhook is authentic, process it 1558 processWebhook(payload) 1559 w.WriteHeader(http.StatusOK) 1560 } else { 1561 http.Error(w, "Invalid signature", http.StatusUnauthorized) 1562 } 1563} 1564``` 1565 1566## Delivery retries 1567 1568Webhooks are automatically retried on failure: 1569 1570- **3 total attempts** (1 initial + 2 retries) 1571- **Exponential backoff** starting at 1 second, max 10 seconds 1572- **Retried on**: 1573 - Network errors 1574 - HTTP 5xx server errors 1575- **Not retried on**: 1576 - HTTP 4xx client errors (bad request, unauthorized, etc.) 1577 1578### Timeouts 1579 1580Webhook requests timeout after 30 seconds. If your endpoint needs more time: 1581 15821. Respond with 200 OK immediately 15832. Process the webhook asynchronously in the background 1584 1585## Example integrations 1586 1587### Discord notifications 1588 1589```javascript 1590app.post("/webhook", (req, res) => { 1591 const payload = req.body; 1592 1593 fetch("https://discord.com/api/webhooks/...", { 1594 method: "POST", 1595 headers: { "Content-Type": "application/json" }, 1596 body: JSON.stringify({ 1597 content: `New push to ${payload.repository.full_name}`, 1598 embeds: [ 1599 { 1600 title: `${payload.pusher.did} pushed to ${payload.ref}`, 1601 url: payload.repository.html_url, 1602 color: 0x00ff00, 1603 }, 1604 ], 1605 }), 1606 }); 1607 1608 res.status(200).send("OK"); 1609}); 1610``` 1611 1612# Migrating knots and spindles 1613 1614Sometimes, non-backwards compatible changes are made to the 1615knot/spindle XRPC APIs. If you host a knot or a spindle, you 1616will need to follow this guide to upgrade. Typically, this 1617only requires you to deploy the newest version. 1618 1619This document is laid out in reverse-chronological order. 1620Newer migration guides are listed first, and older guides 1621are further down the page. 1622 1623## Upgrading to v1.15.0-alpha 1624 1625With v1.15.0-alpha, a knot itself owns its members and 1626per-repo collaborators directly. Previously this data was sourced from 1627PDS records (`sh.tangled.knot.member` and `sh.tangled.repo.collaborator`) 1628that the appview and the knot both read off the firehose. 1629The knot is now the source of truth and serves them over XRPC instead: 1630 1631- `sh.tangled.knot.addMember`, `sh.tangled.knot.removeMember`, `sh.tangled.knot.listMembers` 1632- `sh.tangled.repo.addCollaborator`, `sh.tangled.repo.removeCollaborator`, `sh.tangled.repo.listCollaborators` 1633 1634Until your knot is upgraded, the appview keeps reading its 1635members and collaborators from the old firehose-sourced records. 1636Upgrade to move your knot onto knot-owned access control. 1637 1638- Upgrade to the latest tag (v1.15.0 or above) 1639- Head to the [knot dashboard](https://tangled.org/settings/knots) and 1640 hit the "retry" button to verify your knot 1641 1642## Upgrading to v1.14.0-alpha 1643 1644Starting with v1.14.0-alpha, the fully knot uses the repoDID as its 1645canonical handle for repositories. This unlocks repository 1646renames from the appview UI and changes the wire format for 1647the following lexicons (`sh.tangled.repo.pull`, `sh.tangled.repo.collaborator`, 1648`sh.tangled.repo.issue`, `sh.tangled.git.refUpdate`). 1649 1650Knots that have not been upgraded may silently drop new push 1651events, pull requests, issues, and collaborator invites for 1652repositories they host until upgraded. So upgrade please!!! 1653 1654- Upgrade to the latest tag (v1.14.0 or above) 1655- Head to the [knot dashboard](https://tangled.org/settings/knots) and 1656 hit the "retry" button to verify your knot 1657 1658## Upgrading to v1.13.0-alpha 1659 1660Starting with v1.13.0-alpha, every repository on a knot is 1661assigned a DID. This makes repositories stable across 1662renames and transfers. 1663 1664When you upgrade your knot to this version, the server will 1665automatically mint DIDs for all existing repositories on 1666startup. This is a one-time process and you may see 1667additional log output during the first boot as DIDs are 1668assigned. 1669 1670- Upgrade to the latest tag (v1.13.0 or above) 1671- Head to the [knot dashboard](https://tangled.org/settings/knots) and 1672 hit the "retry" button to verify your knot 1673 1674## Upgrading from v1.8.x 1675 1676After v1.8.2, the HTTP API for knots and spindles has been 1677deprecated and replaced with XRPC. Repositories on outdated 1678knots will not be viewable from the appview. Upgrading is 1679straightforward however. 1680 1681For knots: 1682 1683- Upgrade to the latest tag (v1.9.0 or above) 1684- Head to the [knot dashboard](https://tangled.org/settings/knots) and 1685 hit the "retry" button to verify your knot 1686 1687For spindles: 1688 1689- Upgrade to the latest tag (v1.9.0 or above) 1690- Head to the [spindle 1691 dashboard](https://tangled.org/settings/spindles) and hit the 1692 "retry" button to verify your spindle 1693 1694## Upgrading from v1.7.x 1695 1696After v1.7.0, knot secrets have been deprecated. You no 1697longer need a secret from the appview to run a knot. All 1698authorized commands to knots are managed via [Inter-Service 1699Authentication](https://atproto.com/specs/xrpc#inter-service-authentication-jwt). 1700Knots will be read-only until upgraded. 1701 1702Upgrading is quite easy, in essence: 1703 1704- `KNOT_SERVER_SECRET` is no more, you can remove this 1705 environment variable entirely 1706- `KNOT_SERVER_OWNER` is now required on boot, set this to 1707 your DID. You can find your DID in the 1708 [settings](https://tangled.org/settings) page. 1709- Restart your knot once you have replaced the environment 1710 variable 1711- Head to the [knot dashboard](https://tangled.org/settings/knots) and 1712 hit the "retry" button to verify your knot. This simply 1713 writes a `sh.tangled.knot` record to your PDS. 1714 1715If you use the nix module, simply bump the flake to the 1716latest revision, and change your config block like so: 1717 1718```diff 1719 services.tangled.knot = { 1720 enable = true; 1721 server = { 1722- secretFile = /path/to/secret; 1723+ owner = "did:plc:foo"; 1724 }; 1725 }; 1726``` 1727 1728# Bobbin 1729 1730Bobbin is an API appview for Tangled records. It serves XRPC 1731endpoints for `sh.tangled.*`, with it you can get repos, 1732issues, pulls, comments, follows, stars, labels, pipelines, 1733and profiles. It is read-only, there is no auth, since that 1734should all be handled direct-to-PDS and knot respectively. 1735 1736**Bobbin has no permanent storage**. 1737 1738It is only a glorified edge index, in the graph theory 1739sense. Additionally it has a record cache, re-filled on 1740demand. All other data that Bobbin serves comes live from 1741PDSes & knots. 1742 1743## What Bobbin needs 1744 1745The way that Bobbin is able to pull off being 1746so stateless is by moving state upstream. 1747Primarily it depends on an instance of 1748[Hydrant](https://tangled.org/did:plc:6v3ul2ptnqctyxwkz5ti4amn) 1749, which is the service that gives an event stream 1750for Bobbin to quickly backfill from on every restart. 1751Backfilling ought to take less than a couple of minutes 1752maximum. If the upstream instance of Hydrant fails 1753while Bobbin is live, its list/count endpoints stop 1754advancing and report a stale cursor. Single-lookups 1755will continue working, due to the second dependency: 1756[Slingshot](https://tangled.org/did:plc:c7mc2fn47ihdihul4vjwsuy3/tree/main/slingshot). 1757Slingshot fetches individual records & resolves identities. 1758If the upstream instance of Slingshot fails, single-lookups 1759will fail with a `502` error. There are some aggregation 1760endpoints that use Slingshot for hydrating, which will also 1761fail. 1762 1763A soft dependency that ought to exist for Bobbin to operate 1764correctly is simply the plethora of knots that are out 1765there, that Bobbin talks to directly for git data and, for 1766knots at v1.15+, members & collaborators. 1767 1768## Building Bobbin 1769 1770Bobbin is under [Tangled's core monorepo, under bobbin/](https://tangled.org/did:plc:j5hmlfdrwkvtxm7cjmu7j2is/tree/master/bobbin). 1771Here's an easy local debug-build: 1772 1773```sh 1774cargo build -p bobbin 1775``` 1776 1777Bobbin loves being in a container. When using 1778`bobbin/containerfiles/bobbin.Containerfile`, it runs `cargo 1779build --release --bin bobbin --package bobbin` within a 1780little Debian runtime, exposing port 8090. 1781 1782## Configuration 1783 1784The best way to configure Bobbin is via a toml config file. 1785There's an `example.toml` in [Bobbin's subdir](https://tangled.org/did:plc:j5hmlfdrwkvtxm7cjmu7j2is/blob/master/bobbin/example.toml). 1786Every value is overridable by a `BOBBIN_*` env var. 1787The load order is env, then `--config <path>`, then 1788`/etc/bobbin/config.toml`, then built-in defaults. 1789 1790Load and check a config without starting the server: 1791 1792```sh 1793bobbin --config config.toml validate 1794``` 1795 1796Minimal config is the two upstream URLs. The hydrant URL 1797takes `ws://` or `wss://`. An `http://` or `https://` 1798URL is rewritten to the matching websocket scheme at 1799connection-time. 1800 1801```toml 1802[server] 1803binds = ["127.0.0.1:8090"] 1804 1805# Loopback-only & can leave empty to disable debug introspection. 1806debug_bind = "127.0.0.1:8091" 1807 1808[hydrant] 1809url = "https://hydrant.example.com" 1810 1811[slingshot] 1812url = "https://slingshot.example.com" 1813``` 1814 1815> 🦪 Lewis 1816> 1817> At time of writing, we (Tangled) don't host public 1818> instances of Hydrant or Slingshot. You will have to 1819> find public instances or spin these up yourself! :P 1820 1821Take a gander in the project's example.toml for an 1822exhaustive list of things to configure. 1823 1824You will discover fun things such as a configurable adaptive 1825loop that watches the cgroup memory limit & throttles heavy 1826requests under pressure. It only works if it detects a 1827cgroup limit is present. The config for that is in the 1828`[backpressure]` block of the config template. 1829 1830## Running Bobbin 1831 1832Start the server using a config toml: 1833 1834```bash 1835bobbin --config config.toml 1836``` 1837Bobbin wakes up in a cold sweat and immediately gets to 1838work: 18391. It binds its listeners, connects to the Hydrant stream 1840 in the background. 18412. It serves requests from the first 1842 moment it's alive, even before the Hydrant stream connects 1843 or finishes catching up. Having a cold Hydrant itself 1844 costs only latency and approximate counts. 1845 1846## The API 1847 1848**Single lookups** take a record's AT-URI. 1849 1850- `getRepo` takes the repo URI: 1851 1852```sh 1853curl "$BOBBIN/xrpc/sh.tangled.repo.getRepo?repo=at://did:plc:boltless/sh.tangled.repo/squid" 1854``` 1855```json 1856{ 1857 "uri": "at://did:plc:boltless/sh.tangled.repo/squid", 1858 "cid": "bafyrei...", 1859 "value": { "$type": "sh.tangled.repo", "knot": "knot1.tangled.sh", "description": "...", "createdAt": "..." } 1860} 1861``` 1862 1863- `getProfile` takes the full profile record URI, so a bare 1864 handle or DID will not resolve: 1865 1866```sh 1867curl "$BOBBIN/xrpc/sh.tangled.actor.getProfile?actor=at://did:plc:boltless/sh.tangled.actor.profile/self" 1868``` 1869 1870- If Slingshot cannot serve the record, the response is `502`: 1871 1872```json 1873{ "error": "UpstreamFailed", "message": "upstream unavailable: ..." } 1874``` 1875 1876**Aggregation** endpoints come in `list*` and `count*` pairs, 1877each with a `*By` sibling, and require a `subject` query param. 1878 1879- `listRepos` and `countRepos` key on the owner DID: 1880 1881```sh 1882curl "$BOBBIN/xrpc/sh.tangled.repo.countRepos?subject=did:plc:boltless" 1883``` 1884```json 1885{ "count": 7, "distinctAuthors": 1 } 1886``` 1887 1888```sh 1889curl "$BOBBIN/xrpc/sh.tangled.repo.listRepos?subject=did:plc:boltless&limit=3" 1890``` 1891```json 1892{ "items": [ { "uri": "at://did:plc:boltless/sh.tangled.repo/squid", "cid": "bafyrei...", "value": { } } ], "cursor": null } 1893``` 1894 1895- Bobbin validates the subject per collection. Here a repo URI 1896 is passed where a bare DID is required, so the call returns a 1897 `400`: 1898 1899```sh 1900curl "$BOBBIN/xrpc/sh.tangled.graph.listFollows?subject=at://did:plc:boltless/sh.tangled.repo/squid" 1901``` 1902```json 1903{ "error": "InvalidRequest", "message": "invalid request: subject must be a bare did, got at-uri with collection sh.tangled.repo" } 1904``` 1905 1906**Search** is a single endpoint over an in-mem full-text 1907index: 1908 1909```sh 1910curl "$BOBBIN/xrpc/sh.tangled.search.query?q=tangled&limit=2" 1911``` 1912```json 1913{ "hits": [ { "uri": "at://...", "cid": "...", "nsid": "sh.tangled.repo", "score": 27.1, "value": { } } ], "cursor": null } 1914``` 1915 1916**Git data** such as blob, tree, diff, log, and archive proxies 1917straight to the repo's knot, streamed back without caching. 1918 1919## Coverage and warm-up 1920 1921- While the edge index is catching up from Hydrant, 1922 the aggregation count is a lower bound & may still climb. 1923- One endpoint reports how far along the backfill it is: 1924 1925```sh 1926curl "$BOBBIN/xrpc/sh.tangled.bobbin.getCoverage" 1927``` 1928 1929While warming up: 1930 1931```json 1932{ "ready": false, "eventsProcessed": 45588, "lastCursor": 51658 } 1933``` 1934 1935Once caught up, Bobbin flips to ready: 1936 1937```json 1938{ "ready": true, "eventsProcessed": 106085, "lastCursor": 116527 } 1939``` 1940 1941If starting up Hydrant for the first time, Hydrant itself 1942will take a decent while (a couple of hours) to backfill 1943from PDSes. Hydrant stores its backfill on disk. Bobbin 1944restart reaches `ready` in minutes by replaying event from 1945an already-populated Hydrant. If your Hydrant is new, expect 1946Bobbin to backfill in that same couple of hours that Hydrant 1947takes. 1948 1949## Loose ends and not-gonna-impl 1950 1951- **No coverage signal for per-knot rosters yet.** 1952 Coverage tracks the hydrant stream only. A v1.15 knot 1953 that is unreachable serves a stale or empty member set 1954 with nothing to flag it. 1955- **Knot eventstream fan-out isn't pooled.** 1956 Bobbin opens one websocket per v1.15 1957 knot on top of the hydrant subscription. A network with 1958 thousands of knots wants pooling or a shared subscription. 1959- **No sequential issue or PR numbers.** bobbin returns rkeys, 1960 not `#42` style ids like the web appview. A client 1961 deriving a display number does it from creation order. But 1962 why bother? rkeys are the IDs. 1963 1964# Hacking on Tangled 1965 1966We highly recommend [installing 1967Nix](https://nixos.org/download/) (the package manager) 1968before working on the codebase. The Nix flake provides a lot 1969of helpers to get started and most importantly, builds and 1970dev shells are entirely deterministic. 1971 1972To set up your dev environment: 1973 1974```bash 1975nix develop 1976``` 1977 1978Non-Nix users can look at the `devShell` attribute in the 1979`flake.nix` file to determine necessary dependencies. 1980 1981## Running the appview 1982 1983The appview requires Redis and OAuth JWKs. Start these 1984first, before launching the appview itself. 1985 1986```bash 1987# OAuth JWKs should already be set up by the Nix devshell: 1988echo $TANGLED_OAUTH_CLIENT_SECRET 1989z42ty4RT1ovnTopY8B8ekz9NuziF2CuMkZ7rbRFpAR9jBqMc 1990 1991echo $TANGLED_OAUTH_CLIENT_KID 19921761667908 1993 1994# if not, you can set it up yourself: 1995goat key generate -t P-256 1996Key Type: P-256 / secp256r1 / ES256 private key 1997Secret Key (Multibase Syntax): save this securely (eg, add to password manager) 1998 z42tuPDKRfM2mz2Kv953ARen2jmrPA8S9LX9tRq4RVcUMwwL 1999Public Key (DID Key Syntax): share or publish this (eg, in DID document) 2000 did:key:zDnaeUBxtG6Xuv3ATJE4GaWeyXM3jyamJsZw3bSPpxx4bNXDR 2001 2002# the secret key from above 2003export TANGLED_OAUTH_CLIENT_SECRET="z42tuP..." 2004 2005# Run Redis in a new shell to store OAuth sessions 2006redis-server 2007``` 2008 2009The Nix flake exposes a few `app` attributes (run `nix 2010flake show` to see a full list of what the flake provides), 2011one of the apps runs the appview with the `air` 2012live-reloader: 2013 2014```bash 2015TANGLED_DEV=true nix run .#watch-appview 2016 2017# TANGLED_DB_PATH might be of interest to point to 2018# different sqlite DBs 2019 2020# in a separate shell, you can live-reload tailwind 2021nix run .#watch-tailwind 2022``` 2023 2024## Running knots and spindles 2025 2026An end-to-end knot setup requires setting up a machine with 2027`sshd`, `AuthorizedKeysCommand`, and a Git user, which is 2028quite cumbersome. So the Nix flake provides a 2029`nixosConfiguration` to do so. 2030 2031<details> 2032 <summary><strong>macOS users will have to set up a Nix Builder first</strong></summary> 2033 2034In order to build Tangled's dev VM on macOS, you will 2035first need to set up a Linux Nix builder. The recommended 2036way to do so is to run a [`darwin.linux-builder` 2037VM](https://nixos.org/manual/nixpkgs/unstable/#sec-darwin-builder) 2038and to register it in `nix.conf` as a builder for Linux 2039with the same architecture as your Mac (`linux-aarch64` if 2040you are using Apple Silicon). 2041 2042If you're on nix-darwin, you can simply add 2043 2044``` 2045nix.linux-builder.enable = true; 2046``` 2047 2048to your host's `configuration.nix`. 2049 2050Alternatively, you can use any other method to set up a 2051Linux machine with Nix installed that you can `sudo ssh` 2052into (in other words, root user on your Mac has to be able 2053to ssh into the Linux machine without entering a password) 2054and that has the same architecture as your Mac. See 2055[remote builder 2056instructions](https://nix.dev/manual/nix/2.28/advanced-topics/distributed-builds.html#requirements) 2057for how to register such a builder in `nix.conf`. 2058 2059> WARNING: If you'd like to use 2060> [`nixos-lima`](https://github.com/nixos-lima/nixos-lima) or 2061> [Orbstack](https://orbstack.dev/), note that setting them up so that `sudo 2062ssh` works can be tricky. It seems to be [possible with 2063> Orbstack](https://github.com/orgs/orbstack/discussions/1669). 2064 2065</details> 2066 2067To begin, grab your DID from http://localhost:3000/settings. 2068Then, set `TANGLED_VM_KNOT_OWNER` and 2069`TANGLED_VM_SPINDLE_OWNER` to your DID. You can now start a 2070lightweight NixOS VM like so: 2071 2072```bash 2073nix run --impure .#vm 2074 2075# type `poweroff` at the shell to exit the VM 2076``` 2077 2078This starts a knot on port 6444, a spindle on port 6555 2079with `ssh` exposed on port 2222. 2080 2081Once the services are running, head to 2082http://localhost:3000/settings/knots and hit "Verify". It should 2083verify the ownership of the services instantly if everything 2084went smoothly. 2085 2086You can push repositories to this VM with this ssh config 2087block on your main machine: 2088 2089```bash 2090Host nixos-shell 2091 Hostname localhost 2092 Port 2222 2093 User git 2094 IdentityFile ~/.ssh/my_tangled_key 2095``` 2096 2097Set up a remote called `local-dev` on a git repo: 2098 2099```bash 2100git remote add local-dev git@nixos-shell:user/repo 2101git push local-dev main 2102``` 2103 2104The above VM should already be running a spindle on 2105`localhost:6555`. Head to http://localhost:3000/settings/spindles and 2106hit "Verify". You can then configure each repository to use 2107this spindle and run CI jobs. 2108 2109Of interest when debugging spindles: 2110 2111``` 2112# Service logs from journald: 2113journalctl -xeu spindle 2114 2115# CI job logs from disk: 2116ls /var/log/spindle 2117 2118# Debugging spindle database: 2119sqlite3 /var/lib/spindle/spindle.db 2120 2121# litecli has a nicer REPL interface: 2122litecli /var/lib/spindle/spindle.db 2123``` 2124 2125If for any reason you wish to disable either one of the 2126services in the VM, modify [nix/vm.nix](/nix/vm.nix) and set 2127`services.tangled.spindle.enable` (or 2128`services.tangled.knot.enable`) to `false`. 2129 2130# Contribution guide 2131 2132## Commit guidelines 2133 2134We follow a commit style similar to the Go project. Please keep commits: 2135 2136- **atomic**: each commit should represent one logical change 2137- **descriptive**: the commit message should clearly describe what the 2138 change does and why it's needed 2139 2140### Message format 2141 2142``` 2143<service/top-level directory>/<affected package/directory>: <short summary of change> 2144 2145Optional longer description can go here, if necessary. Explain what the 2146change does and why, especially if not obvious. Reference relevant 2147issues or PRs when applicable. These can be links for now since we don't 2148auto-link issues/PRs yet. 2149``` 2150 2151Here are some examples: 2152 2153``` 2154appview/state: fix token expiry check in middleware 2155 2156The previous check did not account for clock drift, leading to premature 2157token invalidation. 2158``` 2159 2160``` 2161knotserver/git/service: improve error checking in upload-pack 2162``` 2163 2164### General notes 2165 2166- PRs get merged "as-is" (fast-forward)—like applying a patch-series 2167 using `git am`. At present, there is no squashing—so please author 2168 your commits as they would appear on `master`, following the above 2169 guidelines. 2170- If there is a lot of nesting, for example "appview: 2171 pages/templates/repo/fragments: ...", these can be truncated down to 2172 just "appview: repo/fragments: ...". If the change affects a lot of 2173 subdirectories, you may abbreviate to just the top-level names, e.g. 2174 "appview: ..." or "knotserver: ...". 2175- Keep commits lowercased with no trailing period. 2176- Use the imperative mood in the summary line (e.g., "fix bug" not 2177 "fixed bug" or "fixes bug"). 2178- Try to keep the summary line under 72 characters, but we aren't too 2179 fussed about this. 2180- Follow the same formatting for PR titles if filled manually. 2181- Don't include unrelated changes in the same commit. 2182- Avoid noisy commit messages like "wip" or "final fix"—rewrite history 2183 before submitting if necessary. 2184 2185## Code formatting 2186 2187We use a variety of tools to format our code, and multiplex them with 2188[`treefmt`](https://treefmt.com). All you need to do to format your changes 2189is run `nix run .#fmt` (or just `treefmt` if you're in the devshell). 2190 2191## Proposals for bigger changes 2192 2193Small fixes like typos, minor bugs, or trivial refactors can be 2194submitted directly as PRs. 2195 2196For larger changes—especially those introducing new features, significant 2197refactoring, or altering system behavior—please open a proposal first. This 2198helps us evaluate the scope, design, and potential impact before implementation. 2199 2200Create a new issue titled: 2201 2202``` 2203proposal: <affected scope>: <summary of change> 2204``` 2205 2206In the description, explain: 2207 2208- What the change is 2209- Why it's needed 2210- How you plan to implement it (roughly) 2211- Any open questions or tradeoffs 2212 2213We'll use the issue thread to discuss and refine the idea before moving 2214forward. 2215 2216## Developer Certificate of Origin (DCO) 2217 2218We require all contributors to certify that they have the right to 2219submit the code they're contributing. To do this, we follow the 2220[Developer Certificate of Origin 2221(DCO)](https://developercertificate.org/). 2222 2223By signing your commits, you're stating that the contribution is your 2224own work, or that you have the right to submit it under the project's 2225license. This helps us keep things clean and legally sound. 2226 2227To sign your commit, just add the `-s` flag when committing: 2228 2229```sh 2230git commit -s -m "your commit message" 2231``` 2232 2233This appends a line like: 2234 2235``` 2236Signed-off-by: Your Name <your.email@example.com> 2237``` 2238 2239We won't merge commits if they aren't signed off. If you forget, you can 2240amend the last commit like this: 2241 2242```sh 2243git commit --amend -s 2244``` 2245 2246If you're submitting a PR with multiple commits, make sure each one is 2247signed. 2248 2249For [jj](https://jj-vcs.github.io/jj/latest/) users, you can run the following command 2250to make it sign off commits in the tangled repo: 2251 2252```shell 2253# Safety check, should say "No matching config key..." 2254jj config list templates.commit_trailers 2255# The command below may need to be adjusted if the command above returned something. 2256jj config set --repo templates.commit_trailers "format_signed_off_by_trailer(self)" 2257``` 2258 2259Refer to the [jujutsu 2260documentation](https://jj-vcs.github.io/jj/latest/config/#commit-trailers) 2261for more information. 2262 2263# Troubleshooting guide 2264 2265## Login issues 2266 2267Owing to the distributed nature of OAuth on AT Protocol, you 2268may run into issues with logging in. If you run a 2269self-hosted PDS: 2270 2271- You may need to ensure that your PDS is timesynced using 2272 NTP: 2273 - Enable the `ntpd` service 2274 - Run `ntpd -qg` to synchronize your clock 2275- You may need to increase the default request timeout: 2276 `NODE_OPTIONS="--network-family-autoselection-attempt-timeout=500"` 2277 2278## Empty punchcard 2279 2280For Tangled to register commits that you make across the 2281network, you need to setup one of following: 2282 2283- The committer email should be a verified email associated 2284 to your account. You can add and verify emails on the 2285 settings page. 2286- Or, the committer email should be set to your account's 2287 DID: `git config user.email "did:plc:foobar"`. You can find 2288 your account's DID on the settings page 2289 2290## Commit is not marked as verified 2291 2292Presently, Tangled only supports SSH commit signatures. 2293 2294To sign commits using an SSH key with git: 2295 2296``` 2297git config --global gpg.format ssh 2298git config --global user.signingkey ~/.ssh/tangled-key 2299``` 2300 2301To sign commits using an SSH key with jj, add this to your 2302config: 2303 2304``` 2305[signing] 2306behavior = "own" 2307backend = "ssh" 2308key = "~/.ssh/tangled-key" 2309``` 2310 2311## Self-hosted knot issues 2312 2313If you need help troubleshooting a self-hosted knot, check 2314out the [knot troubleshooting 2315guide](/knot-self-hosting-guide.html#troubleshooting).