Tutorial 1: Create Your Own Project
This tutorial will guide you through starting a dehub project of your own, as well as introducing some basic concepts regarding how commit payloads work. You will use an example hello world project to do this.
This tutorial assumes you have already completed Tutorial 0.
Step 0: Init the Project
A dehub project is initialized in the same way as a git project. An empty
directory is created, and
dehub init is run within that directory.
mkdir hello-world cd hello-world dehub init
dehub init does nearly exactly the same thing as
git init, with the primary
difference being that it sets the initial branch to be
main instead of
master. dehub makes a distinction between
master in order to help
prevent confusion between dehub and vanilla git projects, as well as to avoid
conflicts when migrating vanilla git projects to dehub.
Step 1: Add the First Account
A dehub project is not fully initialized until it has an account defined for it. dehub accounts refer to a specific user who has some kind of access to the project. Each account can have specific permissions for it, as well as multiple ways of signifying itself.
For now, you'll add a basic account
tut with a pgp key signifier. First,
.dehub directory, which is where all dehub project configuration
goes, and put your pgp key there:
mkdir .dehub gpg -a --export KEY_ID > .dehub/tut.asc
Next you'll create the
.dehub/config.yml file, which is where accounts are
actually defined (amongst many other things). The file should have the following
# contents of .dehub/config.yml --- accounts: - id: tut signifiers: - type: pgp_public_key_file path: ".dehub/tut.asc"
Finally, you'll commit these changes and the project will have its first commit! Committing changes works very similarly to committing comments (as you did in Tutorial 0). Where a comment commit merely carries a user's comment, a change commit describes a set of changes to the tracked files in the git repo.
git add --all dehub commit --as tut change
Like when you made a comment commit, this will pop up with your editor asking
for a description of the changes. Fill it in with something like
Initialize the project and save+close the editor. Depending on your pgp key settings you'll
likely be prompted for your pgp key password at this point. After that the
commit has been created!
Step 2: Inspect the Payload
In this step you're going to look at the commit you just created and learn about
the contents of the payload. To view the commit do
git show. Something similar
to the following should be output as the commit message:
commit 3cdcbc19546d4e6d817ebfba3e18afbc23283ec0 Author: username <> Date: Sat Apr 25 15:17:21 2020 -0600 Initialize the project --- type: change description: Initialize the project fingerprint: AG0s3yILU+0uIZltVY7A9/cgxr/pXk2MzGwExsY/hbIc credentials: - type: pgp_signature pub_key_id: 95C46FA6A41148AC body: BIG LONG STRING account: tut
All commits in a dehub project will contain a similar looking message. The first
line (the head) is always a human readable description of the commit. In this
case our commit description itself,
Initialize the project, was used.
After the head comes the payload, which is always a YAML encoded object. All
payloads have a
type field indicating what type of payload they are. That type
will determine what other fields the payload is expected to have. The other
fields in this payload object are:
description: This is the description which was input into the editor when creating the change commit.
fingerprint: A unique descriptor for this set of changes. It is computed using both
descriptionand the files changed.
credentials: A set of credentials for this commit, each one declaring that this commit has been given approval by a user. This commit has one
pgp_signaturecredential, created by the
bodyis a signature of the
fingerprintcreated by the
tut's pgp key.
Step 3: Create Another Commit
Now that the initial commit is created, and configuration has been added to the dehub project, you can continue on to use the project for what it was intended for: greeting the world!
Add a simple "hello world" script to the project by doing:
echo 'echo "hello world"' > hello.sh git add hello.sh dehub commit --as tut change --descr 'add hello.sh'
You'll notice that this time around you used the
--descr flag to declare the
change's description, rather than opening up the editor
Once again you can inspect the payload you just created using
git show, if
you'd like, or continue on to the next step to learn about commit verification.
Step 4: Verify Your Commits
All this work to create YAML encoded payloads has been done for one primary purpose: to make commits verifiable. A verifiable commit is one which follows the access controls defined by its parent.
Your dehub project doesn't have any explicitly defined access controls (that
will be covered in a future tutorial), and so the defaults are used. By default,
dehub requires that all commits in
main are change commits which have been
signed by at least one account.
In order to verify the HEAD commit you can do:
This command looks at the project configuration defined in the parent of HEAD
and verifies that HEAD conforms to it. The HEAD of your project is a change
commit signed by the account
tut, and so should be verifiable.
Arbitrary commits can be verified using the
--rev flag. This command will
verify the parent of HEAD, i.e. the initial commit:
dehub verify --rev HEAD^
The initial commit doesn't have a parent, and so is a special case for verification. The initial commit uses the configuration defined within itself in order to verify itself. This creates an exploit opportunity: if you clone a remote dehub project and an attacker intercepts that request they will be able to send you back a project with a different initial commit than what you expected. The whole project will still be verifiable, even though it's been compromised. For this reason it's important to manually verify that the initial commit of projects you clone are configured correctly, using the expected signifiers for the expected accounts.
You are now able to initialize a project, configure accounts within it, commit changes to its files, and verify those commits. Well done! Continue on to Tutorial 2, where you will learn how to configure dehub's access controls.