# Organizations

Create an organization, invite people, group them into teams and set the rules its repositories follow.

## Create one and invite someone

```sh
sailfork org create acme --name "Acme" --tagline "Tools for tide tables"
sailfork org invite acme maya
sailfork org members acme
```

`org create` makes you the organization's only owner. `org invite` takes a Sailfork handle or an email address, and the person joins with the role `member` unless you pass `--role owner`. Nobody joins until they accept.

## What an organization is

An organization owns repositories, caissons and compute together, and groups people under two roles, Owner and Member. Its address is `https://sailfork.com/acme`. A repository in an organization belongs to the organization, not to whoever created it. Every member can create repositories in it.

Roles, teams and the rest of the access model are in [Roles and permissions](https://sailfork.com/docs/permissions). Billing is in [Plans, billing and usage](https://sailfork.com/docs/billing).

## Create an organization

In the web app, open Settings, Organizations, find Create an organization, enter a Name and a Handle, and choose Create organization. You become its only owner.

With the CLI:

```sh
sailfork org create acme --name "Acme" --tagline "Tools for tide tables" --time-zone America/Los_Angeles
sailfork org create acme --dry-run
```

| Flag | Meaning |
| --- | --- |
| `<handle>` | 1 to 39 letters, digits and hyphens. Organizations and people share one namespace, so a handle a person already has is taken. |
| `--name` | Display name. It defaults to the handle. 1 to 100 characters. |
| `--tagline` | One line about the organization. |
| `--time-zone` | An IANA name such as `America/Los_Angeles`. It defaults to UTC. |
| `--dry-run` | Says what would be created and changes nothing. |

A taken handle fails with `pick another handle`.

Look at your organizations with `sailfork org list`, which prints HANDLE, NAME, ROLE, REPOS and JOINED, and at one with `sailfork org view acme`. `sailfork org members acme` prints HANDLE, NAME and ROLE for each member.

## The organization pages

Switch between your personal workspace and each organization from the workspace menu at the top of the sidebar. An organization has these pages under `https://sailfork.com/acme`:

| Page | What it shows |
| --- | --- |
| Overview (`/acme`) | The profile, pinned repositories, recent activity and the members who chose to be public. |
| Repositories | Every repository the organization owns that you can read. |
| Activity (`/acme/activity`) | See [Activity](#activity). |
| Inbox | Pull requests and agent work waiting on you. |
| Caissons | Agent worktrees for the organization's repositories. See [Caissons](https://sailfork.com/docs/caissons). |
| Sandboxes | Sandboxes on the organization's Drydock hosts. See [Sandboxes](https://sailfork.com/docs/sandboxes). |
| Moving to Sailfork | Repositories being copied in from GitHub. See [Move from GitHub](https://sailfork.com/docs/migrate). |
| Settings | The sections in [Organization settings](#organization-settings). |

New repositories go under the organization from the New repository form, or with `sailfork repo create acme/ocean-landing`.

### Activity

`https://sailfork.com/acme/activity` lists the latest 30 events across the organization's repositories, each with who did it, what, the repository and how long ago. Agents are labeled as agents. It shows only repositories the viewer can read, so a signed-out visitor sees events from public repositories only, and a member sees private ones too. It has no filter or paging, and an organization with no events shows `No activity yet`. For a personal account the same address goes to the Activity section of the profile.

### View as

Members see a View as switch at the top of the Overview, with the choices Member and Public. Public reloads the page with `?as=public` and shows the organization as someone outside it sees it: public repositories only, only the members who chose to be listed publicly, and no queue or private work. A note says so, with a link back to the member view. The switch only changes what the page draws. It grants and hides nothing on the server, and people who are not members, signed out included, always get the public view. Your own profile has the same switch with You and Public. See [Your account](https://sailfork.com/docs/account#profile).

## Members

Settings, People lists everyone in the organization. The page tells owners and members apart with these actions:

- **Change a role.** An owner picks Owner or Member for a person. Role changes wait for Save.
- **Remove.** An owner removes a person. It applies at once and ends their access to every repository.
- **Leave.** Any member can leave from their own row, or from Settings, Organizations. It applies at once, and an owner can invite them back.

The organization always keeps at least one owner. Removing or demoting the last owner fails with `an organization needs at least one owner: make someone else an owner first`.

Each member can choose whether the organization page lists them publicly. Members always see the full list.

## Invite people

Only owners invite. In Settings, People, under Invite people, enter an email address or `@handle`, choose Owner or Member, and choose Send invitation.

```sh
sailfork org invite acme maya
sailfork org invite acme maya@example.com --role owner
sailfork org invite acme maya --dry-run
```

The `who` argument is an email address when it contains an `@`, otherwise a handle. An invitation for a handle shows up in that person's account at once. An invitation for an email address goes to that address, and whoever holds the invitation link can use it.

- **Expiry.** An invitation stops working 7 days after it is sent.
- **Seats.** Each accepted invitation adds a seat. See [Plans, billing and usage](https://sailfork.com/docs/billing).
- **Mail that did not go out.** If the server could not send the email, the CLI prints `No email went out` and a link to give the person. The People page says `The email did not go out. Copy the link and send it yourself.` and shows a Copy link button.
- **Already a member.** Inviting someone who belongs fails with `<who> already belongs to Acme`.

Pending invitations show under Invite people with Resend and Revoke. From the CLI:

```sh
sailfork org invites list acme
sailfork org invites revoke acme <invitation-id>
```

`org invites list <org>` prints ID, INVITEE, ROLE, INVITED BY and SENT. Both commands are for owners. Anyone else gets `only owners of acme can see its invitations` or `only owners of acme can revoke invitations`, followed by the list of owners.

## Answer an invitation

A pending invitation appears as Join Acme in the sidebar, under Invitations in Settings, Organizations, and in the invitation email. Choose Accept or Decline. Accepting adds you at once with the role you were invited with.

```sh
sailfork org invites list
sailfork org invites accept acme
sailfork org invites decline acme
```

With no organization, `org invites list` prints the invitations sent to you, with ID, ORG, ROLE, INVITED BY and SENT. `accept` and `decline` take the invitation id or the organization's handle.

> [!IMPORTANT]
> An invitation sent to an email address can be answered only after you verify that address. Until then you get `verify <address> first; the invitation went to that address`. Verify it under Settings, Account. See [Your account](https://sailfork.com/docs/account#email-addresses).

An invitation that expired, was revoked or was already answered fails with `that invitation is not waiting for you; it may have expired, been revoked or been answered`.

Repository invitations for collaborators on personal repositories show in the same Invitations list. See [Roles and permissions](https://sailfork.com/docs/permissions).

## Teams

Teams give groups of members access to specific repositories. Open Settings, Teams, and choose New team. Give it a Name and a Slug (1 to 60 letters, digits and hyphens), and optionally a parent team.

- **Members and maintainers.** Add members to a team. A maintainer can add and remove that team's members without being an owner.
- **Repositories.** Grant a team Read, Write or Admin on each repository.
- **Parent teams.** A child team inherits the repositories of its parent.
- **Effective access.** A person gets the highest of their organization's base access and every team they are in, including parent teams.

Only owners create and delete teams and change what repositories a team reaches. Changes on the Teams page wait for Save.

Teams need an organization. A personal repository gives access through [collaborators](https://sailfork.com/docs/permissions).

## Organization repositories

Every repository in an organization has an access level for each member, worked out from the member's role, the organization's base access and their teams. Owners always have admin access.

Repository admins can transfer a repository. A repository moves between you and an organization you belong to from its settings, under Transfer or delete. The old address keeps forwarding, so existing remotes keep working. When a repository moves into an organization, its collaborators and their invitations are removed, because the organization gives access through teams.

Deleting a repository takes admin access to it, and the repository is removed 14 days after you confirm.

## Organization settings

Open them from Settings at `https://sailfork.com/acme/settings`. Only owners can change them.

| Section | What you set |
| --- | --- |
| General | Logo, Name, Tagline, Location, Website, Time zone, the Handle, Verified domains and Delete organization. |
| People | Members, roles and invitations. |
| Teams | Teams and the repositories each reaches. |
| Merge rules | What every pull request needs before it merges. |
| Rulesets | Branch rules set once for every repository a pattern names. See [Rulesets](#rulesets). |
| CI | The CI provider. See [CI](https://sailfork.com/docs/ci). |
| Drydock hosts | The machines that run sandboxes and CI. See [Sandboxes](https://sailfork.com/docs/sandboxes). |
| Security and audit log | Two-factor requirement, base access, new repository visibility, device copies and the audit log. Other controls on the page are not available yet: see [Security and audit log](#security-and-audit-log). |
| Moderation | People blocked from the organization's repositories. |
| Plan and seats | The plan, seats, storage and bills. See [Plans, billing and usage](https://sailfork.com/docs/billing). |

### General

- **Handle.** Renaming applies at once and the old handle keeps leading to the organization. Remotes that use the old handle need updating, and the page prints the `git remote set-url` command.
- **Verified domains.** Add a domain, then publish the TXT record Sailfork shows at `_sailfork.<domain>`. Choose Check again to verify it. A verified domain earns the organization a verified badge.
- **Delete organization.** Remove or transfer every repository first, or the request fails with `Acme still owns 2 repositories: delete or transfer them first`. The deletion happens 14 days after you confirm, and you can cancel until then. Members keep their own accounts.

### Merge rules

Merge rules apply to every pull request in the organization, and a repository can set its own. A repository's own rules replace the organization's. Four rules exist:

| Rule | Meaning |
| --- | --- |
| Approvals from people | 0 to 6 approvals, not counting the author's own. |
| Dismiss stale approvals | A push after an approval voids it. |
| Up to date with main | The branch contains the base branch's latest commit. |
| Threads resolved | Every comment thread on a line of code is resolved. |
| Author self-review | The author approves their own pull request before it merges. It never counts toward the approvals. |

### Rulesets

A ruleset applies the same branch rules to many repositories at once, such as keeping `main` behind pull requests everywhere. It holds the same rules a repository sets for itself, and applies on top of them. An organization can have up to 20 rulesets, and only owners change them. Open Settings, Rulesets, choose Add a ruleset, edit, then Save.

| Setting | Meaning |
| --- | --- |
| Name | 1 to 80 characters, unique in the organization. |
| Enforcement | Off, Dry run or Active. |
| Repositories | 1 to 20 repository names or patterns, such as `api-*`. `*` covers every repository, including ones made later. |
| Branch rules | The same rules as a repository's own. See [Branch protection rules](https://sailfork.com/docs/branches#branch-protection-rules). Rules that limit who can read a branch are set on a repository only. |
| Bypass teams | Teams whose members push past an active ruleset. Each bypass is logged. |
| Bypass people | Organization members who push past an active ruleset. Each bypass is logged. |
| Log every push | Records every push to a covered repository in the audit log, allowed or not. |

- **Off.** The ruleset is kept, applied nowhere and logged nowhere.
- **Dry run.** It refuses nothing. The audit log records each push it would have refused. Use it before turning a ruleset on.
- **Active.** It refuses what breaks a rule, except pushes from the bypass list, which go through and are logged.

The server checks active rulesets on every push over HTTPS and SSH, and on branch changes the server makes for you, such as web edits and merges. A team or person on a bypass list must already belong to the organization. A save with an unknown team or handle fails with `no such team` or `not members of this organization`.

The Coverage panel on the page shows, for each ruleset, how many of the organization's repositories its patterns reach, and how many repositories are under no active ruleset. It reads the patterns as written on the page, before you save. Changes are written to the audit log as `ruleset.update`. Over the API the route is `GET` and `PUT /api/orgs/{org}/rulesets`, and `PUT` replaces the whole list.

### Security and audit log

- **Require a passkey or authenticator.** Members without one are refused the organization's resources until they add one. The requirement applies to owners too, so turn on your own second step first. The error members see is `acme requires two-factor authentication: add a passkey or an authenticator app in Settings, Security to get back in`. They add one under Settings, Sign-in and sessions. See [Your account](https://sailfork.com/docs/account).
- **Base access for members.** No access, Read or Write, applied to every private repository for every member. Owners always have full access, and a team can give a person more than this, never less.
- **New repositories start as.** Private or Public. Whoever creates a repository can still choose.
- **Keep private repositories on members' devices.** On by default. Browsers keep folders and files a member opened so they open again without asking the server. Turn it off and the server refuses to send the objects a browser would keep from a private repository, with `device_copies_off`, and a browser deletes what it already kept. Public repositories are not affected.
- **Audit log.** Every change to members, rules and access, by people and agents. Kept for 730 days.

Four of these settings are stored and enforced: the two-factor requirement, base access, the starting visibility of new repositories and device copies. See [Security settings](https://sailfork.com/docs/api-orgs#security-settings) for the API.

> [!NOTE]
> The page also shows controls that are not available yet. The server does not store or enforce any of them, so turning one on changes nothing: Session length, Agent commits must be signed, Agent API keys expire after, single sign-on (SAML), provisioning (SCIM), the IP allowlist and its Apply to agent API calls option, audit log streaming to Datadog, Splunk or Amazon S3, and limiting invitations to verified domains. Saving them keeps nothing: the page forgets them on reload. Meanwhile, a browser session lasts 30 days, and a token expires on the date you give it when you create it (see [Tokens](https://sailfork.com/docs/tokens)). To move audit events to your own tools, use Export CSV or Export NDJSON on the audit log.

## Leave or delete

Leaving is covered in [Members](#members). An organization's last owner cannot leave. Deleting an organization is an owner action in Settings, General, and waits 14 days.

---

Every docs page: https://sailfork.com/llms.txt
