Private repositories

A private repository lives in a permissioned space on the owner’s PDS, at://<did>/space/dev.knotless.space/<name>, and holds the same records as a public one. Each member writes their issues and comments into their own repo inside the space, so the conversation is as private as the code.

Before you start

Spaces are in the reference PDS’s permissioned-data alpha. On a PDS without them, every repository is public.

Members read a private repository with a space credential, and getting one takes an OAuth login (knotless login without --password-stdin). An app password cannot read someone else’s private repository.

Create and share one

knotless create knotless://alice.test/secret --private
git push knotless://alice.test/secret main
knotless share knotless://alice.test/secret bob.test           # bob may clone
knotless share knotless://alice.test/secret carol.test --write # carol may push too
knotless members knotless://alice.test/secret

Every member can read the repository and write issues and comments in it. Pushing is a separate grant (--write), and goes through a gateway as it does for a public repository.

A fork of a private repository is private. It is shared for reading with the source’s owner, so that they can take pulls from it.

Run checks on one

A runner checks a private repository as it does a public one, once the owner names it:

knotless runners knotless://alice.test/secret add ci.alice.test

That also makes the runner’s account a member, to read the repository. Its checks, logs and pictures are written in the space, so only members see them with knotless checks. The runner’s account logs in with OAuth, since reading a space takes a space credential that an app password cannot get: knotless login ci.alice.test on its machine, or, for a runner beside a knotless-serve, through that server’s bot login, whose session lasts two years rather than two weeks. It hears of pushes by asking the space every --poll seconds rather than from Jetstream, and, as with any repository, runs only what is pushed after it starts watching (Start a runner).

Browse one

Log in to the pages (Log in, at the top of any page of https://knotless.dev) as a member, and open the repository’s page, https://knotless.dev/alice.test/secret: it shows as a public one does, with a Private badge, to you alone. Your own private repositories are listed on your profile there, to you alone. Anyone else, logged in or not, finds no such repository. Someone you unshare it with stops seeing it within a minute.

The appview keeps an index of it, synced from the space and shown only to members, so its pages load as a public repository’s do however many members it has. One you make with knotless create --private while logged in there is in that index before you look, and lists on your profile at once; others join it as you log in or a member reads them there. A server of your own (Serve the web pages) shows private repositories the same way, once you log in to its pages; it needs --public-url for that.

Access explains how spaces, credentials and members work.