---
title: Migrating knots and spindles
description: Upgrade guides for non-backwards compatible knot/spindle changes.
---


Sometimes, non-backwards compatible changes are made to the
knot/spindle XRPC APIs. If you host a knot or a spindle, you
will need to follow this guide to upgrade. Typically, this
only requires you to deploy the newest version.

This document is laid out in reverse-chronological order.
Newer migration guides are listed first, and older guides
are further down the page.

## Upgrading to v1.16.0-alpha

Starting with v1.16.0-alpha, spindles own CI pipeline data
directly. The appview no longer stores pipeline runs or follows
spindle event streams for pipeline history. Instead, it asks the
configured spindle for pipeline lists, single pipeline details,
workflow logs, retries, and cancellations over XRPC.

This means that existing pipeline logs / runs won't appear after
you upgrade. Existing pipeline history from the appview cannot be
automatically migrated. If you want to migrate your data, you can
reach out to us and we will send you an SQL file that'll add the data
into your spindle.

- Upgrade to the latest tag (v1.16.0 or above)
- Head to the [spindle
  dashboard](https://tangled.org/settings/spindles) and hit the
  "retry" button to verify your spindle

## Upgrading to v1.15.0-alpha

With v1.15.0-alpha, a knot itself owns its members and
per-repo collaborators directly. Previously this data was sourced from
PDS records (`sh.tangled.knot.member` and `sh.tangled.repo.collaborator`)
that the appview and the knot both read off the firehose.
The knot is now the source of truth and serves them over XRPC instead:

- `sh.tangled.knot.addMember`, `sh.tangled.knot.removeMember`, `sh.tangled.knot.listMembers`
- `sh.tangled.repo.addCollaborator`, `sh.tangled.repo.removeCollaborator`, `sh.tangled.repo.listCollaborators`

Until your knot is upgraded, the appview keeps reading its
members and collaborators from the old firehose-sourced records.
Upgrade to move your knot onto knot-owned access control.

- Upgrade to the latest tag (v1.15.0 or above)
- Head to the [knot dashboard](https://tangled.org/settings/knots) and
  hit the "retry" button to verify your knot

## Upgrading to v1.14.0-alpha

Starting with v1.14.0-alpha, the fully knot uses the repoDID as its
canonical handle for repositories. This unlocks repository
renames from the appview UI and changes the wire format for
the following lexicons (`sh.tangled.repo.pull`, `sh.tangled.repo.collaborator`,
`sh.tangled.repo.issue`, `sh.tangled.git.refUpdate`).

Knots that have not been upgraded may silently drop new push
events, pull requests, issues, and collaborator invites for
repositories they host until upgraded. So upgrade please!!!

- Upgrade to the latest tag (v1.14.0 or above)
- Head to the [knot dashboard](https://tangled.org/settings/knots) and
  hit the "retry" button to verify your knot

## Upgrading to v1.13.0-alpha

Starting with v1.13.0-alpha, every repository on a knot is
assigned a DID. This makes repositories stable across
renames and transfers.

When you upgrade your knot to this version, the server will
automatically mint DIDs for all existing repositories on
startup. This is a one-time process and you may see
additional log output during the first boot as DIDs are
assigned.

- Upgrade to the latest tag (v1.13.0 or above)
- Head to the [knot dashboard](https://tangled.org/settings/knots) and
  hit the "retry" button to verify your knot

## Upgrading from v1.8.x

After v1.8.2, the HTTP API for knots and spindles has been
deprecated and replaced with XRPC. Repositories on outdated
knots will not be viewable from the appview. Upgrading is
straightforward however.

For knots:

- Upgrade to the latest tag (v1.9.0 or above)
- Head to the [knot dashboard](https://tangled.org/settings/knots) and
  hit the "retry" button to verify your knot

For spindles:

- Upgrade to the latest tag (v1.9.0 or above)
- Head to the [spindle
  dashboard](https://tangled.org/settings/spindles) and hit the
  "retry" button to verify your spindle

## Upgrading from v1.7.x

After v1.7.0, knot secrets have been deprecated. You no
longer need a secret from the appview to run a knot. All
authorized commands to knots are managed via [Inter-Service
Authentication](https://atproto.com/specs/xrpc#inter-service-authentication-jwt).
Knots will be read-only until upgraded.

Upgrading is quite easy, in essence:

- `KNOT_SERVER_SECRET` is no more, you can remove this
  environment variable entirely
- `KNOT_SERVER_OWNER` is now required on boot, set this to
  your DID. You can find your DID in the
  [settings](https://tangled.org/settings) page.
- Restart your knot once you have replaced the environment
  variable
- Head to the [knot dashboard](https://tangled.org/settings/knots) and
  hit the "retry" button to verify your knot. This simply
  writes a `sh.tangled.knot` record to your PDS.

If you use the nix module, simply bump the flake to the
latest revision, and change your config block like so:

```diff
 services.tangled.knot = {
   enable = true;
   server = {
-    secretFile = /path/to/secret;
+    owner = "did:plc:foo";
   };
 };
```
