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
mediocregopher
4 years ago
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 |
||||
|
||||
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 |
||||
to being accepted into their branch). |
||||
dehub-enabled git http server (i.e. one in which incoming commits will be |
||||
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 |
||||
[gitbox](https://github.com/nmarus/docker-gitbox), so thank you to nmarus for |
||||
the great work there. |
||||
|
||||
|
||||
Loading…
Reference in new issue