Roles & Review Workflow
cratly is designed so that editors propose changes and chief editors publish them. The editor has no backend of its own, so it does not manage users or roles itself — it derives them entirely from the connected GitLab repository. Setting up the roles is therefore a matter of configuring GitLab correctly.
The two roles
| Role | Can do | Cannot do |
|---|---|---|
| Editor | Create branches, save changes, open merge requests | Publish (merge into the published branch) — their changes need approval |
| Chief editor | Everything an editor can, plus publish their own and others' merge requests | — |
"Publishing" is simply merging a merge request into the published branch (usually main), which is what triggers your CI to rebuild and deploy the site. There is no separate approval step to configure: whoever is allowed to merge into the published branch is a chief editor.
GitLab setup
The roles map directly onto GitLab's member roles and a protected branch:
| cratly role | GitLab member role |
|---|---|
| Editor | Developer |
| Chief editor | Maintainer |
Then protect the published branch so that editors can propose but not publish:
Go to Settings → Repository → Protected branches
Protect your published branch (e.g.
main):Setting Value Allowed to push and merge No one Allowed to merge Maintainers Allowed to push No one Make sure the published branch is also the project's default branch (Settings → Repository → Branch defaults).
With this in place:
- Editors (Developers) can create branches and open merge requests, but the merge button is unavailable to them — their work waits for a chief editor.
- Chief editors (Maintainers) see open merge requests, review them, and merge — the merge is the act of publishing.
Which drafts you see
The editor's draft picker offers your own drafts: the ones you started, plus any that were handed to you by assigning the merge request to you in GitLab. Other editors' unfinished drafts stay out of your way.
Two exceptions:
- Chief editors always see every open draft — reviewing and publishing other editors' work is their job.
- A site can opt its whole team into seeing each other's work with
drafts.visibility: allin.cratly.config.yaml. The other editors' drafts are then listed for orientation, labelled with their author; only their own editor (or a chief editor) can discard them.
Publishing from the editor
Chief editors do not need to leave the editor to publish. When a merge request is active, the editor shows a Publish button in the branch/merge-request dialog. It appears only for chief editors and becomes available once the merge request's CI pipeline (if any) has finished successfully.
Publishing opens a review & publish dialog first: it groups the changed files into Pages and Media, and lets you expand each one to see exactly what changed (line-by-line), with a Preview button for the built site and a link to open the full details in GitLab. Only when you confirm does the editor merge the changes into the published branch and return you to the public version. Editors do not see the Publish button; their changes wait for a chief editor.
Non-content changes
Changes to files that are neither pages nor media — theme implementations, build configuration, lock files — are not shown as editorial diffs by default. Such changes usually mean the draft is not up to date with the published version rather than carrying content to review. Instead of listing them, the dialog shows a warning with the number of affected files.
You can tune this behaviour in .cratly.config.yaml under publish.other_files:
show: true— let reviewers expand and inspect those diffs anyway.block: true— prevent publishing entirely while non-content files differ.warning: "…"— replace the default hint with your own text, e.g. pointing editors to a technical contact. May be a single string or a map of locale → string (with*as fallback) to localize the hint.
When publishing isn't possible
If the draft conflicts with the current published version, GitLab reports the merge request as not mergeable. The editor detects this before publishing, shows a blocking notice, and asks you to update the draft from the published version first (see below). Updating tries a clean rebase and only falls back to the manual conflict resolution when it must.
For cases an editor can't resolve alone, configure a technical support contact in .cratly.config.yaml under support.contact (a string, or a locale → string map with * fallback). It is shown on update failures, in the conflict-resolution dialog, and on the publish-conflict notice.
A small badge in the header always shows your current role (Editor or Chief editor) for the connected repository, so it is clear at a glance whether you can publish yourself or need approval.
Why "merge" and not "approve"?
GitLab's enforced approval rules (a required, separate approve step; minimum approvers; "author may not approve their own request") are a Premium/Ultimate feature. On GitLab Community Edition / Free they are not available. Because cratly's publish point is always "the change lands in the published branch", the merge itself is the approval — so the workflow above needs no paid features. In CE the Approve button still exists as an optional, non-binding marker, and chief editors may use it to record who signed off.
How the editor detects your role
Because everything is derived on the fly, the editor works out your role from what GitLab exposes:
- Heuristic, on connect. From your member access level plus the published branch's merge rule — no elevated permissions required. Maintainer and above → chief editor; a Developer only counts as a chief editor if branch protection explicitly lets developers merge.
- Ground truth, when a merge request is open. The editor asks GitLab whether you may merge this merge request and adjusts the UI accordingly. This correctly accounts for protection rules that grant merge rights to specific users or groups.
- Fail-safe. If anything is unclear, the editor treats you as an editor (approval required) rather than offering a publish action that would fail at merge time.
Setup check in the editor
Users with the Maintainer role or above find an expandable Check repository setup section in the branch/merge-request dialog that verifies the workflow is configured correctly. Everyone else does not see it: the settings it inspects can only be changed by a Maintainer, so its findings would be of no use to anyone else, and the editor keeps their screens about content. The check covers:
- Branch protection: Is the published branch protected? Are editors correctly prevented from pushing and merging directly? This is the security-relevant half.
- Protection rules: The exact list of who may push and merge.
- Merge policy: Does a merge wait for its pipeline to succeed, and is a merge request built as it will land?
If the published branch is not protected, the check says so: in that case the whole review workflow can be bypassed, and every editor could publish unreviewed.
Each finding is explained — with the steps to resolve it — in Repository Check.
Permissions required
All of the above works with the same api OAuth scope described in Connecting a Repository. No additional scope is needed — role detection and the setup check read branch, protection, and merge-request permission information through that scope.