vcs:commit-signing

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
vcs:commit-signing [2021/04/01 04:48] – add install instructions for Linux distros; grammar bishopvcs:commit-signing [2021/04/01 16:48] (current) – improve documentation around key expiration bishop
Line 64: Line 64:
 Use the package manager available in your OS. See also the [[https://gnupg.org/download/index.html|GPG binaries download page]] for direct downloads. Use the package manager available in your OS. See also the [[https://gnupg.org/download/index.html|GPG binaries download page]] for direct downloads.
  
-== MacOS with Homebrew ==+== Recent versions of OS and distributions ==
  
-<code> +^ OS / Distribution ^ Command(s) ^ 
-$ brew install gpg +| macOS with Homebrew | ''brew install gpg'' | 
-</code>+| Ubuntu, Debian, Mint, Kali | ''sudo apt install gnupg'' | 
 +| CentOS, Fedora, RHEL | ''sudo yum install gnupg'' |
  
-== Ubuntu, Debian, Mint and Kali ==+== Older releases ==
  
-<code> +^ OS ^ Command(s) ^ 
-$ sudo apt install gnupg +| Ubuntu 18.04LTS | ''sudo add-apt-repository ppa:git-core/ppa && sudo apt update && sudo apt install git'' |
-</code> +
- +
-== CentOS, Fedora, and RHEL == +
- +
-<code> +
-$ sudo yum install gnupg +
-</code>+
  
 === Update start-up files === === Update start-up files ===
  
-These instructions assume you're using Zsh. If you're using a different shell, replace ''.zshrc'' with your shell's startup file for interactivity (e.g., [[https://scriptingosx.com/2017/04/about-bash_profile-and-bashrc-on-macos/|.bash_profile for Terminal.app]]). It's been reported that iTerm2 in Big Sur needs ''.zshenv''. Vanilla bash will need ''.bash_profile''.+These instructions assume you're using Zsh. If you're using a different shell, replace ''.zshrc'' with your shell's startup file for interactivity (e.g., ''.bash_profile'' in Linux, macOS accounts that haven't migrated to Zsh or in the [[https://scriptingosx.com/2017/04/about-bash_profile-and-bashrc-on-macos/|Terminal.app]]). It's been reported that iTerm2 in macOS Big Sur needs ''.zshenv''.
  
 <code> <code>
Line 110: Line 104:
 ==== Step 2 of 7: Generate a new, unique GPG signing key ==== ==== Step 2 of 7: Generate a new, unique GPG signing key ====
  
-With GPG installed and operational, the next step is to create a key. In the examples that follow, replace references to "Your Name" with your full name; replace "you@php.net" with your PHP.net email address.+With GPG installed and operational, the next step is to create a key.
  
-You will need to choose a strong passphrase and store that in a secure location.+In the examples that follow, replace references to "Your Name" with your full name; replace "you@php.net" with your PHP.net email address. 
 + 
 +You will be prompted to enter a strong passphrase. Remember to store that in a secure location, like a password manager.
  
 === From a macOS/Linux/POSIX command line === === From a macOS/Linux/POSIX command line ===
Line 123: Line 119:
 Name-Real: Your Name Name-Real: Your Name
 Name-Email: you@php.net Name-Email: you@php.net
-Passphrase: enter-a-strong-password-here-and-save-it-in-a-password-manager 
 ') ')
 </code> </code>
 +
 +Note that this creates an immortal key. See the section "Frequently Asked Questions" for a discussion of the pros and cons to this.
  
 ==== Step 3 of 7: Get the key ID ==== ==== Step 3 of 7: Get the key ID ====
Line 210: Line 207:
   * If that doesn't prompt you for your password, your GPG agent is not running. See the "Troubleshooting" section.   * If that doesn't prompt you for your password, your GPG agent is not running. See the "Troubleshooting" section.
  
-Now, we have a signed tag. We'll push this up to GitHub to ensure we can see that it's a verified tag:+Now, we have a signed tag. We can verify that in the git log: 
 + 
 +<code> 
 +$ git show --show-signature "${TEMP_TAG}" 
 +tag myusername-1599166378-6517-signature-test 
 +Tagger: Your Name <you@php.net> 
 +Date:   Tue Aug 25 16:42:17 EDT 2020 
 + 
 +Temporary tag for testing signing 
 +-----BEGIN PGP SIGNATURE----- 
 +ABCD...=== 
 +-----END PGP SIGNATURE----- 
 +</code> 
 + 
 +We'll push this temporary tag to GitHub to check that GitHub recognizes the signature:
  
 <code> <code>
Line 222: Line 233:
 </code> </code>
  
-Let's go check that it's verified on GitHub. Navigate to the [[https://github.com/php/php-src/tags|repository's tag page]].+Now, navigate to the [[https://github.com/php/php-src/tags|repository's tag page]].
  
 Near the top of the list you'll see the recently pushed tag and off to the right there should be green text of "Verified". Click on the "Verified" text and a pop-up appears showing your information and key. Near the top of the list you'll see the recently pushed tag and off to the right there should be green text of "Verified". Click on the "Verified" text and a pop-up appears showing your information and key.
Line 238: Line 249:
 $ git tag --delete "${TEMP_TAG}" $ git tag --delete "${TEMP_TAG}"
 </code> </code>
 +
  
 ===== Troubleshooting ===== ===== Troubleshooting =====
Line 315: Line 327:
 git config --list git config --list
 </code> </code>
 +
 +
 +===== Frequently Asked Questions =====
 +
 +==== Can I sign commits using VSCode, Emacs, PHPStorm, vim, or ${other_favorite_editor}? ====
 +
 +Yes, probably. These IDE just pass down the git responsibility to the underlying tool chain, so if git is configured properly on the command line, it should work in your favorite IDE. However, you may need to configure GPG to use the native key chain instead of its default agent (''pinentry''), so that the IDE can prompt for and remember the password.
 +
 +==== What if I lose my key? ====
 +
 +Laptop stolen. Accidentally ''rm'' the file. Whatever the case may be, the simplest way to revoke authorization is to open the GitHub SSH and GPG keys page, find the key, and remove it. Any future use of that key will not appear as valid in GitHub. Then follow this guide to add a new key.
 +
 +==== Do I need a passphrase? ====
 +
 +Yes. If your private key falls into the wrong hands, they'll be unable to use the key without the passphrase.
 +
 +==== Should my key expire? ====
 +
 +This guide created an immortal key (see step 2), because //for this use case// [[https://security.stackexchange.com/a/79386/72365|key expiration does not add any security]] while it increases development friction.
 +
 +As part of regular security hygiene, however, consider creating a new key and replacing the old one at GitHub annually.
  
  
 ===== Advanced Setup ===== ===== Advanced Setup =====
 +
 +==== Configure more key options ====
 +
 +This guide created a unique key in batch mode, to simplify working through the steps. However, more key options are available, which can be entered interactively:
 +
 +<code>
 +$ gpg --full-generate-key
 +</code>
 +
 +When doing this, make sure to select a key type of ''RSA'' and a key length of ''4096'', as GitHub sets that as a minimum requirement.
  
 ==== Extend the lifetime of cached passwords ==== ==== Extend the lifetime of cached passwords ====
Line 359: Line 402:
  
 The ''.gitconfig'' file, lines 1 through 11 set a global signing key, while lines 13 and 14 use a //different// configuration for all repositories under the ''$HOME/code/php'' directory. For those repos, it uses the signing key ''7DB08A14''. The ''.gitconfig'' file, lines 1 through 11 set a global signing key, while lines 13 and 14 use a //different// configuration for all repositories under the ''$HOME/code/php'' directory. For those repos, it uses the signing key ''7DB08A14''.
 +
 +==== Always show signatures in logs ====
 +
 +To always display signatures in commit logs, you can configure git to always display them by default
 +
 +<code>
 +    git config --global log.showSignature true
 +</code>
  
 ===== Thanks ===== ===== Thanks =====
  
 This guide was adapted, with permission, from internal developer documentation at [[https://github.com/lifeomic|LifeOmic]]. This guide was adapted, with permission, from internal developer documentation at [[https://github.com/lifeomic|LifeOmic]].
vcs/commit-signing.1617252528.txt.gz · Last modified: 2021/04/01 04:48 by bishop

Page Tools