GPG Signing Setup for Releases
This guide explains how to set up GPG signing for nemo-git-integration releases, allowing users to verify that builds are authentically from you.
Overview
When you create a tagged release (e.g., v1.0.0), the CI pipeline will:
- Build
.debpackages on Ubuntu 22.04 and 24.04 - Sign each package with your GPG key
- Create signed SHA256 checksums
- Publish everything to GitHub Releases
Step 1: Generate a GPG Key (if you don’t have one)
# Generate a new GPG key
gpg --full-generate-key
Choose these options:
- Kind: RSA and RSA (default)
- Key size: 4096 bits
- Validity: 2 years (or your preference)
- Real name: Your Name
- Email: your-email@example.com (use your GitHub email)
- Passphrase: Choose a strong passphrase
Step 2: Find Your Key ID
# List your keys
gpg --list-secret-keys --keyid-format=long
# Output will look like:
# sec rsa4096/ABCD1234EFGH5678 2024-01-01 [SC] [expires: 2026-01-01]
# FULL_KEY_FINGERPRINT_HERE
# uid [ultimate] Your Name <your-email@example.com>
# ssb rsa4096/WXYZ9876IJKL5432 2024-01-01 [E] [expires: 2026-01-01]
Your Key ID is the part after rsa4096/ (e.g., ABCD1234EFGH5678).
Step 3: Export Your Private Key
# Export the private key (keep this SECRET!)
gpg --armor --export-secret-keys YOUR_KEY_ID > private-key.asc
# View the contents (you'll need this for GitHub Secrets)
cat private-key.asc
⚠️ IMPORTANT: Delete private-key.asc after adding it to GitHub Secrets!
Step 4: Add Secrets to GitHub Repository
Go to your repository → Settings → Secrets and variables → Actions → New repository secret
Add these three secrets:
| Secret Name | Value |
|---|---|
GPG_PRIVATE_KEY | The entire contents of private-key.asc (including BEGIN/END lines) |
GPG_PASSPHRASE | Your GPG key passphrase |
GPG_KEY_ID | Your key ID (e.g., ABCD1234EFGH5678) |
Step 5: Publish Your Public Key
Users need your public key to verify signatures.
Option A: Upload to a keyserver
gpg --keyserver keyserver.ubuntu.com --send-keys YOUR_KEY_ID
gpg --keyserver keys.openpgp.org --send-keys YOUR_KEY_ID
Option B: Export and add to your repository
# Export public key
gpg --armor --export YOUR_KEY_ID > public-key.asc
Add this file to your repository root or docs/ folder.
Option C: Add to GitHub profile
Go to GitHub → Settings → SSH and GPG keys → New GPG key, then paste your public key.
Step 6: Create a Release
# Tag a version
git tag -s v1.0.0 -m "Release v1.0.0"
# Push the tag
git push origin v1.0.0
The CI pipeline will automatically:
- Run all tests
- Build packages for Ubuntu 22.04 and 24.04
- Sign packages with your GPG key
- Create checksums and sign them
- Publish to GitHub Releases
For Users: Verifying Downloads
Step 1: Import the maintainer’s public key
# From keyserver
gpg --keyserver keyserver.ubuntu.com --recv-keys MAINTAINER_KEY_ID
# Or from file
gpg --import public-key.asc
Step 2: Verify the package signature
# Download the .deb and .deb.asc files
gpg --verify nemo-git-integration_1.0.0_all.deb.asc nemo-git-integration_1.0.0_all.deb
Expected output:
gpg: Signature made [date]
gpg: using RSA key [KEY_ID]
gpg: Good signature from "Maintainer Name <email>"
Step 3: Verify checksums
# Verify the signed checksum file
gpg --verify SHA256SUMS.gpg
# Check the package checksum
sha256sum -c SHA256SUMS
Troubleshooting
“gpg: signing failed: No secret key”
- Ensure
GPG_PRIVATE_KEYsecret contains the full private key including headers - Verify
GPG_KEY_IDmatches your key
“gpg: signing failed: Inappropriate ioctl for device”
- This is handled by the
--pinentry-mode loopbackflag in the workflow
Key expired
- Generate a new key or extend your existing key’s expiration
- Update the GitHub secrets with the new key
Security Best Practices
- Use a dedicated signing key - Don’t use your personal GPG key
- Strong passphrase - Use a unique, strong passphrase for the signing key
- Rotate keys - Consider rotating keys every 1-2 years
- Backup securely - Keep an encrypted backup of your private key offline
-
Revocation certificate - Generate and store a revocation certificate:
gpg --gen-revoke YOUR_KEY_ID > revoke.asc
Quick Reference
# Generate key
gpg --full-generate-key
# List keys
gpg --list-secret-keys --keyid-format=long
# Export private (for GitHub secret)
gpg --armor --export-secret-keys KEY_ID
# Export public (for users)
gpg --armor --export KEY_ID > public-key.asc
# Create signed tag
git tag -s v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0