From 20714aee0d2d2a989d93d6065e081aed8ac85fbf Mon Sep 17 00:00:00 2001
From: James Moger <james.moger@gitblit.com>
Date: Wed, 10 Oct 2012 00:05:34 -0400
Subject: [PATCH] Finer-grained repository access permissions (issue 36)
---
docs/01_setup.mkd | 68 ++++++++++++++++++++++++++++++---
1 files changed, 61 insertions(+), 7 deletions(-)
diff --git a/docs/01_setup.mkd b/docs/01_setup.mkd
index fa1bcd9..1cebb3b 100644
--- a/docs/01_setup.mkd
+++ b/docs/01_setup.mkd
@@ -244,6 +244,25 @@
#### Repository Owner
The *Repository Owner* has the special permission of being able to edit a repository through the web UI. The Repository Owner is not permitted to rename the repository, delete the repository, or reassign ownership to another user.
+### Access Restrictions and Access Permissions
+
+
+#### Discrete Permissions (Gitblit v1.2.0+)
+
+Since v1.2.0, Gitblit supports more discrete permissions. While Gitblit does not offer a built-in solution for branch-based permissions like Gitolite, it does allow for the following repository access permissions:
+
+- **V** (view in web ui, RSS feeds, download zip)
+- **R** (clone)
+- **RW** (clone and push)
+- **RWC** (clone and push with ref creation)
+- **RWD** (clone and push with ref creation, deletion)
+- **RW+** (clone and push with ref creation, deletion, rewind)
+
+#### No-So-Discrete Permissions (Gitblit <= v1.1.0)
+
+Prior to v1.2.0, Gitblit had two main access permission groupings:
+What you were permitted to do as an anonymous user and then **RW+** for any permitted user.
+
### Teams
Since v0.8.0, Gitblit supports *teams* for the original `users.properties` user service and the current default user service `users.conf`. Teams have assigned users and assigned repositories. A user can be a member of multiple teams and a repository may belong to multiple teams. This allows the administrator to quickly add a user to a team without having to keep track of all the appropriate repositories.
@@ -257,11 +276,12 @@
password = admin
role = "#admin"
role = "#notfederated"
- repository = repo1.git
- repository = repo2.git
+ repository = RW+:repo1.git
+ repository = RW+:repo2.git
[user "hannibal"]
password = bossman
+ repository = RWD:topsecret.git
[user "faceman"]
password = vanity
@@ -277,7 +297,7 @@
user = faceman
user = murdock
user = babaracus
- repository = topsecret.git
+ repository = RW:topsecret.git
mailingList = list@ateam.org
postReceiveScript = sendmail
@@ -291,15 +311,49 @@
username=password,role1,role2,role3...
@teamname=&mailinglist,!username1,!username2,!username3,repository1,repository2,repository3...
-#### Usernames
+### Usernames
Usernames must be unique and are case-insensitive.
Whitespace is illegal.
-#### Passwords
+### Passwords
User passwords are CASE-SENSITIVE and may be *plain*, *md5*, or *combined-md5* formatted (see `gitblit.properties` -> *realm.passwordStorage*).
-#### User Roles
-There are two actual *roles* in Gitblit: *#admin*, which grants administrative powers to that user, and *#notfederated*, which prevents an account from being pulled by another Gitblit instance. Administrators automatically have access to all repositories. All other *roles* are repository names. If a repository is access-restricted, the user must have the repository's name within his/her roles to bypass the access restriction. This is how users are granted access to a restricted repository.
+### User Roles
+There are four actual *roles* in Gitblit:
+
+- *#admin*, which grants administrative powers to that user
+- *#notfederated*, which prevents an account from being pulled by another Gitblit instance
+- *#create*, which allows the user the power to create personal repositories
+- *#fork*, which allows the user to create a personal fork of an existing Gitblit-hosted repository
+
+Administrators automatically have access to all repositories. All other *roles* are repository permissions. If a repository is access-restricted, the user must have the repository's name within his/her roles to bypass the access restriction. This is how users are granted access to a restricted repository.
+
+**NOTE:**
+The following roles are equivalent:
+
+- myrepo.git
+- RW+:myrepo.git
+
+This is to preserve backwards-compatibility with Gitblit <= 1.1.0 which granted rewind power to all access-permitted users.
+
+### Personal Repositories & Forks
+
+Personal Repositories and Forks are related but are controlled individually.
+
+#### Creating a Personal Repository
+A user may be granted the power to create personal repositories by specifying the *#create* role through the web ui or through the RPC mechanism via the Gitblit Manager. Personal repositories are exactly like common/shared repositories except that the owner has a few additional administrative powers for that repository, like rename and delete.
+
+#### Creating a Fork
+A user may also be granted the power to fork an existing repository hosted on your Gitblit server to their own personal clone by specifying the *#fork* role through the web ui or via the Gitblit Manager.
+
+Forks are mostly likely personal repositories or common/shared repositories except for two important differences:
+
+1. Forks inherit a view/clone access list from the origin repository.
+i.e. if Team A has clone access to the origin repository, then by default Team A also has clone access to the fork. This is to facilitate collaboration.
+2. Forks are always listed in the fork network, regardless of any access restriction set on the fork.
+In other words, if you fork *RepoA.git* to *~me/RepoA.git* and then set the access restriction of *~me/RepoA.git* to *Authenticated View, Clone, & Push* your fork will still be listed in the fork network for *RepoA.git*.
+
+If you really must have an invisible fork, the clone it locally, create a new personal repository for your invisible fork, and push it back to that personal repository.
## Alternative Authentication and Authorization
--
Gitblit v1.9.1