tangled
View as single-page

Migrating knots and spindles

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 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 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 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 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 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 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. 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 page.
  • Restart your knot once you have replaced the environment variable
  • Head to the knot dashboard 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:

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