co ruleset — rulesets
Manage branch, tag and push policies. list / view / create / edit / enforce / delete / rule / target / bypass
co ruleset manages workspace rulesets. A ruleset picks branches or tags with ref patterns (--include / --exclude) and groups rules (what is enforced), targets (which repositories it applies to) and bypass actors (who may skip it). It is the same data as Workspace settings > Rulesets in the web.
Only workspace owners can create, change or delete rulesets, including their rules, targets and bypass actors. Members can list and view them. Without the role you get "Ruleset changes need a workspace owner role."
Quick start
co ruleset create -n "protect main" --include main
co ruleset enforce <id> evaluate # log only, no blocking (dry run)
co ruleset rule add <id> --kind require_approvals_min_count --scope merge --value 1
co ruleset target add <id> --repo my-repo
co ruleset view <id>
co ruleset enforce <id> active # enforce once it looks rightNew rulesets start active. Blocking begins as soon as a target is added, so switch to evaluate first, check the results, then go active. A workspace ruleset with no target applies to no repository.
co ruleset list
Lists the workspace's rulesets. With --repo, only the rulesets that apply to that repository.
co ruleset list
co ruleset list --repo my-repoco ruleset view <id>
Shows one ruleset's ref patterns, enforcement, rules, targets and bypass actors. This is also where you find the ids needed to remove a rule, target or bypass.
co ruleset view 12co ruleset create
Creates a workspace ruleset. It starts with no rules.
co ruleset create -n "protect main" --target branch --include main --repo my-repo
co ruleset create -n "release tags" --target tag --include 'v*'
co ruleset create -n "push policy" --target push| Option | Description |
|---|---|
| -n, --name <name> | Ruleset name (required) |
| -d, --description <text> | Description |
| --target <branch / tag / push> | What the ruleset matches (default branch) |
| --include <patterns> | Ref patterns to include. Repeat or comma-separate (e.g. main,release/*) |
| --exclude <patterns> | Ref patterns to exclude |
| --repo <name / key> | Also add one repository as a target (same as co ruleset target add <id> --repo) |
co ruleset edit <id>
Changes the name, description or ref patterns. --include / --exclude replace the current list; an empty string clears it.
co ruleset edit 12 -n "protect main and develop" --include main,develop
co ruleset edit 12 --exclude "" # clear exclusionsco ruleset enforce <id> <state>
Switches enforcement.
co ruleset enforce 12 evaluate
co ruleset enforce 12 active| State | Behavior |
|---|---|
| active | Blocks pushes and merges that break a rule |
| evaluate | Logs what would be blocked without blocking (dry run) |
| disabled | Not evaluated |
co ruleset rule add / remove
Adds or removes rules. --kind and --scope are required, and each kind works in one scope only (table below). An invalid --kind prints every valid value.
co ruleset rule add 12 --kind block_force_push --scope push
co ruleset rule add 12 --kind require_approvals_min_count --scope merge --value 2
co ruleset rule add 12 --kind commit_message_pattern --scope push --pattern '^(feat|fix): '
co ruleset rule remove 12 418 --yes| Option | Description |
|---|---|
| --kind <kind> | Rule kind (required) |
| --scope <push / merge> | Stage the rule applies to (required) |
| --value <n> | Numeric parameter (approval count, max file size in MB, ...) |
| --pattern <text> | Pattern parameter (regex for *_pattern kinds and restrict_file_paths, repo:<role> or workspace:<role> for role rules) |
| --effect <deny / allow> | Effect (server default when omitted) |
| --disabled | Add the rule switched off |
Rule kinds
| kind | scope | Description | Parameters |
|---|---|---|---|
| require_change_request | push | Require a change request before merging (blocks direct push) | - |
| require_approvals_min_count | merge | At least N approvals | --value N |
| require_approval_from_repo_role | merge | Approval from a repository role or higher | --pattern repo:<role>, --value N |
| require_approval_from_workspace_role | merge | Approval from a workspace role or higher | --pattern workspace:<role>, --value N |
| require_approval_from_actor | merge | Approval from specific users / teams / roles (pick approvers in the web) | --value N |
| require_recent_push_approval | merge | Approval of the most recent push | - |
| require_no_pending_rejections | merge | All review rejections resolved before merge | - |
| require_ci_pipeline_success | merge | CI pipeline must succeed before merge | - |
| require_linked_issue_for_merge | merge | At least one linked issue | - |
| require_branch_up_to_date | merge | Branch must be up to date with the target | - |
| require_merge_train | merge | Merges must go through the merge train | - |
| restrict_merge_to_role | merge | Only a role or higher may merge | --pattern repo:<role> / workspace:<role> |
| allow_merge_commit | merge | Allow merge commits | - |
| allow_squash_merge | merge | Allow squash merge | - |
| allow_rebase_merge | merge | Allow rebase merge | - |
| block_force_push | push | Block force pushes | - |
| block_main_branch_push | push | Block pushes to the main branch | - |
| require_linear_history | push | Linear history (no merge commits) | - |
| require_signed_commits | push | Signed / verified commits only | - |
| require_committer_verified | push | Committer must be a verified user | - |
| restrict_push_to_role | push | Only a role or higher may push | --pattern repo:<role> / workspace:<role> |
| restrict_creations | push | Restrict ref creation | - |
| restrict_updates | push | Restrict ref updates | - |
| restrict_deletions | push | Restrict ref (branch / tag) deletion | - |
| branch_name_pattern | push | Branch name must match a pattern | --pattern <regex> |
| tag_name_pattern | push | Tag name must match a pattern | --pattern <regex> |
| commit_message_pattern | push | Commit message must match a pattern | --pattern <regex> |
| reject_commit_message_pattern | push | Reject commit messages matching a pattern | --pattern <regex> |
| commit_author_email_pattern | push | Author email must match a pattern | --pattern <regex> |
| committer_email_pattern | push | Committer email must match a pattern | --pattern <regex> |
| max_file_size | push | Block files larger than N MB | --value N |
| restrict_file_paths | push | Reject pushes touching matching paths | --pattern <regex> |
co ruleset target add / remove
Chooses which repositories a workspace ruleset applies to. The repository must be in the current workspace; pass its name or the key from co repo list.
co ruleset target add 12 --repo my-repo
co ruleset target add 12 --include 'collabops-*' --exclude collabops-sandbox
co ruleset target add 12 --all
co ruleset target remove 12 141 --yes| Option | Description |
|---|---|
| --repo <name / key> | One repository |
| --include <patterns> | Repository name patterns |
| --exclude <patterns> | Repository name patterns to exclude (with --all or --include) |
| --all | Every repository in the workspace |
co ruleset bypass add / remove
Sets who may bypass the ruleset.
co ruleset bypass add 12 --actor-type workspace_role --actor admin
co ruleset bypass add 12 --actor-type user --actor <user-uuid> --mode change_request
co ruleset bypass remove 12 55 --yes| Option | Description |
|---|---|
| --actor-type <type> | user / team / workspace_role / repo_role / app (required) |
| --actor <ref> | User UUID, team id, or role name (required) |
| --mode <always / change_request> | always bypasses every time, change_request only through a change request (server default when omitted) |
co ruleset delete <id>
Permanently deletes a ruleset. This cannot be undone.
co ruleset delete 12
co ruleset delete 12 --yes # no promptremove and delete ask for confirmation. Outside a terminal (scripts, agents) pass --yes.