message: add INTRODUCTION and update http-server/README change_hash: ADFDw8cLgmC1JaW0Ii35PV+aKpZIpw4y7Je4uRJBLCFe credentials: - type: pgp_signature pub_key_id: 95C46FA6A41148AC body: iQIzBAABAgAdFiEEJ6tQKp6olvZKJ0lwlcRvpqQRSKwFAl5JowIACgkQlcRvpqQRSKzZnQ/+IPM7Ra6IYqsve5PYXwOeALzjpUWcdtcbnHNyrYSR+h09J/EEMw/hlg/HgrbTIOLcxuuBNi849sH3v8G/R0zc8Iisjhaq9PAZC20pHe8KNuaHPqmu5tP4zKKYShqDzj5fZSV9fzEiL5JVUSr0YAVEuxqg0UiKnv9MBOqdYR4GP+tIgNyWwMRmJ0ZnlVjj23e5h6onC1YHPWdsl7+3IqEefXGFcAR81wysyoH/uQDmfSQxncWEey1vUhuK05LpwdezKVOKrfogEJoUYMcpKOTw9vRvrPkGUgEwxXZs0ENg0aEs9F7m3+Yaao+I8jiBlEImIJWs9rO+bAzRebDJS28jT+ENm9RIRFmGWwkK58gP7jZdbwnZATyVLrW84RAQfgISXntE4SvJAcLzxCNReB6cKA1HZC+ozmHcJkovpMMY/RBC4Px9eAf49utNzk5otoM2/zQqU99b1JoSFt3K34ric80kGhpo1Gz47sVEyKKi5koyhYuZX2GZhc+yTVC2LxYuekV8/FlxAPE7zVF/hvXa3957nPiaBdi7mTX/JRpDA4UrCuPY2JMpLCfW7IQ77Vw4mJacAHs/OpxDKGqupi9dMlre2NpqqJntIRMUdi9eDkvzddw3odnYfij5HlkC7mKzvVbBKoM5w0SjfqH/5UiVopWFKII8JMepiil/NNHEJBE= account: mediocregophermain
parent
72f2a74415
commit
85d79ff71a
@ -0,0 +1,206 @@ |
|||||||
|
# dehub |
||||||
|
|
||||||
|
**Embed project coordination into your git history.** |
||||||
|
|
||||||
|
## Gettin Started |
||||||
|
|
||||||
|
``` |
||||||
|
git clone https://dehub.mediocregopher.com/dehub.git |
||||||
|
``` |
||||||
|
|
||||||
|
and check out the project! dehub is still very very alpha, but it will be |
||||||
|
"eating its own dogfood" from the start. |
||||||
|
|
||||||
|
Check out the `cmd/http-server` directory if you'd like to host your own. |
||||||
|
|
||||||
|
## Motivation |
||||||
|
|
||||||
|
Any active git project has a set of requirements which are not met by the git |
||||||
|
protocol directly, for example: |
||||||
|
|
||||||
|
* Authenticating committers |
||||||
|
* Some kind of ticket system for bugs and proposals |
||||||
|
* Change reviews |
||||||
|
* Signoff of changes by one or more maintainers |
||||||
|
* Release management (git tags are mutable and therefore generally ineffective) |
||||||
|
|
||||||
|
To solve these requirements developers generally turn to centralized services |
||||||
|
like GitHub or Bitbucket, or self-hosted server solutions like Gitlab or gogs. |
||||||
|
These platforms become a point of hindrance; their sheer size makes developers |
||||||
|
dependent on the platform developers to implement features and fix bugs, as well |
||||||
|
as making developers dependent on non-trivial amounts of devops (whether |
||||||
|
provided by the service, or self-hosted) in order to function. |
||||||
|
|
||||||
|
## Enter dehub |
||||||
|
|
||||||
|
By embedding project meta-information into git messages, as yaml encoded data |
||||||
|
structures, dehub is able to incept all the features generally provided by git |
||||||
|
platforms into the git history itself, including dehub's own configuration. |
||||||
|
|
||||||
|
### Example |
||||||
|
|
||||||
|
MyProject wants to ensure that at least 2 of the 3 maintainers sign off on a |
||||||
|
commit before the commit can be placed into the `trunk` branch (dehub's |
||||||
|
equivalent of the `master` branch). MyProject's repo would contain a |
||||||
|
`.dehub/config.yml` file with the following access controls set: |
||||||
|
|
||||||
|
``` |
||||||
|
# ... |
||||||
|
access_controls: |
||||||
|
|
||||||
|
# matches all files, but could be used for more fine-grained control |
||||||
|
- pattern: "**" |
||||||
|
condition: |
||||||
|
type: signature |
||||||
|
account_ids: |
||||||
|
- alice |
||||||
|
- bob |
||||||
|
- carol |
||||||
|
count: 2 |
||||||
|
``` |
||||||
|
|
||||||
|
A commit in the `trunk` branch would have a message with the following form: |
||||||
|
|
||||||
|
``` |
||||||
|
This is the first line of the commit message. It remains human readable |
||||||
|
|
||||||
|
type: change |
||||||
|
message: | |
||||||
|
This is the first line of the commit message. It remains human readable |
||||||
|
|
||||||
|
The rest of the message body is a yaml encoded object. The message field of |
||||||
|
that object repeats the first line of the commit message, followed by the |
||||||
|
rest of the commit message (if there is one). The first line is duplicated |
||||||
|
so that commands like `git log` are more usable, while at the same time |
||||||
|
allowing the full commit message to be signed off on. |
||||||
|
|
||||||
|
# A hash of the diff between the previous commit and this one. |
||||||
|
change_hash: ABCDEFGHIJKLMNOPQRSTUVWXYZ |
||||||
|
|
||||||
|
credentials: |
||||||
|
- type: pgp_signature |
||||||
|
pub_key_id: 01234 |
||||||
|
body: SIGNATUREBODY |
||||||
|
account: alice |
||||||
|
|
||||||
|
- type: pgp_signature |
||||||
|
pub_key_id: 56789 |
||||||
|
body: SIGNATUREBODY |
||||||
|
account: carol |
||||||
|
``` |
||||||
|
|
||||||
|
The `credentials` contains signatures of both the commit message and its |
||||||
|
changes, allowing it to be added to the `trunk`. A simple git hook is all that's |
||||||
|
needed to verify commits in `trunk` when they are pushed or pulled. |
||||||
|
|
||||||
|
## dehub Branches |
||||||
|
|
||||||
|
The `trunk` branch is the project's source-of-truth; all commits in it must have |
||||||
|
dehub encoded message bodies with acceptable credentials. Other branches are |
||||||
|
used to coordinate new changes, and then coalesce those changes into a commit |
||||||
|
suitable for `trunk`. |
||||||
|
|
||||||
|
### Example |
||||||
|
|
||||||
|
Alice creates and pushes a branch on the git repo called `featureBranch`, and |
||||||
|
pushes to it a commit with the following commit message: |
||||||
|
|
||||||
|
``` |
||||||
|
This commit adds some really cool features |
||||||
|
|
||||||
|
type: change |
||||||
|
message: This commit adds some really cool features |
||||||
|
credentials: |
||||||
|
- type: pgp_signature |
||||||
|
pub_key_id: 01234 |
||||||
|
body: SIGNATUREBODY |
||||||
|
account: alice |
||||||
|
|
||||||
|
# Note that this commit does not have enough credentials to be allowed in the |
||||||
|
# trunk branch. |
||||||
|
``` |
||||||
|
|
||||||
|
Bob sees the new branch and looks through it. He pushes the following commit |
||||||
|
(with no file changes): |
||||||
|
|
||||||
|
``` |
||||||
|
A small comment |
||||||
|
|
||||||
|
type: comment |
||||||
|
message: | |
||||||
|
A small comment |
||||||
|
|
||||||
|
I think you should change the code at file:line to be more like the code at |
||||||
|
otherFile:otherLine |
||||||
|
|
||||||
|
# Comment credentials sign the comment itself, so you can be sure of its |
||||||
|
# authenticity. |
||||||
|
credentials: |
||||||
|
- type: pgp_signature |
||||||
|
pub_key_id: 01234 |
||||||
|
body: SIGNATUREBODY |
||||||
|
account: bob |
||||||
|
``` |
||||||
|
|
||||||
|
Alice sees Bob's comment, and agrees with his suggestion. She pushes a new |
||||||
|
commit, which contains a slight modification of the original commit message plus |
||||||
|
the suggested changes: |
||||||
|
|
||||||
|
``` |
||||||
|
This commit adds some really cool features |
||||||
|
|
||||||
|
type: change |
||||||
|
message: | |
||||||
|
This commit adds some really cool features |
||||||
|
|
||||||
|
The pattern used at file:line was suggested by Bob. Thanks Bob! |
||||||
|
|
||||||
|
credentials: |
||||||
|
- type: pgp_signature |
||||||
|
pub_key_id: 01234 |
||||||
|
body: NEWSIGNATUREBODY |
||||||
|
account: alice |
||||||
|
|
||||||
|
# Note that this commit does not have enough credentials to be allowed in the |
||||||
|
# trunk branch. |
||||||
|
``` |
||||||
|
|
||||||
|
Bob, happy with these changes, pushes a commit to `featureBranch` which adds his |
||||||
|
own signature for the latest commit message and all file changes in the branch: |
||||||
|
|
||||||
|
``` |
||||||
|
bob's signature for this branch's changes |
||||||
|
|
||||||
|
type: pgp_signature |
||||||
|
pub_key_id: 01234 |
||||||
|
body: SIGNATUREBODY |
||||||
|
account: bob |
||||||
|
``` |
||||||
|
|
||||||
|
_Finally_ the feature branch is ready to be coalesced, which is a step anyone |
||||||
|
can do once all the required credentials are available. |
||||||
|
|
||||||
|
To coalesce, the following is done: All changes in the branch are squashed into |
||||||
|
a single commit, using the latest commit message which was pushed by Alice. |
||||||
|
Bob's signature is added to the commit structure as a credential. The commit can |
||||||
|
then be pushed to `trunk` (because it now has two credentials) and |
||||||
|
`featureBranch` can be deleted. |
||||||
|
|
||||||
|
## Pre-emptively Answered Questions |
||||||
|
|
||||||
|
**How can I trust that the git history I've received is legitimate?** |
||||||
|
|
||||||
|
Each commit in `trunk` can have its credentials verified locally. Credentials |
||||||
|
are currently provided by pgp signatures, so your trust in the git chain can be |
||||||
|
as strong as your trust in those signatures. Support for other kinds of |
||||||
|
credentials (e.g. keybase signatures) will increase the number of options for |
||||||
|
trust the user has. |
||||||
|
|
||||||
|
**Why `trunk`?** |
||||||
|
|
||||||
|
The primary branch in most git projects is called `master`. It makes sense to |
||||||
|
use a different one, `trunk`, for dehub, since the commits on it will be |
||||||
|
following a specific protocol which is not compatible with most `master` |
||||||
|
branches. By having a different primary branch convention we can prevent undue |
||||||
|
conflict, as well as make it easy to tell at a glance what kind of project is |
||||||
|
being worked with. |
@ -1,9 +1,35 @@ |
|||||||
# dehub-server |
# dehub-server |
||||||
|
|
||||||
This directory provides a simple Docker image which can be spun up to run a |
This directory provides a simple Docker image which can be spun up to run a |
||||||
dehub-enabled server (i.e. one in which incoming commits will be verified prior |
dehub-enabled git http server (i.e. one in which incoming commits will be |
||||||
to being accepted into their branch). |
verified prior to being accepted into the `trunk` branch). |
||||||
|
|
||||||
|
The docker image is also being hosted on docker hub at `mediocregopher/dehub`. |
||||||
|
Proper image tagging/versioning coming soon! |
||||||
|
|
||||||
|
## Usage |
||||||
|
|
||||||
|
Running the following: |
||||||
|
|
||||||
|
``` |
||||||
|
docker run \ |
||||||
|
--name dehub \ |
||||||
|
-v /opt/dehub/repos:/repos \ |
||||||
|
-v /opt/dehub/www:/var/www \ |
||||||
|
-p 8080:80 \ |
||||||
|
mediocregopher/dehub repo-a repo-b |
||||||
|
``` |
||||||
|
|
||||||
|
Will start an http server on port 8080, using `/opt/dehub/repos` to store all |
||||||
|
repo folders. It will then initialize repos at `/opt/dehub/repos/repo-a.git` and |
||||||
|
`/opt/dehub/repos/repo-b.git`, if they arent already there. |
||||||
|
|
||||||
|
If a volume for `/var/www` is given then that will be used as the root for all |
||||||
|
non-git http requests. |
||||||
|
|
||||||
|
## Contributors |
||||||
|
|
||||||
The Dockerfile being used is based on |
The Dockerfile being used is based on |
||||||
[gitbox](https://github.com/nmarus/docker-gitbox), so thank you to nmarus for |
[gitbox](https://github.com/nmarus/docker-gitbox), so thank you to nmarus for |
||||||
the great work there. |
the great work there. |
||||||
|
|
||||||
|
Loading…
Reference in new issue