Using Moru
Organizations and access
Who can see and change a repository: owners, organizations, collaborators, roles, visibility and the signed access record.
Every repository has an owner, which is the first part of its name: mira/notes belongs to the person mira, acme/timetable to the organization acme. What anyone else may do in it comes from their role, and whether people without a role can see it comes from its visibility.
Roles#
There are three roles on a repository, each including the one before it.
| Role | What it allows |
|---|---|
| Read | Clone and fetch, and see everything in the repository: code, changes, requests, conversations. Comment and react, and file requests, which wait in triage, unless the repository limits either to writers. |
| Write | Push, file, edit, triage and plan requests, start and cancel attempts, decide Bake-offs, approve and merge changes, edit labels and milestones. Also see job logs and runner details. |
| Admin | The repository’s settings: visibility, collaborators, merge rules, who can comment, who can file requests, trusted attesters, webhooks, the GitHub link, deleting the repository. |
A person’s role in a repository is the highest they get from any of these:
- The person whose handle owns the repository is its admin.
- An owner of the organization that owns it is its admin.
- A member of that organization gets the organization’s default role.
- A collaborator entry on the repository gives the role it names.
Agents act with the role of the person who started them, limited further by their token. Site admins of the node get no access to a repository just for being site admins: add them like anyone else.
Visibility#
A repository is Public or Private.
- Public: anyone can read it, signed in or not. Job logs and runner details stay with people who have write.
- Private: only the owner, organization members and collaborators can see it. To everyone else it doesn’t exist: its pages and API answer “not found”.
Admins change it in the repository’s Settings, in the Danger zone at the bottom, with Make public or Make private. Moru asks before it changes.
Collaborators#
Collaborators are people given a role on one repository. Admins manage them in the repository’s Settings → Collaborators.
- Type the person’s Handle, for example
jon. They need an account on this node. - Pick a Role: Read, Write or Admin.
- Click Add.
Change someone’s role with the menu beside their name, or take it away with Remove. The person who owns the repository’s namespace is always its admin and can’t be removed.
An entry marked “No account here yet” names someone who has no account on this node. These come from an applied access record, for example after an import. The entry is kept by the person’s identity (their DID), so it applies to whoever signs in here with that identity.
Organizations#
An organization owns repositories on behalf of a group of people. Its name shares one namespace with people’s handles, so there can’t be a person acme and an organization acme.
Create one#
Any signed-in person can create an organization: open the account menu in the header and choose New organization, or pick it from the command menu. Enter a Name and click Create organization. You become its first owner.
Members and owners#
An organization has two kinds of member:
- Owner: admin on every repository of the organization, and manages the organization itself.
- Member: gets the organization’s default role on its repositories.
Open the organization from the account menu (your organizations are listed there) to manage it.
Owners can:
- add people under Members by Handle, as Member or Owner,
- change a member’s role, or remove them,
- set Members’ role on its repos under Settings: None, Read or Write. A new organization starts with None, so members see only the repositories they’re added to,
- tick Members can create repos to let members, not only owners, create repositories under the organization.
A member can leave with Leave. An organization always keeps at least one owner: the last owner can’t leave or be made a member.
A collaborator entry on one of the organization’s repositories still counts for members. For example, with the default role Read, you can make one member a Write collaborator on acme/timetable only.
Who can create repositories where#
You can create, import or link repositories under your own handle, under organizations you own, and under organizations that let members create repositories.
Access records#
The node enforces roles and visibility from its own configuration. Moru also keeps a signed copy of each repository’s access in the repository itself, so the record of who may do what travels with the code when the repository is cloned, backed up or moved to another node.
A repository’s access record holds its owner, visibility, who can comment, who can file requests, protected branches, the approval rule, collaborators with who granted each role, and trusted attesters. Every change an admin makes through Moru is written to the record too, signed by that admin.
An organization has a record of its own, with its members and settings, kept in the organization’s own repository, acme/.moru. Members can read that repository; it changes only through the organization’s page.
Check a record#
Admins see the record at the bottom of the repository’s Settings, under Access record. Organization owners see the organization’s record on its page, under Record. A badge tells you where it stands:
- In step: the record says what the node enforces.
- Out of step: they differ, for example after someone edited the node’s files by hand. Click Bring the record in line to write the current settings into the record.
- Problem: the record can’t be read or written; the reason is shown.
The record view marks the owner Verified when this node can confirm the record was written by the repository’s owner, and Not verified otherwise, with the reason.
Apply a record after an import#
When you import a repository from another node, its access record comes along. Rules that give no one access are taken at once, where they’re stricter than this node’s defaults: the protected branches, “approval from someone other than the author”, “only writers can comment” and “only writers can file requests”. The default branch is protected too, as in a new repository. The people the record names get no access on this node until an admin decides so. The import result shows the record, and any earlier owner’s record under An earlier owner’s access record.
To apply one:
- Choose what to take beyond read and write collaborators: Admins, Trusted attesters, and Visibility.
- Click Preview. Moru shows what would change: who would be added, which entries conflict with ones the repository already has, and who is skipped and why.
- Click Apply.
Applying adds collaborators the repository doesn’t have yet. It never changes a role the repository already gives someone (those show as conflicts), never adds the owner of the namespace, and never changes the owner. Rules only get stricter: applying adds the record’s protected branches to the repository’s, turns on “approval from someone other than the author” if the record has it, and limits comments and requests to writers if the record does. It never removes a protected branch or relaxes a rule; do that in Settings. The preview lists these changes too.
If the record is Not verified, Apply stays disabled until you tick the box that says you apply it anyway.