diff --git a/README.md b/README.md index 56b5bad..5071c5c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Git Guide -In this guide we are going to show you how to use Gitlab, however before we get going setting thingsup it's good to get an understanding of however the tool works that powers Gitlab (and Github). So let's dive in and take a look. +In this guide we are going to show you how to use Gitlab, however before we get going setting things up it's good to get an understanding of the tool works that powers Gitlab (and Github). So let's dive in and take a look. Where possible I'll include instructions for Github but this guide focuses on using Gitlab primerially. ## So what is Git? @@ -218,8 +218,189 @@ Warning: Permanently added 'gitlab.example.com' (ECDSA) to the list of known hos - Click Add SSH key. +#### Verify your key + +- Open Terminal. + +- Enter the following: + +``` +ssh -T git@github.com +# Attempts to ssh to GitHub +``` + +> You may see a warning like this: + +``` +The authenticity of host 'github.com (IP ADDRESS)' can't be established. +ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU. +Are you sure you want to continue connecting (yes/no)? +``` + +- Verify that the fingerprint in the message you see matches GitHub's public key fingerprint. If it does, then type yes: + +``` +Hi USERNAME! You've successfully authenticated, but GitHub does not +provide shell access. +``` + +> You may see this error message: + +``` +... +Agent admitted failure to sign using the key. +debug1: No more authentication methods to try. +Permission denied (publickey). +``` + +> This is a known problem with certain Linux distributions. For more information, see "Error: Agent admitted failure to sign." + +- Note: The remote command should exit with code 1. + +- Verify that the resulting message contains your username. If you receive a "permission denied" message, see "Error: Permission denied (publickey)." + + ## Advanced Setup (Highly Recommended) +#### Create a GPG key +If you don’t already have a GPG key, create one: + +- Install GPG for your operating system. If your operating system has gpg2 installed, replace gpg with gpg2 in the commands on this page. + +- To generate your key pair, run the command appropriate for your version of gpg: + +``` + # Use this command for the default version of GPG, including + # Gpg4win on Windows, and most macOS versions: + gpg --gen-key + + # Use this command for versions of GPG later than 2.1.17: + gpg --full-gen-key +``` + +- Select the algorithm your key should use, or press ``Enter`` to select the default option, RSA and RSA. +- Select the key length, in bits. GitLab recommends 4096-bit keys. +- Specify the validity period of your key. This value is subjective, and the default value is no expiration. +- To confirm your answers, enter y. +- Enter your name. +- Enter your email address. It must match a verified email address in your GitLab account. +- Optional. Enter a comment to display in parentheses after your name. +- GPG displays the information you’ve entered so far. Edit the information or press O (for Okay) to continue. +- Enter a strong password, then enter it again to confirm it. + +- To list your private GPG key, run this command, replacing with the email address you used when you generated the key: + +``` +gpg --list-secret-keys --keyid-format LONG +``` + +- In the output, identify the sec line, and copy the GPG key ID. It begins after the / character. In this example, the key ID is **30F2B65B9246B6CA**: + +``` +sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] + D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA +uid [ultimate] Mr. Robot +ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] +``` + +- To show the associated public key, run this command, replacing with the GPG key ID from the previous step: + +``` +gpg --armor --export +``` + +- Copy the public key, including the **BEGIN PGP PUBLIC KEY BLOCK** and **END PGP PUBLIC KEY BLOCK** lines. You need this key in the next step. + +#### Add the key to your account + +
+Instructions for Gitlab + +To add a GPG key to your user settings: + +- Sign in to GitLab. +- On the left sidebar, select your avatar. +- Select Edit profile. +- Select GPG Keys (). +- Select Add new key. +- In Key, paste your public key. +- To add the key to your account, select Add key. GitLab shows the key’s fingerprint, email address, and creation date: + +![GPG key single page](./img/gitlab_gpg.png) + +- After you add a key, you cannot edit it. Instead, remove the offending key and re-add it. + +
+ +
+Instructions for Github + + +- SIgn into Github +- In the upper-right corner of any page, click your profile photo, then click Settings. +- In the "Access" section of the sidebar, click SSH and GPG keys. +- Next to the "GPG keys" header, click New GPG key. +- In the "Title" field, type a name for your GPG key. +- In the "Key" field, paste the GPG key you copied when you generated your GPG key. +- Click Add GPG key. +- To confirm the action, authenticate to your GitHub account. + +
+ +### Sign your commits + +After you add your public key to your account, you can sign individual commits manually, or configure Git to default to signed commits. But first we need to let Git know about your GPG key. + +#### Tell Git about your signing key + +- Open your terminal. +- Use the gpg command to list the long form of the GPG keys for which you have both a public and private key. A private key is required for signing commits or tags. + +``` +gpg --list-secret-keys --keyid-format=long +``` + +> Note: Some GPG installations on Linux may require you to use gpg2 --list-keys --keyid-format LONG to view a list of your existing keys instead. In this case you will also need to configure Git to use gpg2 by running git config --global gpg.program gpg2. + +- From the list of GPG keys, copy the long form of the GPG key ID you'd like to use. In this example, the GPG key ID is ```3AA5C34371567BD2```: + +``` +$ gpg --list-secret-keys --keyid-format=long +/Users/hubot/.gnupg/secring.gpg +------------------------------------ +sec 4096R/3AA5C34371567BD2 2016-03-10 [expires: 2017-03-10] +uid Hubot +ssb 4096R/4BB6D45482678BE3 2016-03-10 +``` + +- To set your primary GPG signing key in Git, paste the text below, substituting in the GPG primary key ID you'd like to use. In this example, the GPG key ID is ```3AA5C34371567BD2```: + +``` +git config --global user.signingkey 3AA5C34371567BD2 +``` + +#### Sign individual Git commits manually + +Add -S flag to any commit you want to sign: + +``` +git commit -S -m "My commit message" +``` + +- Enter the passphrase of your GPG key when asked. +- Push to GitLab/Github and check that your commits are verified. + +#### Sign all Git commits by default + +If you want to sign all your commits from now on, and I recomend this, run the following command. + +``` +git config --global commit.gpgsign true +``` + +Now you're all ready to get started with learning how to use Git. + +(![Link to Ric's Mastodon Account](.img/mastodon.png){width=100 height=100px})[https://awscommunity.social/@Ric] \ No newline at end of file diff --git a/img/gitlab_gpg.png b/img/gitlab_gpg.png new file mode 100644 index 0000000..ae0a869 Binary files /dev/null and b/img/gitlab_gpg.png differ diff --git a/img/mastodon.png b/img/mastodon.png new file mode 100755 index 0000000..8d8d79e Binary files /dev/null and b/img/mastodon.png differ