diff options
Diffstat (limited to 'doc/user/project/repository/gpg_signed_commits/index.md')
| -rw-r--r-- | doc/user/project/repository/gpg_signed_commits/index.md | 335 |
1 files changed, 144 insertions, 191 deletions
diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index f5cea8a8075..00998c9a227 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -6,129 +6,96 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Signing commits with GPG **(FREE)** -You can use a GPG key to sign Git commits made in a GitLab repository. Signed -commits are labeled **Verified** if the identity of the committer can be -verified. To verify the identity of a committer, GitLab requires their public -GPG key. +You can sign the commits you make in a GitLab repository with a +GPG ([GNU Privacy Guard](https://gnupg.org/)) key. When you add a cryptographic +signature to your commit, you provide extra assurance that a commit +originated from you, rather than an impersonator. If GitLab can verify a commit +author's identity with a public GPG key, the commit is marked **Verified** in the +GitLab UI. You can then configure [push rules](../push_rules.md#enabling-push-rules) +for your project to reject individual commits not signed with GPG, or reject all +commits from unverified users. NOTE: -The term GPG is used for all OpenPGP/PGP/GPG related material and +GitLab uses the term GPG for all OpenPGP, PGP, and GPG-related material and implementations. -To view a user's public GPG key, you can: - -- Go to `https://gitlab.example.com/<username>.gpg`. -- Select **View public GPG keys** (**{key}**) in the top right of the user's profile. - -GPG verified tags are not supported yet. - -See the [further reading](#further-reading) section for more details on GPG. - -## How GitLab handles GPG - -GitLab uses its own keyring to verify the GPG signature. It does not access any -public key server. - -For a commit to be verified by GitLab: +For GitLab to consider a commit verified: - The committer must have a GPG public/private key pair. -- The committer's public key must have been uploaded to their GitLab - account. -- One of the emails in the GPG key must match a **verified** email address - used by the committer in GitLab. This address will be part of the public key. - If you want to keep this address private, use the automatically generated +- The committer's public key must be uploaded to their GitLab account. +- One of the email addresses in the GPG public key must match a **verified** email address + used by the committer in GitLab. To keep this address private, use the automatically generated [private commit email address](../../../profile/index.md#use-an-automatically-generated-private-commit-email) GitLab provides in your profile. - The committer's email address must match the verified email address from the GPG key. -## Generating a GPG key - -If you don't already have a GPG key, the following steps can help you get -started: - -1. [Install GPG](https://www.gnupg.org/download/index.html) for your operating system. - If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in - the following commands. -1. Generate the private/public key pair with the command appropriate for your version - of `gpg`. This command spawns a series of questions: - - ```shell - # Use this command for the default version of gpg, including - # Gpg4win on Windows, and most macOS versions: - gpg --gen-key +GitLab uses its own keyring to verify the GPG signature. It does not access any +public key server. - # Use this command for versions of GPG later than 2.1.17: - gpg --full-gen-key - ``` +GPG verified tags are not supported. -1. The first question is which algorithm can be used. Select the kind you want - or press <kbd>Enter</kbd> to choose the default (RSA and RSA): +For more details about GPG, refer to the [related topics list](#related-topics). - ```plaintext - Please select what kind of key you want: - (1) RSA and RSA (default) - (2) DSA and Elgamal - (3) DSA (sign only) - (4) RSA (sign only) - Your selection? 1 - ``` +## View a user's public GPG key -1. The next question is key length. We recommend you choose `4096`: +To view a user's public GPG key, you can either: - ```plaintext - RSA keys may be between 1024 and 4096 bits long. - What keysize do you want? (2048) 4096 - Requested keysize is 4096 bits - ``` +- Go to `https://gitlab.example.com/<USERNAME>.gpg`. GitLab displays the GPG key, + if the user has configured one, or a blank page for users without a configured GPG key. +- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the top right + of the user's profile, select **View public GPG keys** (**{key}**). -1. Specify the validity period of your key. This is something - subjective, and you can use the default value, which is to never expire: +## Configure commit signing - ```plaintext - Please specify how long the key should be valid. - 0 = key does not expire - <n> = key expires in n days - <n>w = key expires in n weeks - <n>m = key expires in n months - <n>y = key expires in n years - Key is valid for? (0) 0 - Key does not expire at all - ``` +To sign commits, you must configure both your local machine and your GitLab account: -1. Confirm that the answers you gave were correct by typing `y`: +1. [Create a GPG key](#create-a-gpg-key). +1. [Add a GPG key to your account](#add-a-gpg-key-to-your-account). +1. [Associate your GPG key with Git](#associate-your-gpg-key-with-git). +1. [Sign your Git commits](#sign-your-git-commits). - ```plaintext - Is this correct? (y/N) y - ``` +### Create a GPG key -1. Enter your real name, the email address to be associated with this key - (should match a verified email address you use in GitLab) and an optional - comment (press <kbd>Enter</kbd> to skip): +If you don't already have a GPG key, create one: - ```plaintext - GnuPG needs to construct a user ID to identify your key. +1. [Install GPG](https://www.gnupg.org/download/) for your operating system. + If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in + the commands on this page. +1. To generate your key pair, run the command appropriate for your version of `gpg`: - Real name: Mr. Robot - Email address: <your_email> - Comment: - You selected this USER-ID: - "Mr. Robot <your_email>" + ```shell + # Use this command for the default version of GPG, including + # Gpg4win on Windows, and most macOS versions: + gpg --gen-key - Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O + # Use this command for versions of GPG later than 2.1.17: + gpg --full-gen-key ``` -1. Pick a strong password when asked and type it twice to confirm. -1. Use the following command to list the private GPG key you just created: +1. Select the algorithm your key should use, or press <kbd>Enter</kbd> to select + the default option, `RSA and RSA`. +1. Select the key length, in bits. GitLab recommends 4096-bit keys. +1. Specify the validity period of your key. This value is subjective, and the + default value is no expiration. +1. To confirm your answers, enter `y`. +1. Enter your name. +1. Enter your email address. It must match a + [verified email address](../../../profile/index.md#change-the-email-displayed-on-your-commits) + in your GitLab account. +1. Optional. Enter a comment to display in parentheses after your name. +1. GPG displays the information you've entered so far. Edit the information or press + <kbd>O</kbd> (for `Okay`) to continue. +1. Enter a strong password, then enter it again to confirm it. +1. To list your private GPG key, run this command, replacing + `<EMAIL>` with the email address you used when you generated the key: ```shell - gpg --list-secret-keys --keyid-format LONG <your_email> + gpg --list-secret-keys --keyid-format LONG <EMAIL> ``` - Replace `<your_email>` with the email address you entered above. - -1. Copy the GPG key ID that starts with `sec`. In the following example, that's - `30F2B65B9246B6CA`: +1. 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`: ```plaintext sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] @@ -137,49 +104,46 @@ started: ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] ``` -1. Export the public key of that ID (replace your key ID from the previous step): +1. To show the associated public key, run this command, replacing `<ID>` with the + GPG key ID from the previous step: ```shell - gpg --armor --export 30F2B65B9246B6CA + gpg --armor --export <ID> ``` -1. Finally, copy the public key and [add it in your user settings](#adding-a-gpg-key-to-your-account) +1. 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. -## Adding a GPG key to your account +### Add a GPG key to your account -NOTE: -After you add a key, you cannot edit it, only remove it. In case the paste -didn't work, you have to remove the offending key and re-add it. - -You can add a GPG key in your user settings: +To add a GPG key to your user settings: +1. Sign in to GitLab. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys**. -1. Paste your _public_ key in the **Key** text box. - -  - -1. Select **Add key** to add it to GitLab. You can see the key's fingerprint, the corresponding - email address, and creation date. +1. On the left sidebar, select **GPG Keys** (**{key}**). +1. In **Key**, paste your _public_ key. +1. To add the key to your account, select **Add key**. GitLab shows the key's + fingerprint, email address, and creation date:  -## Associating your GPG key with Git +After you add a key, you cannot edit it. Instead, remove the offending key and re-add it. -After you have [created your GPG key](#generating-a-gpg-key) and [added it to -your account](#adding-a-gpg-key-to-your-account), it's time to tell Git which -key to use. +### Associate your GPG key with Git -1. Use the following command to list the private GPG key you just created: +After you [create your GPG key](#create-a-gpg-key) and +[add it to your account](#add-a-gpg-key-to-your-account), you must configure Git +to use this key: + +1. Run this command to list the private GPG key you just created, + replacing `<EMAIL>` with the email address for your key: ```shell - gpg --list-secret-keys --keyid-format LONG <your_email> + gpg --list-secret-keys --keyid-format LONG <EMAIL> ``` - Replace `<your_email>` with the email address you entered above. - -1. Copy the GPG key ID that starts with `sec`. In the following example, that's +1. Copy the GPG private key ID that starts with `sec`. In this example, the private key ID is `30F2B65B9246B6CA`: ```plaintext @@ -189,114 +153,103 @@ key to use. ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] ``` -1. Tell Git to use that key to sign the commits: +1. Run this command to configure Git to sign your commits with your key, + replacing `<KEY ID>` with your GPG key ID: ```shell - git config --global user.signingkey 30F2B65B9246B6CA + git config --global user.signingkey <KEY ID> ``` - Replace `30F2B65B9246B6CA` with your GPG key ID. - -1. Optional. If Git is using `gpg` and you get errors like `secret key not available` - or `gpg: signing failed: secret key not available`, run the following command to - change to `gpg2`: +1. Optional. If Git uses `gpg` and you get errors like `secret key not available` + or `gpg: signing failed: secret key not available`, run this command to + use `gpg2` instead: ```shell git config --global gpg.program gpg2 ``` -## Signing commits +### Sign your Git commits -After you have [created your GPG key](#generating-a-gpg-key) and [added it to -your account](#adding-a-gpg-key-to-your-account), you can start signing your -commits: +After you [add your public key to your account](#add-a-gpg-key-to-your-account), +you can sign individual commits manually, or configure Git to default to signed commits: -1. Commit like you used to, the only difference is the addition of the `-S` flag: +- Sign individual Git commits manually: + 1. Add `-S` flag to any commit you want to sign: - ```shell - git commit -S -m "My commit msg" - ``` + ```shell + git commit -S -m "My commit message" + ``` -1. Enter the passphrase of your GPG key when asked. -1. Push to GitLab and check that your commits [are verified](#verifying-commits). + 1. Enter the passphrase of your GPG key when asked. + 1. Push to GitLab and check that your commits [are verified](#verify-commits). +- Sign all Git commits by default by running this command: -If you don't want to type the `-S` flag every time you commit, you can tell Git -to sign your commits automatically: + ```shell + git config --global commit.gpgsign true + ``` -```shell -git config --global commit.gpgsign true -``` +## Verify commits -## Verifying commits +You can review commits for a merge request, or for an entire project: -1. Within a project or [merge request](../../merge_requests/index.md), navigate to - the **Commits** tab. Signed commits show a badge containing either - **Verified** or **Unverified**, depending on the verification status of the GPG - signature. +1. To review commits for a project: + 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the left sidebar, select **Repository > Commits**. +1. To review commits for a merge request: + 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the left sidebar, select **Merge requests**, then select your merge request. + 1. Select **Commits**. +1. Identify the commit you want to review. Signed commits show either a **Verified** + or **Unverified** badge, depending on the verification status of the GPG + signature. Unsigned commits do not display a badge:  -1. By clicking on the GPG badge, details of the signature are displayed. +1. To display the signature details for a commit, select the GPG badge:  -  +  -## Revoking a GPG key +## Revoke a GPG key -Revoking a key **unverifies** already signed commits. Commits that were -verified by using this key changes to an unverified state. Future commits -stay unverified after you revoke this key. This action should be used -in case your key has been compromised. +If a GPG key becomes compromised, revoke it. Revoking a key changes both future and past commits: + +- Past commits signed by this key are marked as unverified. +- Future commits signed by this key are marked as unverified. To revoke a GPG key: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys**. +1. On the left sidebar, select **GPG Keys** (**{key}**). 1. Select **Revoke** next to the GPG key you want to delete. -## Removing a GPG key +## Remove a GPG key + +When you remove a GPG key from your GitLab account: -Removing a key **does not unverify** already signed commits. Commits that were -verified by using this key stay verified. Only unpushed commits stay -unverified after you remove this key. To unverify already signed commits, you need -to [revoke the associated GPG key](#revoking-a-gpg-key) from your account. +- Previous commits signed with this key remain verified. +- Future commits (including any commits created but not yet pushed) that attempt + to use this key are unverified. To remove a GPG key from your account: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys**. -1. Select the trash icon (**{remove}**) next to the GPG key you want to delete. - -## Rejecting commits that are not signed **(PREMIUM)** - -You can configure your project to reject commits that aren't GPG-signed -via [push rules](../push_rules.md). - -## GPG signing API - -Learn how to [get the GPG signature from a commit via API](../../../../api/commits.md#get-gpg-signature-of-a-commit). - -## Further reading - -For more details about GPG, see: - -- [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) -- [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) -- [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) -- [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) -- [Review existing GPG keys in your instance](../../../admin_area/credentials_inventory.md#review-existing-gpg-keys) - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +1. On the left sidebar, select **GPG Keys** (**{key}**). +1. Select **Remove** (**{remove}**) next to the GPG key you want to delete. + +If you must unverify both future and past commits, +[revoke the associated GPG key](#revoke-a-gpg-key) instead. + +## Related topics + +- [Sign commits and tags with X.509 certificates](../x509_signed_commits/index.md) +- [Commits API](../../../../api/commits.md) +- GPG resources: + - [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) + - [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) + - [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) + - [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) + - [Review existing GPG keys in your instance](../../../admin_area/credentials_inventory.md#review-existing-gpg-keys) |