Getting Started

Common tools

Source Code Management

Github

GitHub: Where the world builds softwareGitHub

• Your no-reply email can be found at https://github.com/settings/emails and it looks like ${USER_ID}+${USERNAME}@users.noreply.github.com

Gitlab

Iterate faster, innovate togetherGitLab

• Your no-reply email can be found at https://gitlab.com/-/user_settings/profile and it looks like ${USER_ID}-${USERNAME}@users.noreply.gitlab.com

Creating your keys

Keys are used for platforms to identify you. It's recommended to use Public-Key-Infrastructure (PKI) technologies for your authentication keys, and the below covers generating and submission of SSH and GPG keys. Remember to never send anyone your private keys.

GPG Keys

GPG keys are used to sign commits. To generate a GPG key, run:

gpg --full-gen-key

Enter in options as shown in your terminal:

1. RSA and RSA

2. 4096-bits long

3. 1 year validity

4. Enter any name for the Real name field (doesn't have to be your real name)

5. Use the no-reply email of the platform you are intending to use the GPG key with for the Email field (this is important for personal data hygiene)

6. Use a computer identifier for the Comment field (ideally you can recognise which device it comes from based on this field)

List your GPG keys using:

gpg --list-secret-keys --keyid-format=LONG

Identify the key to export. The ID of the key can be found in the line rsa4096/${KEY_ID}

Export your GPG key using:

gpg --armor --export ${KEY_ID};

Your exported GPG public key should look like:

-----BEGIN PGP PUBLIC KEY BLOCK-----

mQINB...
...
...
-----END PGP PUBLIC KEY BLOCK-----

Copy that block of text and paste it into wherever it needs to be.

SSH Keys

SSH keys are used to authenticate you when you are cloning repositories or pushing code changes. To generate an SSH key, run:

ssh-keygen -t rsa -b 8192

Save it to ~/.ssh/id_rsa if it's your primary SSH key.

To get your public key, assuming it's your primary SSH key, run:

cat ~/.ssh/id_rsa.pub

Your public key should look like:

ssh-rsa AAAA..... ${USERNAME}@${NETWORK_HOSTNAME}

Copy that block of text and paste it into wherever it needs to be

Remember never to share your private key at ~/.ssh/id_rsa with anyone.

Uploading your keys

In order for your service provider to identify you, you will have to submit your public keys to the service provider via their web UI. Your computer will sign messages using your private keys before sending them to the service provider who will then verify that the messages can be validated against your pre-uploaded public keys.

Github

Your SSH and GPG keys will be available at:

https://github.com/settings/keysgithub.com

Navigate to that page and click on New SSH key, give it a name which can identify your machine and paste in your SSH public key from above

Scroll down and click on New GPG key, give it a name which can identify your machine and paste in your public GPG key from above.

GItlab

Your SSH keys will be available at:

https://gitlab.com/-/user_settings/ssh_keysgitlab.com

Navigate to that page and click on Add new key, give it a name which can identify your machine and paste in your SSH public key from above

Your GPG keys will be available at:

https://gitlab.com/-/user_settings/gpg_keysgitlab.com

Navigate to that page and click on Add new key, give it a name which can identify your machine and paste in your GPG public key from above

Configuring GPG key usage

Finally, we configure our machine to use the keys we generated. SSH keys do not usually face any issues and the SSH agent will be able to find the correct keys to use from ~/.ssh. We will cover GPG key configurations.

Configuring a standalone local repository

The configuration can be found at .git/config relative to your project's root directory. Open it up and add the following:

[user]
  name = your name
  email = [e-mail]
  signingkey = ${KEY_ID}

Get the key ID by running gpg --list-secret-keys --keyid-format=LONG and getting the key ID from the line indicating rsa4096/${KEY_ID}

Configuring a directory and all subpaths

The following assumes that you have a directory named github.com where all your Github projects are stored. Open the root Git configuration file at ~/.gitconfig and add in:

# for all github commits...
[includeIf "gitdir:**/github.com/"]
  path = ~/.github.com.gitconfig

Open the conditionally included file at ~/.github.com.gitconfig and add in:

[user]
  name = your name
  email = [e-mail]
  signingkey = ${KEY_ID}

Similar to above, get the key ID by running gpg --list-secret-keys --keyid-format=LONG and getting the key ID from the line indicating rsa4096/${KEY_ID}