Monorepo for Tangled
tangled.org
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.14.0-alpha
1624
1625Starting with v1.14.0-alpha, the fully knot uses the repoDID as its
1626canonical handle for repositories. This unlocks repository
1627renames from the appview UI and changes the wire format for
1628the following lexicons (`sh.tangled.repo.pull`, `sh.tangled.repo.collaborator`,
1629`sh.tangled.repo.issue`, `sh.tangled.git.refUpdate`).
1630
1631Knots that have not been upgraded may silently drop new push
1632events, pull requests, issues, and collaborator invites for
1633repositories they host until upgraded. So upgrade please!!!
1634
1635- Upgrade to the latest tag (v1.14.0 or above)
1636- Head to the [knot dashboard](https://tangled.org/settings/knots) and
1637 hit the "retry" button to verify your knot
1638
1639## Upgrading to v1.13.0-alpha
1640
1641Starting with v1.13.0-alpha, every repository on a knot is
1642assigned a DID. This makes repositories stable across
1643renames and transfers.
1644
1645When you upgrade your knot to this version, the server will
1646automatically mint DIDs for all existing repositories on
1647startup. This is a one-time process and you may see
1648additional log output during the first boot as DIDs are
1649assigned.
1650
1651- Upgrade to the latest tag (v1.13.0 or above)
1652- Head to the [knot dashboard](https://tangled.org/settings/knots) and
1653 hit the "retry" button to verify your knot
1654
1655## Upgrading from v1.8.x
1656
1657After v1.8.2, the HTTP API for knots and spindles has been
1658deprecated and replaced with XRPC. Repositories on outdated
1659knots will not be viewable from the appview. Upgrading is
1660straightforward however.
1661
1662For knots:
1663
1664- Upgrade to the latest tag (v1.9.0 or above)
1665- Head to the [knot dashboard](https://tangled.org/settings/knots) and
1666 hit the "retry" button to verify your knot
1667
1668For spindles:
1669
1670- Upgrade to the latest tag (v1.9.0 or above)
1671- Head to the [spindle
1672 dashboard](https://tangled.org/settings/spindles) and hit the
1673 "retry" button to verify your spindle
1674
1675## Upgrading from v1.7.x
1676
1677After v1.7.0, knot secrets have been deprecated. You no
1678longer need a secret from the appview to run a knot. All
1679authorized commands to knots are managed via [Inter-Service
1680Authentication](https://atproto.com/specs/xrpc#inter-service-authentication-jwt).
1681Knots will be read-only until upgraded.
1682
1683Upgrading is quite easy, in essence:
1684
1685- `KNOT_SERVER_SECRET` is no more, you can remove this
1686 environment variable entirely
1687- `KNOT_SERVER_OWNER` is now required on boot, set this to
1688 your DID. You can find your DID in the
1689 [settings](https://tangled.org/settings) page.
1690- Restart your knot once you have replaced the environment
1691 variable
1692- Head to the [knot dashboard](https://tangled.org/settings/knots) and
1693 hit the "retry" button to verify your knot. This simply
1694 writes a `sh.tangled.knot` record to your PDS.
1695
1696If you use the nix module, simply bump the flake to the
1697latest revision, and change your config block like so:
1698
1699```diff
1700 services.tangled.knot = {
1701 enable = true;
1702 server = {
1703- secretFile = /path/to/secret;
1704+ owner = "did:plc:foo";
1705 };
1706 };
1707```
1708
1709# Hacking on Tangled
1710
1711We highly recommend [installing
1712Nix](https://nixos.org/download/) (the package manager)
1713before working on the codebase. The Nix flake provides a lot
1714of helpers to get started and most importantly, builds and
1715dev shells are entirely deterministic.
1716
1717To set up your dev environment:
1718
1719```bash
1720nix develop
1721```
1722
1723Non-Nix users can look at the `devShell` attribute in the
1724`flake.nix` file to determine necessary dependencies.
1725
1726## Running the appview
1727
1728The appview requires Redis and OAuth JWKs. Start these
1729first, before launching the appview itself.
1730
1731```bash
1732# OAuth JWKs should already be set up by the Nix devshell:
1733echo $TANGLED_OAUTH_CLIENT_SECRET
1734z42ty4RT1ovnTopY8B8ekz9NuziF2CuMkZ7rbRFpAR9jBqMc
1735
1736echo $TANGLED_OAUTH_CLIENT_KID
17371761667908
1738
1739# if not, you can set it up yourself:
1740goat key generate -t P-256
1741Key Type: P-256 / secp256r1 / ES256 private key
1742Secret Key (Multibase Syntax): save this securely (eg, add to password manager)
1743 z42tuPDKRfM2mz2Kv953ARen2jmrPA8S9LX9tRq4RVcUMwwL
1744Public Key (DID Key Syntax): share or publish this (eg, in DID document)
1745 did:key:zDnaeUBxtG6Xuv3ATJE4GaWeyXM3jyamJsZw3bSPpxx4bNXDR
1746
1747# the secret key from above
1748export TANGLED_OAUTH_CLIENT_SECRET="z42tuP..."
1749
1750# Run Redis in a new shell to store OAuth sessions
1751redis-server
1752```
1753
1754The Nix flake exposes a few `app` attributes (run `nix
1755flake show` to see a full list of what the flake provides),
1756one of the apps runs the appview with the `air`
1757live-reloader:
1758
1759```bash
1760TANGLED_DEV=true nix run .#watch-appview
1761
1762# TANGLED_DB_PATH might be of interest to point to
1763# different sqlite DBs
1764
1765# in a separate shell, you can live-reload tailwind
1766nix run .#watch-tailwind
1767```
1768
1769## Running knots and spindles
1770
1771An end-to-end knot setup requires setting up a machine with
1772`sshd`, `AuthorizedKeysCommand`, and a Git user, which is
1773quite cumbersome. So the Nix flake provides a
1774`nixosConfiguration` to do so.
1775
1776<details>
1777 <summary><strong>macOS users will have to set up a Nix Builder first</strong></summary>
1778
1779In order to build Tangled's dev VM on macOS, you will
1780first need to set up a Linux Nix builder. The recommended
1781way to do so is to run a [`darwin.linux-builder`
1782VM](https://nixos.org/manual/nixpkgs/unstable/#sec-darwin-builder)
1783and to register it in `nix.conf` as a builder for Linux
1784with the same architecture as your Mac (`linux-aarch64` if
1785you are using Apple Silicon).
1786
1787If you're on nix-darwin, you can simply add
1788
1789```
1790nix.linux-builder.enable = true;
1791```
1792
1793to your host's `configuration.nix`.
1794
1795Alternatively, you can use any other method to set up a
1796Linux machine with Nix installed that you can `sudo ssh`
1797into (in other words, root user on your Mac has to be able
1798to ssh into the Linux machine without entering a password)
1799and that has the same architecture as your Mac. See
1800[remote builder
1801instructions](https://nix.dev/manual/nix/2.28/advanced-topics/distributed-builds.html#requirements)
1802for how to register such a builder in `nix.conf`.
1803
1804> WARNING: If you'd like to use
1805> [`nixos-lima`](https://github.com/nixos-lima/nixos-lima) or
1806> [Orbstack](https://orbstack.dev/), note that setting them up so that `sudo
1807ssh` works can be tricky. It seems to be [possible with
1808> Orbstack](https://github.com/orgs/orbstack/discussions/1669).
1809
1810</details>
1811
1812To begin, grab your DID from http://localhost:3000/settings.
1813Then, set `TANGLED_VM_KNOT_OWNER` and
1814`TANGLED_VM_SPINDLE_OWNER` to your DID. You can now start a
1815lightweight NixOS VM like so:
1816
1817```bash
1818nix run --impure .#vm
1819
1820# type `poweroff` at the shell to exit the VM
1821```
1822
1823This starts a knot on port 6444, a spindle on port 6555
1824with `ssh` exposed on port 2222.
1825
1826Once the services are running, head to
1827http://localhost:3000/settings/knots and hit "Verify". It should
1828verify the ownership of the services instantly if everything
1829went smoothly.
1830
1831You can push repositories to this VM with this ssh config
1832block on your main machine:
1833
1834```bash
1835Host nixos-shell
1836 Hostname localhost
1837 Port 2222
1838 User git
1839 IdentityFile ~/.ssh/my_tangled_key
1840```
1841
1842Set up a remote called `local-dev` on a git repo:
1843
1844```bash
1845git remote add local-dev git@nixos-shell:user/repo
1846git push local-dev main
1847```
1848
1849The above VM should already be running a spindle on
1850`localhost:6555`. Head to http://localhost:3000/settings/spindles and
1851hit "Verify". You can then configure each repository to use
1852this spindle and run CI jobs.
1853
1854Of interest when debugging spindles:
1855
1856```
1857# Service logs from journald:
1858journalctl -xeu spindle
1859
1860# CI job logs from disk:
1861ls /var/log/spindle
1862
1863# Debugging spindle database:
1864sqlite3 /var/lib/spindle/spindle.db
1865
1866# litecli has a nicer REPL interface:
1867litecli /var/lib/spindle/spindle.db
1868```
1869
1870If for any reason you wish to disable either one of the
1871services in the VM, modify [nix/vm.nix](/nix/vm.nix) and set
1872`services.tangled.spindle.enable` (or
1873`services.tangled.knot.enable`) to `false`.
1874
1875# Contribution guide
1876
1877## Commit guidelines
1878
1879We follow a commit style similar to the Go project. Please keep commits:
1880
1881- **atomic**: each commit should represent one logical change
1882- **descriptive**: the commit message should clearly describe what the
1883 change does and why it's needed
1884
1885### Message format
1886
1887```
1888<service/top-level directory>/<affected package/directory>: <short summary of change>
1889
1890Optional longer description can go here, if necessary. Explain what the
1891change does and why, especially if not obvious. Reference relevant
1892issues or PRs when applicable. These can be links for now since we don't
1893auto-link issues/PRs yet.
1894```
1895
1896Here are some examples:
1897
1898```
1899appview/state: fix token expiry check in middleware
1900
1901The previous check did not account for clock drift, leading to premature
1902token invalidation.
1903```
1904
1905```
1906knotserver/git/service: improve error checking in upload-pack
1907```
1908
1909### General notes
1910
1911- PRs get merged "as-is" (fast-forward)—like applying a patch-series
1912 using `git am`. At present, there is no squashing—so please author
1913 your commits as they would appear on `master`, following the above
1914 guidelines.
1915- If there is a lot of nesting, for example "appview:
1916 pages/templates/repo/fragments: ...", these can be truncated down to
1917 just "appview: repo/fragments: ...". If the change affects a lot of
1918 subdirectories, you may abbreviate to just the top-level names, e.g.
1919 "appview: ..." or "knotserver: ...".
1920- Keep commits lowercased with no trailing period.
1921- Use the imperative mood in the summary line (e.g., "fix bug" not
1922 "fixed bug" or "fixes bug").
1923- Try to keep the summary line under 72 characters, but we aren't too
1924 fussed about this.
1925- Follow the same formatting for PR titles if filled manually.
1926- Don't include unrelated changes in the same commit.
1927- Avoid noisy commit messages like "wip" or "final fix"—rewrite history
1928 before submitting if necessary.
1929
1930## Code formatting
1931
1932We use a variety of tools to format our code, and multiplex them with
1933[`treefmt`](https://treefmt.com). All you need to do to format your changes
1934is run `nix run .#fmt` (or just `treefmt` if you're in the devshell).
1935
1936## Proposals for bigger changes
1937
1938Small fixes like typos, minor bugs, or trivial refactors can be
1939submitted directly as PRs.
1940
1941For larger changes—especially those introducing new features, significant
1942refactoring, or altering system behavior—please open a proposal first. This
1943helps us evaluate the scope, design, and potential impact before implementation.
1944
1945Create a new issue titled:
1946
1947```
1948proposal: <affected scope>: <summary of change>
1949```
1950
1951In the description, explain:
1952
1953- What the change is
1954- Why it's needed
1955- How you plan to implement it (roughly)
1956- Any open questions or tradeoffs
1957
1958We'll use the issue thread to discuss and refine the idea before moving
1959forward.
1960
1961## Developer Certificate of Origin (DCO)
1962
1963We require all contributors to certify that they have the right to
1964submit the code they're contributing. To do this, we follow the
1965[Developer Certificate of Origin
1966(DCO)](https://developercertificate.org/).
1967
1968By signing your commits, you're stating that the contribution is your
1969own work, or that you have the right to submit it under the project's
1970license. This helps us keep things clean and legally sound.
1971
1972To sign your commit, just add the `-s` flag when committing:
1973
1974```sh
1975git commit -s -m "your commit message"
1976```
1977
1978This appends a line like:
1979
1980```
1981Signed-off-by: Your Name <your.email@example.com>
1982```
1983
1984We won't merge commits if they aren't signed off. If you forget, you can
1985amend the last commit like this:
1986
1987```sh
1988git commit --amend -s
1989```
1990
1991If you're submitting a PR with multiple commits, make sure each one is
1992signed.
1993
1994For [jj](https://jj-vcs.github.io/jj/latest/) users, you can run the following command
1995to make it sign off commits in the tangled repo:
1996
1997```shell
1998# Safety check, should say "No matching config key..."
1999jj config list templates.commit_trailers
2000# The command below may need to be adjusted if the command above returned something.
2001jj config set --repo templates.commit_trailers "format_signed_off_by_trailer(self)"
2002```
2003
2004Refer to the [jujutsu
2005documentation](https://jj-vcs.github.io/jj/latest/config/#commit-trailers)
2006for more information.
2007
2008# Troubleshooting guide
2009
2010## Login issues
2011
2012Owing to the distributed nature of OAuth on AT Protocol, you
2013may run into issues with logging in. If you run a
2014self-hosted PDS:
2015
2016- You may need to ensure that your PDS is timesynced using
2017 NTP:
2018 - Enable the `ntpd` service
2019 - Run `ntpd -qg` to synchronize your clock
2020- You may need to increase the default request timeout:
2021 `NODE_OPTIONS="--network-family-autoselection-attempt-timeout=500"`
2022
2023## Empty punchcard
2024
2025For Tangled to register commits that you make across the
2026network, you need to setup one of following:
2027
2028- The committer email should be a verified email associated
2029 to your account. You can add and verify emails on the
2030 settings page.
2031- Or, the committer email should be set to your account's
2032 DID: `git config user.email "did:plc:foobar"`. You can find
2033 your account's DID on the settings page
2034
2035## Commit is not marked as verified
2036
2037Presently, Tangled only supports SSH commit signatures.
2038
2039To sign commits using an SSH key with git:
2040
2041```
2042git config --global gpg.format ssh
2043git config --global user.signingkey ~/.ssh/tangled-key
2044```
2045
2046To sign commits using an SSH key with jj, add this to your
2047config:
2048
2049```
2050[signing]
2051behavior = "own"
2052backend = "ssh"
2053key = "~/.ssh/tangled-key"
2054```
2055
2056## Self-hosted knot issues
2057
2058If you need help troubleshooting a self-hosted knot, check
2059out the [knot troubleshooting
2060guide](/knot-self-hosting-guide.html#troubleshooting).