Skip to content

G
gitlab-ce
Commit 4be7b092 authored by Kati Paizee's avatar Kati Paizee
Browse files
Options

Merge branch 'aqualls-signing-commits' into 'master' 

CTRT revision of GPG signing page

See merge request gitlab-org/gitlab!82541
parents 0b53f192 891c8a72
Show whitespace changes
Inline Side-by-side
Showing with 145 additions and 192 deletions
doc/user/project/repository/gpg_signed_commits/index.md
View file @ 4be7b092
......@@ -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.
![Paste GPG public key](img/profile_settings_gpg_keys_paste_pub.png)
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:
![GPG key single page](img/profile_settings_gpg_keys_single_key.png)
## 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"
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:
![Signed and unsigned commits](img/project_signed_and_unsigned_commits.png)
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:
![Signed commit with verified signature](img/project_signed_commit_verified_signature.png)
![Signed commit with verified signature](img/project_signed_commit_unverified_signature.png)
![Signed commit with unverified signature](img/project_signed_commit_unverified_signature.png)
## 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)
doc/user/project/repository/x509_signed_commits/index.md
View file @ 4be7b092
......@@ -20,7 +20,7 @@ The main difference is the way GitLab determines whether or not the developer's
(A trust store is a repository of trusted security certificates.) Combined with
any required intermediate certificates in the signature, the developer's certificate
can be chained back to a trusted root certificate.
- For GPG, developers [add their GPG key](../gpg_signed_commits/index.md#adding-a-gpg-key-to-your-account)
- For GPG, developers [add their GPG key](../gpg_signed_commits/index.md#add-a-gpg-key-to-your-account)
to their account.
GitLab uses its own certificate store and therefore defines the
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7