docs: add USER_GUIDE and ADMIN_GUIDE; fix SELF_CERTIFY two-layer gate#132
Merged
coopernetes merged 1 commit intomainfrom Apr 12, 2026
Merged
docs: add USER_GUIDE and ADMIN_GUIDE; fix SELF_CERTIFY two-layer gate#132coopernetes merged 1 commit intomainfrom
coopernetes merged 1 commit intomainfrom
Conversation
coopernetes
force-pushed
the
docs/user-and-admin-guides
branch
from
70e6b46 to
04c444e
Compare
coopernetes
commented
Apr 11, 2026
| ## User accounts | ||
|
|
||
| git-proxy-java supports four authentication backends. **LDAP, AD, and OIDC are the expected production choices.** | ||
| Local auth (static users in YAML) is useful for development, demos, and smoke-testing — not for multi-user |
Owner
Author
There was a problem hiding this comment.
Local auth does insert into the database. Can be used outside of static config (add/remove users, reset passwords, etc).
| | `ADMIN` | Everything USER can do, plus: create/delete users, reset passwords, manage any user's profile, view all push records | | ||
| | `SELF_CERTIFY` | Grants the **capability** to self-approve pushes. This is the prerequisite gate — it must be present before any per-repo `SELF_CERTIFY` permission takes effect. | | ||
|
|
||
| `ROLE_USER` is granted to every authenticated user automatically. A user with no `roles:` entry has `USER` |
Owner
Author
There was a problem hiding this comment.
Need this fixed. It should still be by group/role authority mapping. Most orgs will not want to grant all users ability to interact with the system. There may be an issue for this already.
| your org's IdP or IAM process. Self-approval requires **both** this role and a per-repo `SELF_CERTIFY` | ||
| permission entry — neither alone is sufficient. This separation lets organisations externalise the capability | ||
| grant (who is trusted to self-certify at all) to their existing directory/IAM procedures, while the per-repo | ||
| entitlement remains managed inside git-proxy-java. |
Owner
Author
There was a problem hiding this comment.
We need to make self certify a configuration toggle. Some orgs may want to disable this feature out right and enforce 4-eyes.
| ### Attestation questions | ||
|
|
||
| The administrator may configure attestation questions that you must answer before a push is approved. These appear | ||
| in the dashboard push record view, not in the terminal. A reviewer (or yourself, if you have `REVIEW` permission |
Owner
Author
There was a problem hiding this comment.
There is a specific permission for self_review.
| **User permissions** (`permissions`) control which proxy users can perform which operations on specific repositories. | ||
| Even if a repository is in the allow list, you need an explicit `PUSH` permission entry to push to it. | ||
|
|
||
| In practice: if you get "repository not permitted", it could be either layer. Your administrator can check |
Owner
Author
There was a problem hiding this comment.
Nope. The feedback to the git client is clear when it is user permission missing vs repository url not permitted.
coopernetes
force-pushed
the
docs/user-and-admin-guides
branch
from
04c444e to
e164896
Compare
…ovements Docs: - Add USER_GUIDE.md and ADMIN_GUIDE.md covering push flows, approval, self-certify, proxy output, env vars, auth providers, and deployment; closes #86 - Document Log4j2 configuration, NO_COLOR and GITPROXY_NO_EMOJI env vars - Replace Logback with Log4j2 for Apache-2.0 license compliance Features: - require-review-permission config knob — restrict who can approve/reject pushes to a configurable role; closes #131 - /api/me returns user permissions; profile page displays roles - Nav labels renamed and reordered; Users page restricted to admins Fixes: - YAML access rule operations field was ignored when building UrlRuleFilter instances — PUSH-only deny rules incorrectly blocked FETCH requests in both the doHttpFilter deny/allow loops and applyInfoRefsRules - Access rule dialog slug placeholders now include the required leading /; hint added explaining the slug format requirement Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
coopernetes
force-pushed
the
docs/user-and-admin-guides
branch
from
2b8bab9 to
9665544
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
USER_GUIDE.mdandADMIN_GUIDE.mdcovering push flows, approval/review, self-certify, proxy output formats, environment variables, authentication providers, and deployment; closes docs: identify and fill gaps in user-facing, administrator, and deployment documentation #86NO_COLOR/GITPROXY_NO_EMOJIenv vars documentedrequire-review-permissionconfig knob — restrict who can approve/reject pushes; closes feat: make REVIEW permission opt-in; default to any authenticated user can review #131/api/mereturns user permissions; profile page displays rolesoperationsfield was ignored when buildingUrlRuleFilterinstances — PUSH-only deny rules incorrectly blocked FETCH requests. Fixed in both thedoHttpFilterdeny/allow loops andapplyInfoRefsRules/; hint added explaining the slug formatTest plan
UrlRuleFilterTest.infoRefs_uploadPack_pushOnlyDenyRule_doesNotBlock/myorg/myrepoplaceholder and slug hint for all three pattern types