# Access and collaborators

> Who can push, merge, moderate and administer a repository, and how collaborators and contribution policies work.

Access to a repository is decided by its knot. The knot knows four kinds of people: the repository **owner**, the repository’s **collaborators**, the knot’s **members**, and the knot’s **admins**. Everyone else is a stranger. The web app only hides controls you can’t use; the knot enforces the rules.

## Roles

| Role         | Who                                               | Where it is recorded           |
| ------------ | ------------------------------------------------- | ------------------------------ |
| Owner        | The account that created the repository           | The knot’s repository registry |
| Collaborator | Accounts the owner added                          | The repository, on the knot    |
| Knot member  | Accounts admitted to the knot, usually by invite  | The knot’s member list         |
| Knot admin   | DIDs listed in the knot’s `server.admins` setting | The knot’s config file         |

A knot also keeps a blocklist. A blocked account can’t push, write issues or comments, or create repositories on that knot, whatever its other roles. Admins can’t be blocked.

## What each role can do

| Action                                                           | Owner | Collaborator | Knot admin | Anyone else |
| ---------------------------------------------------------------- | ----- | ------------ | ---------- | ----------- |
| Push, delete branches                                            | Yes   | Yes          | No         | No          |
| Merge pull requests                                              | Yes   | Yes          | No         | No          |
| Rename on the knot, set default branch                           | Yes   | Yes          | No         | No          |
| Close, reopen, edit or delete others’ issues, pulls and comments | Yes   | Yes          | Yes        | No          |
| Apply labels (web app)                                           | Yes   | Yes          | No         | No          |
| Define labels                                                    | Yes   | No           | No         | No          |
| Add or remove collaborators                                      | Yes   | No           | No         | No          |
| Set the contribution policy                                      | Yes   | No           | Yes        | No          |
| Delete the repository                                            | Yes   | No           | Yes        | No          |
| Open issues and pull requests, comment, react                    | Yes   | Yes          | By policy  | By policy   |
| Manage pipeline secrets (on the spindle)                         | Yes   | Yes          | No         | No          |

Knot admins moderate every repository on their knot, but they are not maintainers of other people’s repositories: they can’t push, merge or define labels there. Knot members get no rights over other people’s repositories; membership only matters for creating repositories and for the `members` contribution policy.

## Collaborators

The owner adds collaborators under **Settings → Access → Add collaborator** by searching for a handle. The web app sends the change to the knot, and from then on the collaborator can push and merge. The collaborator sees the repository’s **Settings** tab with the default branch and pipeline secrets, but not the owner-only sections. Removing a collaborator on the same page takes effect on the knot immediately.

## Contribution policy

Each repository has a contribution policy that decides who may open issues and pull requests, comment and react. It doesn’t affect pushing, which always needs the owner or a collaborator.

| Policy          | Who may contribute                                |
| --------------- | ------------------------------------------------- |
| `anyone`        | Any account the knot hasn’t blocked               |
| `members`       | The owner, collaborators, and members of the knot |
| `collaborators` | The owner and collaborators only                  |

A new repository takes the knot’s default, set by `repo.contribution_policy` in the knot config, which is `collaborators` unless the operator changes it. When the policy refuses you, the knot answers:

```text
Please ask the repo owner to add you as a collaborator, or to open the contribution policy to members or anyone, thanks.
```

## Knot membership

Members can create repositories on a knot whose `acl.admission` is `closed`, the default. With `open` admission, anyone not blocked can create repositories. Admins create invite codes with `knot-server admin create-invite-code`; you redeem one through an invite link (`/invite?knot=<host>&code=<code>`), which also saves the knot in **Settings → Knots**. Invite codes expire after two days and don’t survive a knot restart.

## When access fails

Check where the action happens:

* **Push and clone**: the knot. It matches your SSH key against the keys in your PDS, caching them for about an hour, so a key you just added or removed can take a moment to take effect.
* **Issues, pulls, comments, merges**: the knot, using the roles and policy above.
* **Pipeline secrets and runs**: the spindle, which keeps its own view of owners and collaborators.
* **Profile, stars, follows**: your PDS.

[Troubleshooting](/docs/troubleshooting/) covers common SSH failures.