vole
Clone
Read only, no credentials:
https://rodent.software/vole.git
Write over SSH with a registered key:
git clone ssh://git@rodent.software:2222/vole.git
A free and open-source forge that lives in your Git repo.
Unify account terminology and clarify ACL commands
2e024cc96a391c0959ad2914caeed78b600fcfc1 · Keenan Nemetz · 14d ago · parent ab326d3a
Unify account terminology and clarify ACL commands Use account consistently in the CLI, help, docs, and remote admin messages. Rename the CLI account command from user to account while retaining the old user spelling as an alias. Replace positional ACL mutations with explicit verbs such as set-role, protect add, runners remove, and checks enable. Update local and remote admin parsing, hints, docs, and tests. Tidy repository filter alignment and remove duplicated issue/change counts from page subtitles.
docs/accounts-and-access.md +48−44
| @@ -28,19 +28,19 @@ only as hashes. Vole reloads the roster every few seconds, so key changes and re | |||
| 28 | 28 | take effect without restarting the server. | |
| 29 | 29 | ||
| 30 | 30 | ```sh | |
| 31 | vole admin user create alice --key ~/.ssh/id_ed25519.pub | ||
| 32 | vole admin user create bob --key bob.pub | ||
| 33 | vole admin user add-key alice --key ~/.ssh/id_ed25519_work.pub | ||
| 34 | vole admin user list | ||
| 35 | vole admin user rm-key alice SHA256:... | ||
| 36 | vole admin user retire alice | ||
| 37 | vole admin user backup backup/users.db | ||
| 31 | vole admin account create alice --key ~/.ssh/id_ed25519.pub | ||
| 32 | vole admin account create bob --key bob.pub | ||
| 33 | vole admin account add-key alice --key ~/.ssh/id_ed25519_work.pub | ||
| 34 | vole admin account list | ||
| 35 | vole admin account rm-key alice SHA256:... | ||
| 36 | vole admin account retire alice | ||
| 37 | vole admin account backup backup/users.db | ||
| 38 | 38 | ``` | |
| 39 | 39 | ||
| 40 | `user create --key` writes the account and its first SSH key together. Without | ||
| 40 | `account create --key` writes the account and its first SSH key together. Without | ||
| 41 | 41 | `--key` (and with no key on stdin), it creates a browser-only account and prints a | |
| 42 | one-time enrollment link. `user invite` issues a fresh link for an existing | ||
| 43 | account. `user add-key` adds another SSH key; use it to rotate credentials | ||
| 42 | one-time enrollment link. `account invite` issues a fresh link for an existing | ||
| 43 | account. `account add-key` adds another SSH key; use it to rotate credentials | ||
| 44 | 44 | without changing the account that access rules and approvals refer to. There is no | |
| 45 | 45 | command to change the account name. | |
| 46 | 46 | ||
| @@ -84,11 +84,11 @@ verification, so leave it off on a private instance unless you want that policy. | |||
| 84 | 84 | Admins can inspect and revoke sessions: | |
| 85 | 85 | ||
| 86 | 86 | ```sh | |
| 87 | vole admin user credentials alice | ||
| 88 | vole admin user rm-credential alice <credential-id> | ||
| 89 | vole admin user sessions alice | ||
| 90 | vole admin user revoke-sessions alice | ||
| 91 | vole admin user revoke-sessions --all | ||
| 87 | vole admin account credentials alice | ||
| 88 | vole admin account rm-credential alice <credential-id> | ||
| 89 | vole admin account sessions alice | ||
| 90 | vole admin account revoke-sessions alice | ||
| 91 | vole admin account revoke-sessions --all | ||
| 92 | 92 | ``` | |
| 93 | 93 | ||
| 94 | 94 | `revoke-sessions --all` is the recovery step after restoring an old `users.db`. | |
| @@ -105,10 +105,10 @@ By default, server management commands run on the host. To use them from another | |||
| 105 | 105 | machine, mark an account as an **instance admin** and pass `--remote`: | |
| 106 | 106 | ||
| 107 | 107 | ```sh | |
| 108 | vole admin user grant-admin alice | ||
| 109 | vole admin --remote ssh://git@forge.example.com:2222 user create bob --key bob.pub | ||
| 108 | vole admin account grant-admin alice | ||
| 109 | vole admin --remote ssh://git@forge.example.com:2222 account create bob --key bob.pub | ||
| 110 | 110 | vole admin --remote origin repo create demo --owner bob | |
| 111 | vole admin --remote origin acl default demo read | ||
| 111 | vole admin --remote origin acl set-default-role demo read | ||
| 112 | 112 | ``` | |
| 113 | 113 | ||
| 114 | 114 | An instance admin is the instance-wide `admin` role. They can create accounts and | |
| @@ -126,13 +126,13 @@ on the home page, and per-repository access rules live on that repository's | |||
| 126 | 126 | **Settings** tab, visible there to instance admins. | |
| 127 | 127 | ||
| 128 | 128 | The first instance admin must be granted on the host. Instance admin is the | |
| 129 | instance-wide `admin` role, so `vole admin user role alice admin` and | ||
| 130 | `vole admin user grant-admin alice` mean the same thing. Vole refuses to remove or | ||
| 129 | instance-wide `admin` role, so `vole admin account role alice admin` and | ||
| 130 | `vole admin account grant-admin alice` mean the same thing. Vole refuses to remove or | ||
| 131 | 131 | retire the last active instance admin, so a remote mistake cannot lock everyone | |
| 132 | 132 | out. Add `--json` to any remote command for a machine-readable response: | |
| 133 | 133 | ||
| 134 | 134 | ```sh | |
| 135 | vole admin --remote origin --json user list | ||
| 135 | vole admin --remote origin --json account list | ||
| 136 | 136 | ``` | |
| 137 | 137 | ||
| 138 | 138 | Backups, garbage collection, and index rebuilds stay on the host; they are | |
| @@ -169,7 +169,7 @@ grant does not open a private repository; an instance admin does. | |||
| 169 | 169 | To publish a repository, give the default role `read`: | |
| 170 | 170 | ||
| 171 | 171 | ```sh | |
| 172 | vole admin acl default demo read | ||
| 172 | vole admin acl set-default-role demo read | ||
| 173 | 173 | ``` | |
| 174 | 174 | ||
| 175 | 175 | A repository admin can also change the description, default branch, and | |
| @@ -186,38 +186,42 @@ or with `vole admin acl`. | |||
| 186 | 186 | ## Changing access | |
| 187 | 187 | ||
| 188 | 188 | ```sh | |
| 189 | vole admin user create carol --role contribute --key carol.pub | ||
| 190 | vole admin user role alice maintain | ||
| 191 | vole admin user role bob none | ||
| 189 | vole admin account create carol --role contribute --key carol.pub | ||
| 190 | vole admin account role alice maintain | ||
| 191 | vole admin account role bob none | ||
| 192 | 192 | ||
| 193 | 193 | vole admin acl show demo | |
| 194 | vole admin acl set demo alice maintain | ||
| 195 | vole admin acl set demo bob contribute | ||
| 196 | vole admin acl set demo carol read | ||
| 197 | vole admin acl default demo read | ||
| 198 | vole admin acl protect demo refs/heads/main | ||
| 199 | vole admin acl approvals demo 2 | ||
| 200 | vole admin acl checks demo on | ||
| 201 | vole admin acl runners demo ci-runner-1 | ||
| 194 | vole admin acl set-role demo alice maintain | ||
| 195 | vole admin acl set-role demo bob contribute | ||
| 196 | vole admin acl set-role demo carol read | ||
| 197 | vole admin acl set-default-role demo read | ||
| 198 | vole admin acl protect add demo refs/heads/main | ||
| 199 | vole admin acl set-approvals demo 2 | ||
| 200 | vole admin acl checks enable demo | ||
| 201 | vole admin acl runners add demo ci-runner-1 | ||
| 202 | 202 | ``` | |
| 203 | 203 | ||
| 204 | - `user create --role` and `user role` set the account's instance-wide role. | ||
| 204 | - `account create --role` and `account role` set the account's instance-wide role. | ||
| 205 | 205 | On a public repository that role applies without a per-repository entry; on a | |
| 206 | 206 | private repository it does not, unless the role is `admin`. | |
| 207 | - `set` gives one account a role in one repository. The roles are `none`, | ||
| 207 | - `set-role` gives one account a role in one repository. The roles are `none`, | ||
| 208 | 208 | `read`, `contribute`, `maintain` and `admin`. `contributor` and `contrib` are | |
| 209 | 209 | accepted as aliases for `contribute`; `write` is accepted as the historical | |
| 210 | 210 | spelling of `maintain`. A repository entry can raise the instance-wide role but | |
| 211 | cannot lower it. | ||
| 212 | - `default` changes the role for everyone else. `read` or higher makes the | ||
| 213 | repository public. | ||
| 214 | - `protect` replaces the list of protected branch patterns. Admins can still push | ||
| 215 | to them directly. | ||
| 216 | - `approvals` sets how many approvals a protected branch needs. `0` means | ||
| 211 | cannot lower it. Use `none` to remove the entry. | ||
| 212 | - `set-default-role` changes the role for everyone else. `read` or higher makes | ||
| 213 | the repository public. | ||
| 214 | - `protect` manages the protected branch patterns. `set` replaces the list, | ||
| 215 | `add` and `remove` change it one entry at a time, `clear` empties it, and | ||
| 216 | `list` shows it. Admins can still push to protected branches directly. | ||
| 217 | - `set-approvals` sets how many approvals a protected branch needs. `0` means | ||
| 217 | 218 | admin-only. | |
| 218 | - `checks` requires CI checks to pass before a protected branch can be updated. | ||
| 219 | - `runners` names the accounts whose CI results this repository trusts. Admins | ||
| 220 | always count. See [Runners](runner.md#who-can-run-jobs-and-report-results). | ||
| 219 | - `checks enable` requires CI checks to pass before a protected branch can be | ||
| 220 | updated; `checks disable` allows approvals alone to land it. | ||
| 221 | - `runners` manages the accounts whose CI results this repository trusts. It uses | ||
| 222 | the same `list`, `add`, `remove`, `set`, and `clear` verbs as `protect`. | ||
| 223 | Admins always count. See | ||
| 224 | [Runners](runner.md#who-can-run-jobs-and-report-results). | ||
| 221 | 225 | ||
| 222 | 226 | ## Contributors and their branches | |
| 223 | 227 | ||