Organizations and access

Organizations, members and roles, groups, and who can see a repository.

Markdown

All pages

Organizations#

Every repository belongs to an organization, and its URL is oak.space/<organization>/<repo>. Every account comes with a personal organization named after its username; create shared ones for groups and companies from your dashboard (or POST /api/orgs).

The organization is also where storage is accounted and deduplicated: content is stored once per organization, so the same large asset committed to five of its repos costs one copy. Each repo's first push of it still uploads it, since a repo can only use content it has sent or published itself. Storage quotas are per organization; see Plans and limits.

A personal organization always has exactly one member. To work with others, create a shared organization and invite them.

Members and roles#

RoleCan
OwnerEverything, including deleting the organization.
AdminManage members, groups and what they can reach, the organization's agents, and settings. Full access to every repo.
MemberCreate repos in the organization, and read or write the repos they've been given access to.

The organization's people are its built-in members group: manage them under People in Settings → Groups (oak.space/<org>/settings), where owners and admins add people, change their role and remove them, and anyone can leave. From the terminal, oak group add members alice adds someone and oak group remove members alice takes them out. Removing someone (or someone leaving) also takes away everything they were granted inside the organization: their group memberships, and any repo they were added to on their own. Admins and owners can always read and write every repo in the organization, and can change any of a repo's boundaries.

Who can see a repository#

Access to a repo is given to groups. Give a group Read or Write on a repo, and everyone in the group gets that, along with any agent keys made for it. Every organization has two built-in groups:

GroupWho's in it
publicAnyone, signed in or not. Giving it Read on a repo is what makes the repo public: readable on the web and with oak clone. It can't be given Write.
membersEveryone in the organization: adding someone to it adds them to the organization. Give it Read or Write on a repo to share it with the whole organization.

Beyond those, a repo can be read by:

Being a plain member of the organization doesn't by itself give access to its private repos, until the members group (or another group they're in) is given access. Only people with Write can push branches or merge, unless the repo takes external contributions.

Who's in each group and what it can do in a repo are set in that repo's Settings → Access: the groups and people who can reach it, each Read or Write and each group with its members under it, with the switch between public and private, and the repo's path rules below it. From the terminal, oak group grant web mono --role write gives a group access, and oak group grant public mono makes a repo public (oak group revoke undoes either). PATCH /api/{owner}/{name}/visibility still switches a repo between public and private.

Inside a repo, path rules can narrow access to particular folders, or publish parts of a private repo to everyone.

External contributions#

Owners and admins can let people without write access contribute, the way a pull request from a fork works on GitHub. Turn on Allow external contributions under the repo's Settings → General. It's off by default.

With it on, anyone who can read the repo (for a public repo, any signed-in person or agent) can clone it and push a branch of their own:

oak clone acme/widgets
cd widgets
oak switch -c fix-typo-in-readme
# ...edit...
oak desc "Fix a typo in the README"
oak commit --push

Their branch shows up on the repo's branch board marked External, with who opened it, and the branch API reports it as "external": {"author": "<username>"}. From there:

Groups#

Groups, nested groups, the organization's own agents and oak group switch have their own page: Groups.

Moving and renaming#

Archiving a repository#

Owners and admins can archive a repo from its Settings → Danger (or POST /api/{owner}/{name}/archive) when it's no longer maintained but should stay around. An archived repo is read-only: pushes, new branches, merges, branch changes and settings edits are refused, while its code, branches and commits stay browsable and it can still be cloned. Every page of the repo says it's archived. Unarchive it from the same place (or POST /api/{owner}/{name}/unarchive) to make it writable again. An archived repo can still be transferred or deleted.

Audit log#

Owners and admins can see who did what — membership changes, merges, merges forced past approvals, settings changes — with GET /api/orgs/{slug}/audit.

The organization page#

oak.space/<org> is the organization's landing page: a list of its repos that the visitor can see. Under Settings → General you can choose whether people outside the organization can see it. To publish a static website from a repo, see Pages.

Something here wrong or missing? Run oak feedback -m "…" or email [email protected].