diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/00_index.mkd | 1 | ||||
| -rw-r--r-- | docs/01_features.mkd | 5 | ||||
| -rw-r--r-- | docs/01_setup.mkd | 33 | ||||
| -rw-r--r-- | docs/04_design.mkd | 1 | ||||
| -rw-r--r-- | docs/04_releases.mkd | 8 | ||||
| -rw-r--r-- | docs/05_roadmap.mkd | 5 |
6 files changed, 42 insertions, 11 deletions
diff --git a/docs/00_index.mkd b/docs/00_index.mkd index 11d571d8..d1c08fe6 100644 --- a/docs/00_index.mkd +++ b/docs/00_index.mkd @@ -66,6 +66,7 @@ Administrators can create and manage all repositories, user accounts, and teams ### Integration with Your Infrastructure
+- Groovy push hook scripts
- Pluggable user service mechanism for custom authentication, authorization, and user management
- Rich RSS feeds
- JSON-based RPC mechanism
diff --git a/docs/01_features.mkd b/docs/01_features.mkd index 4172f4e1..39fbfaac 100644 --- a/docs/01_features.mkd +++ b/docs/01_features.mkd @@ -11,6 +11,7 @@ - RSS/JSON RPC interface
- Java/Swing Gitblit Manager tool
- Gitweb inspired web UI
+- Groovy pre- and post- push hook scripts, per-repository or globally for all repositories
- Administrators may create, edit, rename, or delete repositories through the web UI or RPC interface
- Administrators may create, edit, rename, or delete users through the web UI or RPC interface
- Administrators may create, edit, rename, or delete teams through the web UI or RPC interface
@@ -40,10 +41,10 @@ ## Limitations
- HTTP/HTTPS are the only supported Git protocols
-- Access controls are not path-based, they are repository-based
+- Built-in access controls are not path-based, they are repository-based.
- Only Administrators can create, rename or delete repositories
- Only Administrators can create, modify or delete users
-- Commit hooks are not supported
+- Only Administrators can create, modify or delete teams
- Native Git may be needed to periodically run git-gc as [JGit][jgit] does not fully support the git-gc featureset.
### Caveats
diff --git a/docs/01_setup.mkd b/docs/01_setup.mkd index 3256d1b3..27a4e6af 100644 --- a/docs/01_setup.mkd +++ b/docs/01_setup.mkd @@ -3,9 +3,11 @@ 1. Download [Gitblit WAR %VERSION%](http://code.google.com/p/gitblit/downloads/detail?name=%WAR%) to the webapps folder of your servlet container.
2. You may have to manually extract the WAR (zip file) to a folder within your webapps folder.
3. Copy the `WEB-INF/users.conf` file to a location outside the webapps folder that is accessible by your servlet container.
+Optionally copy the example hook scripts in `WEB-INF/groovy` to a location outside the webapps folder that is accesible by your servlet container.
4. The Gitblit webapp is configured through its `web.xml` file.
Open `web.xml` in your favorite text editor and make sure to review and set:
- <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> *realm.userService* (set the full path to `users.conf`)
5. You may have to restart your servlet container.
6. Open your browser to <http://localhost/gitblit> or whatever the url should be.
@@ -19,6 +21,7 @@ Open `web.xml` in your favorite text editor and make sure to review and set: 2. The server itself is configured through a simple text file.
Open `gitblit.properties` in your favorite text editor and make sure to review and set:
- *git.repositoryFolder* (path may be relative or absolute)
+ - *groovy.scriptsFolder* (path may be relative or absolute)
- *server.tempFolder* (path may be relative or absolute)
- *server.httpPort* and *server.httpsPort*
- *server.httpBindInterface* and *server.httpsBindInterface*
@@ -115,12 +118,13 @@ Backup your `web.properties` file (if you have one, these are the setting overri 2. Backup your `users.properties` file *(if it is located in the Gitblit GO folder)*
OR
Backup your `users.conf` file *(if it is located in the Gitblit GO folder)*
-3. Unzip Gitblit GO to a new folder
-4. Overwrite the `gitblit.properties` file with your backup
-5. Overwrite the `users.properties` file with your backup *(if it was located in the Gitblit GO folder)*
+3. Backup your Groovy hook scripts
+4. Unzip Gitblit GO to a new folder
+5. Overwrite the `gitblit.properties` file with your backup
+6. Overwrite the `users.properties` file with your backup *(if it was located in the Gitblit GO folder)*
OR
Overwrite the `users.conf` file with your backup *(if it was located in the Gitblit GO folder)*
-6. Review and optionally apply any new settings as indicated in the [release log](releases.html).
+7. Review and optionally apply any new settings as indicated in the [release log](releases.html).
#### Upgrading Windows Service
You may need to delete your old service definition and install a new one depending on what has changed in the release.
@@ -197,10 +201,10 @@ The `users.conf` file allows flexibility for adding new fields to a UserModel ob ### Administering Users (users.properties, Gitblit v0.5.0 - v0.7.0)
All users are stored in the `users.properties` file or in the file you specified in `gitblit.properties`. Your file extension must be *.properties* in order to use this user service.
-The format of `users.properties` follows Jetty's convention for HashRealms:
+The format of `users.properties` loosely follows Jetty's convention for HashRealms:
- username,password,role1,role2,role3...
- @teamname,!username1,!username2,!username3,repository1,repository2,repository3...
+ username=password,role1,role2,role3...
+ @teamname=!username1,!username2,!username3,repository1,repository2,repository3...
#### Usernames
Usernames must be unique and are case-insensitive.
@@ -220,6 +224,21 @@ You may use your own custom *com.gitblit.IUserService* implementation by specify Your user service class must be on Gitblit's classpath and must have a public default constructor.
Please see the following interface definition [com.gitblit.IUserService](https://github.com/gitblit/gitblit/blob/master/src/com/gitblit/IUserService.java).
+## Groovy Hook Scripts
+
+*SINCE 0.8.0*
+
+The preferred hook mechanism is Groovy. This mechanism only executes when pushing to Gitblit, not when pushing to some other Git tooling in your stack.
+
+The Groovy hook mechanism allows for dynamic extension of Gitblit to execute custom tasks on receiving and processing push events. The scripts run within the context of your Gitblit instance and therefore have access to Gitblit's internals at runtime.
+
+Your Groovy scripts should be stored in the *groovy.scriptsFolder* as specified in `gitblit.properties` or `web.xml`.
+
+Scripts must be explicitly specified to be executed. A script can be run on *all repositories* by adding the script file name to *groovy.preReceiveScripts* or *groovy.postReceiveScripts* in `gitblit.properties` or `web.xml`. Alternatively, you may specify per-repository scripts in the repository settings. Global/shared scripts are executed first in their listed order, followed by per-repository scripts in their listed order.
+
+Some primitive sample scripts are included in the GO and WAR distributions to show you how you can tap into Gitblit with the provided bound variables.
+Hook contributions and improvements are welcome.
+
## Client Setup and Configuration
### Https with Self-Signed Certificates
You must tell Git/JGit not to verify the self-signed certificate in order to perform any remote Git operations.
diff --git a/docs/04_design.mkd b/docs/04_design.mkd index 3fd13d47..e16a9b11 100644 --- a/docs/04_design.mkd +++ b/docs/04_design.mkd @@ -35,6 +35,7 @@ The following dependencies are automatically downloaded by Gitblit GO (or alread - [jdom](http://www.jdom.org) (Apache-style JDOM license)
- [google-gson](http://code.google.com/google-gson) (Apache 2.0)
- [javamail](http://kenai.com/projects/javamail) (CDDL-1.0, BSD, GPL-2.0, GNU-Classpath)
+- [Groovy](http://groovy.codehaus.org) (Apache 2.0)
### Other Build Dependencies
- [Fancybox image viewer](http://fancybox.net) (MIT and GPL dual-licensed)
diff --git a/docs/04_releases.mkd b/docs/04_releases.mkd index 9a4e4a83..75ce1459 100644 --- a/docs/04_releases.mkd +++ b/docs/04_releases.mkd @@ -3,6 +3,13 @@ ### Current Release
**%VERSION%** ([go](http://code.google.com/p/gitblit/downloads/detail?name=%GO%) | [war](http://code.google.com/p/gitblit/downloads/detail?name=%WAR%) | [express](http://code.google.com/p/gitblit/downloads/detail?name=%EXPRESS%) | [fedclient](http://code.google.com/p/gitblit/downloads/detail?name=%FEDCLIENT%) | [manager](http://code.google.com/p/gitblit/downloads/detail?name=%MANAGER%) | [api](http://code.google.com/p/gitblit/downloads/detail?name=%API%)) based on [%JGIT%][jgit] *released %BUILDDATE%*
+- added: Groovy 1.8.4 and sample pre- and post- push Groovy hook scripts. Hook scripts can be set per-repository or globally for all repositories.
+Unfortunately this adds another 6 MB to the 8MB Gitblit package, but it allows for a *very* powerful, flexible, platform-independent hook script mechanism.
+ **New:** *groovy.scriptsFolder = groovy*
+ **New:** *groovy.preReceiveScripts =*
+ **New:** *groovy.postReceiveScripts =*
+- added: New key for mailing lists. This is _currently_ used in conjunction with the example *sendemail.groovy* post-receive hook script.
+ **New:** *mail.mailingLists =*
- added: new default user service implementation: com.gitblit.ConfigUserService (users.conf)
This user service implementation allows for serialization and deserialization of more sophisticated Gitblit User objects and will open the door for more advanced Gitblit features. For upgrading installations, a `users.conf` file will automatically be created for you from your existing `users.properties` file on your first launch of Gitblit. You will have to manually set *realm.userService=users.conf* to switch to the new user service. The original `users.properties` file and it's corresponding implementation are deprecated.
**New:** *realm.userService = users.conf*
@@ -21,7 +28,6 @@ This user service implementation allows for serialization and deserialization of - improved: empty repositories now link to the *empty repository* page which gives some direction to the user for the next step in using Gitblit. This page displays the primary push/clone url of the repository and gives sample syntax for the git command-line client. (issue 31)
- improved: unit testing framework has been migrated to JUnit4 syntax and the test suite has been redesigned to run all unit tests, including rpc, federation, and git push/clone tests
-
### Older Releases
**0.7.0** ([go](http://code.google.com/p/gitblit/downloads/detail?name=gitblit-0.7.0.zip) | [war](http://code.google.com/p/gitblit/downloads/detail?name=gitblit-0.7.0.war) | [fedclient](http://code.google.com/p/gitblit/downloads/detail?name=fedclient-0.7.0.zip) | [manager](http://code.google.com/p/gitblit/downloads/detail?name=manager-0.7.0.zip) | [api](http://code.google.com/p/gitblit/downloads/detail?name=gbapi-0.7.0.zip)) based on [JGit 1.1.0 (201109151100-r)][jgit] *released 2011-11-11*
diff --git a/docs/05_roadmap.mkd b/docs/05_roadmap.mkd index e9d2dcbe..9be6372e 100644 --- a/docs/05_roadmap.mkd +++ b/docs/05_roadmap.mkd @@ -37,7 +37,10 @@ This list is volatile. ### IDEAS
-* Gitblit: consider user-subscribed email notifications for a repository branch
+* Gitblit: implement branch permission controls as Groovy pre-receive script.
+*Maintain permissions text file similar to a gitolite configuration file or svn authz file.*
+* Gitblit: consider user-subscribed email notifications for a repository branch as a built-in feature.
+*There is a sample Groovy post-receive hook script which can send emails.*
* Gitblit: aggregate RSS feeds by tag or subfolder
* Gitblit: Consider creating more Git model objects and exposing them via the JSON RPC interface to allow inspection/retrieval of Git commits, Git trees, etc from Gitblit.
* Gitblit: Stronger ticgit integration (issue 8)
|