|
| 1 | +# GPG Key Setup for Auto-Version-Bump Workflow |
| 2 | + |
| 3 | +This guide explains how to generate a GPG key and configure it for the auto-version-bump workflow to create verified commits. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +- GPG installed on your local machine |
| 8 | +- Access to repository Settings → Secrets and variables → Actions |
| 9 | +- A verified email address in your GitHub account |
| 10 | + |
| 11 | +## Important: Key Type Compatibility |
| 12 | + |
| 13 | +**⚠️ Use RSA keys for best compatibility with GitHub Actions** |
| 14 | + |
| 15 | +While GitHub supports various key types (RSA, ECC/EdDSA), **RSA keys are recommended** for GitHub Actions workflows because: |
| 16 | +- Better compatibility with automated signing in non-interactive environments |
| 17 | +- Avoid "Inappropriate ioctl for device" errors common with ECC keys |
| 18 | +- More reliable pinentry-mode loopback support |
| 19 | + |
| 20 | +**Avoid**: ECC (Curve 25519) sign-only keys may cause signing failures in CI/CD environments. |
| 21 | + |
| 22 | +## Step 1: Generate a GPG Key |
| 23 | + |
| 24 | +Run the following commands on your local machine: |
| 25 | + |
| 26 | +```bash |
| 27 | +# Generate a new GPG key |
| 28 | +gpg --full-generate-key |
| 29 | +``` |
| 30 | + |
| 31 | +When prompted: |
| 32 | +1. **Key type**: Select `(1) RSA and RSA (default)` ⚠️ **IMPORTANT: Use RSA, not ECC** |
| 33 | +2. **Key size**: Enter `4096` |
| 34 | +3. **Key validity**: Enter `0` (key does not expire) or set an expiration |
| 35 | +4. **Real name**: Enter your name (e.g., "Your Name" or "GhostClass Bot") |
| 36 | +5. **Email address**: Enter your verified GitHub email (e.g., `yourname@example.com` or `61821107+devakesu@users.noreply.github.com`) |
| 37 | +6. **Comment**: Optional, can leave blank |
| 38 | +7. **Passphrase**: Enter a strong passphrase (you'll need this later) |
| 39 | + |
| 40 | +## Step 2: Export Your GPG Key |
| 41 | + |
| 42 | +After generating the key, export it: |
| 43 | + |
| 44 | +```bash |
| 45 | +# List your GPG keys to get the key ID |
| 46 | +gpg --list-secret-keys --keyid-format=long |
| 47 | + |
| 48 | +# You'll see output like: |
| 49 | +# sec rsa4096/ABC123DEF456 2024-01-01 [SC] |
| 50 | +# 1234567890ABCDEF1234567890ABCDEF12345678 |
| 51 | +# uid [ultimate] Your Name <your-email@example.com> |
| 52 | +# ssb rsa4096/XYZ789ABC123 2024-01-01 [E] |
| 53 | + |
| 54 | +# Export the private key (replace ABC123DEF456 with your key ID) |
| 55 | +gpg --armor --export-secret-keys ABC123DEF456 |
| 56 | + |
| 57 | +# Export the public key |
| 58 | +gpg --armor --export ABC123DEF456 |
| 59 | +``` |
| 60 | + |
| 61 | +## Step 3: Add GPG Key to GitHub Account |
| 62 | + |
| 63 | +1. Go to GitHub → Settings → SSH and GPG keys |
| 64 | +2. Click "New GPG key" |
| 65 | +3. Paste your **public key** (the output from `gpg --armor --export`) |
| 66 | +4. Click "Add GPG key" |
| 67 | + |
| 68 | +## Step 4: Verify Your Email Address |
| 69 | + |
| 70 | +1. Go to GitHub → Settings → Emails |
| 71 | +2. Ensure the email address used in your GPG key is listed and verified |
| 72 | +3. If not verified, click "Resend verification email" and follow the link |
| 73 | + |
| 74 | +## Step 5: Add Secrets to Repository |
| 75 | + |
| 76 | +Go to your repository → Settings → Secrets and variables → Actions, and add: |
| 77 | + |
| 78 | +### Required Secrets: |
| 79 | + |
| 80 | +1. **GPG_PRIVATE_KEY** |
| 81 | + - Value: Your private key (output from `gpg --armor --export-secret-keys`) |
| 82 | + - This is the entire output including: |
| 83 | + ``` |
| 84 | + -----BEGIN PGP PRIVATE KEY BLOCK----- |
| 85 | + ... |
| 86 | + -----END PGP PRIVATE KEY BLOCK----- |
| 87 | + ``` |
| 88 | +
|
| 89 | +2. **GPG_PASSPHRASE** |
| 90 | + - Value: The passphrase you set when generating the key |
| 91 | +
|
| 92 | +### Optional Secrets (recommended): |
| 93 | +
|
| 94 | +3. **GPG_COMMITTER_NAME** |
| 95 | + - Value: The name to use for commits (e.g., "GhostClass Bot" or your name) |
| 96 | + - If not set, defaults to "GhostClass Bot" |
| 97 | +
|
| 98 | +4. **GPG_COMMITTER_EMAIL** |
| 99 | + - Value: The email address from your GPG key (must be verified in GitHub) |
| 100 | + - If not set, defaults to "61821107+devakesu@users.noreply.github.com" |
| 101 | +
|
| 102 | +## Step 6: Test the Setup |
| 103 | +
|
| 104 | +1. Create a test PR to trigger the auto-version-bump workflow |
| 105 | +2. Check that the version bump commit shows as "Verified" with a green checkmark |
| 106 | +3. Verify the commit is signed with your GPG key |
| 107 | +
|
| 108 | +## Using GitHub's No-Reply Email |
| 109 | +
|
| 110 | +If you want to keep your email private, you can use GitHub's no-reply email: |
| 111 | +
|
| 112 | +1. Go to GitHub → Settings → Emails |
| 113 | +2. Check "Keep my email addresses private" |
| 114 | +3. GitHub will provide you with a no-reply email like: `123456+username@users.noreply.github.com` |
| 115 | +4. Use this email when generating your GPG key |
| 116 | +5. This email is automatically verified |
| 117 | +
|
| 118 | +## Troubleshooting |
| 119 | +
|
| 120 | +### Commits Show as "Unverified" |
| 121 | +
|
| 122 | +- **Cause**: Email address in GPG key doesn't match a verified email in your GitHub account |
| 123 | +- **Solution**: |
| 124 | + 1. Verify the email in GitHub Settings → Emails |
| 125 | + 2. Or generate a new GPG key with a verified email address |
| 126 | +
|
| 127 | +### "No secret key" Error |
| 128 | +
|
| 129 | +- **Cause**: Private key not properly added to repository secrets |
| 130 | +- **Solution**: Ensure you copied the entire private key including headers and footers |
| 131 | +
|
| 132 | +### "Bad passphrase" Error |
| 133 | +
|
| 134 | +- **Cause**: Incorrect passphrase in repository secrets |
| 135 | +- **Solution**: Double-check the GPG_PASSPHRASE secret matches your key's passphrase |
| 136 | +
|
| 137 | +### "Inappropriate ioctl for device" Error |
| 138 | +
|
| 139 | +- **Cause**: GPG trying to prompt for passphrase in non-interactive environment, or using incompatible key type (ECC) |
| 140 | +- **Solution**: |
| 141 | + 1. **Use RSA keys instead of ECC** (recommended) - Generate a new RSA 4096-bit key |
| 142 | + 2. The workflow now automatically configures GPG for non-interactive use with loopback pinentry |
| 143 | + 3. If using ECC keys, consider regenerating with RSA for better CI/CD compatibility |
| 144 | +
|
| 145 | +### Using ECC/EdDSA Keys (Not Recommended) |
| 146 | +
|
| 147 | +If you must use ECC Curve 25519 keys: |
| 148 | +- Be aware of potential compatibility issues in GitHub Actions |
| 149 | +- The "Inappropriate ioctl for device" error is common with ECC keys |
| 150 | +- **Strongly recommend using RSA 4096-bit keys instead** |
| 151 | +
|
| 152 | +## Security Best Practices |
| 153 | +
|
| 154 | +1. **Never share your private key**: Only add it to repository secrets, never commit it |
| 155 | +2. **Use a strong passphrase**: Protect your GPG key with a strong passphrase |
| 156 | +3. **Rotate keys periodically**: Consider setting an expiration date and rotating keys |
| 157 | +4. **Backup your key**: Keep a secure backup of your GPG key |
| 158 | +5. **Use repository secrets**: Never hardcode sensitive information in workflow files |
| 159 | +
|
| 160 | +## Example Configuration |
| 161 | +
|
| 162 | +After setup, your workflow will use: |
| 163 | +
|
| 164 | +```yaml |
| 165 | +- name: Import GPG key (same-repo only) |
| 166 | + uses: crazy-max/ghaction-import-gpg@v6.1.0 |
| 167 | + with: |
| 168 | + gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }} |
| 169 | + passphrase: ${{ secrets.GPG_PASSPHRASE }} |
| 170 | + git_user_signingkey: true |
| 171 | + git_commit_gpgsign: true |
| 172 | + git_config_global: true |
| 173 | + git_committer_name: ${{ secrets.GPG_COMMITTER_NAME || 'GhostClass Bot' }} |
| 174 | + git_committer_email: ${{ secrets.GPG_COMMITTER_EMAIL || '61821107+devakesu@users.noreply.github.com' }} |
| 175 | +``` |
| 176 | + |
| 177 | +## Additional Resources |
| 178 | + |
| 179 | +- [GitHub: Managing commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification) |
| 180 | +- [GitHub: Generating a new GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key) |
| 181 | +- [GitHub: Adding a GPG key to your GitHub account](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account) |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments