From 5d7545652a6529c9076f67acd75f7a977c8a44a6 Mon Sep 17 00:00:00 2001
From: James Moger <james.moger@gitblit.com>
Date: Wed, 10 Oct 2012 16:47:11 -0400
Subject: [PATCH] Try regex permission matching if exact permission is not found (issue 36)
---
docs/01_setup.mkd | 91 +++++++++++++++++++++++++++++++++++++++++----
1 files changed, 83 insertions(+), 8 deletions(-)
diff --git a/docs/01_setup.mkd b/docs/01_setup.mkd
index 6d6f727..3123aa1 100644
--- a/docs/01_setup.mkd
+++ b/docs/01_setup.mkd
@@ -9,6 +9,7 @@
- <context-parameter> *git.repositoryFolder* (set the full path to your repositories folder)
- <context-parameter> *groovy.scriptsFolder* (set the full path to your Groovy hook scripts folder)
- <context-parameter> *groovy.grapeFolder* (set the full path to your Groovy Grape artifact cache)
+ - <context-parameter> *web.projectsFile* (set the full path to your projects metadata file)
- <context-parameter> *realm.userService* (set the full path to `users.conf`)
- <context-parameter> *git.packedGitLimit* (set larger than the size of your largest repository)
- <context-parameter> *git.streamFileThreshold* (set larger than the size of your largest committed file)
@@ -156,6 +157,15 @@
# If your httpd frontend is https but you are proxying http Gitblit WAR or GO
#Header edit Location ^http://([^⁄]+)/gitblit/ https://$1/gitblit/
+# Additionally you will want to tell Gitblit the original scheme and port
+#RequestHeader set X-Forwarded-Proto https
+#RequestHeader set X-Forwarded-Port 443
+
+# If you are using subdomain proxying then you will want to tell Gitblit the appropriate
+# context path for your repository url.
+# If you are not using subdomain proxying, then ignore this setting.
+#RequestHeader set X-Forwarded-Context /
+
#ProxyPass /gitblit ajp://localhost:8009/gitblit
%ENDCODE%
**Please** make sure to:
@@ -224,7 +234,7 @@
federationSets =
#### Repository Names
-Repository names must be unique and are CASE-SENSITIVE ON CASE-SENSITIVE FILESYSTEMS. The name must be composed of letters, digits, or `/ _ - .`<br/>
+Repository names must be unique and are CASE-SENSITIVE ON CASE-SENSITIVE FILESYSTEMS. The name must be composed of letters, digits, or `/ _ - . ~`<br/>
Whitespace is illegal.
Repositories can be grouped within subfolders. e.g. *libraries/mycoollib.git* and *libraries/myotherlib.git*
@@ -233,6 +243,35 @@
#### 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)
+
+These permission codes are combined with the repository path to create a user permission:
+
+ RW:mygroup/myrepo.git
+
+#### Discrete Permissions with Regex Matching (Gitblit v1.2.0+)
+
+Gitblit also supports regex matching for repository permissions. The following permission grants push privileges to all repositories in the *mygroup* folder.
+
+ RW:mygroup/[A-Za-z0-9-~_\\./]+
+
+#### 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
@@ -247,11 +286,13 @@
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
+ repository = RW+:ateam/[A-Za-z0-9-~_\\./]+
[user "faceman"]
password = vanity
@@ -267,7 +308,7 @@
user = faceman
user = murdock
user = babaracus
- repository = topsecret.git
+ repository = RW:topsecret.git
mailingList = list@ateam.org
postReceiveScript = sendmail
@@ -281,15 +322,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