Note, that you need to first understand policy mechanism as most permissions are reflected in policy rules.

grammar: need a "the" before "policy mechanism"

but, moreso, I'm not sure that just referencing the policy doc is enough clarification where. Some of our access controls are simple permission checks and others are policy checks (that may themselves check a permission)

updated + added acces control page

The access control doc is a big broader than I expected, but I guess it makes sense to mention auth and cover allows_scms. However, the "Perimeter" section seems like it maybe belongs elsewhere. It's good stuff to document, but I feel like it's distracting from the main point.

I think policies and permissions should be the highlight here.

Only builders from createrepo channel (and runroot if you're using that plugin)
should have mounted koji volumes in read-write mode.

This is not true. The createrepo builders only require read-only mounts. The runroot plugin is the only place where read-write mounts are used on builders.

There is whole document :doc:defining_hub_policies covering this.

grammar: need an article before "whole document". I.e. "There is a whole document"

However, I'd just say something simpler like: "See the :doc:defining_hub_policies document for details."

Hub policies are core system of access controls. It can define specialized

grammar: agreement. "Hub policies" is plural. "It" is singular. Or perhaps "it" refers to something else, if so it is unclear what. Perhaps, "Policies govern many actions ranging from..."

Also, it's probably worth clarifying that some only some policies are allow/deny policies (like package_list and build_from_srpm). Others, like channel and volume, govern different parts of Koji behavior.

Specific chapter are user permissions. Every user can have set of permissions
which allow him to do some actions directly (typically admin permission) or
these permissions can be referenced in hub policies.

I'm not sure what the first sentence is saying. I guess we dont want to repeat too much of the permissions doc, but we should say something. Maybe something like:

The permissions system allows admins to grant named permissions to individual users. These permissions govern access to various features of Koji. Permission checks can also be used in policies.

updated

I've put some updates here

https://github.com/mikem23/koji-playground/commits/pagure/pr/2415

Commit 44db1bc8 fixes this pull-request