# 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

```sh
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](collaborating.md#give-someone-write-access) 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](workflows.md#start-a-runner) checks a private repository as it does a public
one, once the owner names it:

```sh
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](../design/gateway.md#bots), 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](workflows.md#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](server.md#serve-the-web-pages)) shows
private repositories the same way, once you log in to its pages; it
needs `--public-url` for that.

[Access](../design/access.md#private-repositories) explains how spaces,
credentials and members work.