https://github.com/purpleclay/gpg-import
Import and configure GPG signing for git
https://github.com/purpleclay/gpg-import
ci git gpg gpg-import rust signing
Last synced: 26 days ago
JSON representation
Import and configure GPG signing for git
- Host: GitHub
- URL: https://github.com/purpleclay/gpg-import
- Owner: purpleclay
- License: mit
- Created: 2023-05-19T04:33:44.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2026-05-28T07:15:14.000Z (30 days ago)
- Last Synced: 2026-05-28T08:18:00.654Z (30 days ago)
- Topics: ci, git, gpg, gpg-import, rust, signing
- Language: Rust
- Homepage:
- Size: 298 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# GPG Import
[](LICENSE)
Import and configure GPG signing for git. Runs on Linux and MacOS.
## Features
- Import GPG keys in ASCII armored format (_optionally base64 encoded for CI environments_).
- Configure local or global git signing settings.
- Preset GPG agent passphrase for non-interactive signing.
- Set key trust level.
- Select a specific key or subkey for signing via fingerprint.
- Override committer identity independently from the GPG key.
- Dry-run mode to preview changes without applying them.
## Install
To install the latest version using a bash script:
```sh
sh -c "$(curl https://raw.githubusercontent.com/purpleclay/gpg-import/main/scripts/install)"
```
Download a specific version using the `-v` flag. The script uses `sudo` by default but can be disabled through the `--no-sudo` flag. You can also provide a different installation directory from the default `/usr/local/bin` by using the `-d` flag:
```sh
sh -c "$(curl https://raw.githubusercontent.com/purpleclay/gpg-import/main/scripts/install)" \
-- -v 0.3.0 --no-sudo -d ./bin
```
## Run with Nix
If you have nix installed, you can run the binary directly from the GitHub repository:
```sh
nix run github:purpleclay/gpg-import -- --help
```
## Prerequisites
[Generate](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key) a GPG key and export it as an ASCII armored private key:
```sh
gpg --armor --export-secret-key batman@dc.com
```
For CI environments that don't handle multiline secrets well, you can base64 encode the key:
```sh
gpg --armor --export-secret-key batman@dc.com | base64
```
## Quick Start
Set the `GPG_PRIVATE_KEY` environment variable (and optionally `GPG_PASSPHRASE`), then run:
```sh
$ gpg-import
> Detected GnuPG:
version: 2.4.5 (libgcrypt: 1.10.3)
homedir: /root/.gnupg
> Imported GPG key:
user: batman
fingerprint: 85E1AA4D4F9FE316A8F452DDEF48BE1DFBFA8BA5
keygrip: 99A0B6DD933CC25D0DC8D36299B4F51A9E3DD8C9
key_id: EF48BE1DFBFA8BA5
created_on: Wed, 11 Jun 2025 04:36:06 +0000
expires_on: Thu, 11 Jun 2026 04:36:06 +0000 (in 364 days)
sub_keygrip: A6780D53C3236724F960FD8AC07848F38C66CF48
sub_key_id: 008183F9F50359D1
sub_created_on: Wed, 11 Jun 2025 04:36:06 +0000
sub_expires_on: Fri, 11 Jul 2025 04:36:59 +0000 (in 29 days)
> Setting Passphrase:
keygrip: 99A0B6DD933CC25D0DC8D36299B4F51A9E3DD8C9 [EF48BE1DFBFA8BA5]
keygrip: A6780D53C3236724F960FD8AC07848F38C66CF48 [008183F9F50359D1]
> Setting Trust Level:
trust_level: 5 [EF48BE1DFBFA8BA5]
> Git config set (local):
user.name: batman
user.email: batman@dc.com
user.signingKey: AE799E2DEB4AFE11
commit.gpgsign: true
tag.gpgsign: true
push.gpgsign: if-asked
```
## Configuration
All options can be set via CLI flags or environment variables:
| Flag | Environment Variable | Description |
| ----------------------- | ------------------------- | ---------------------------------------------------------- |
| `-k, --key` | `GPG_PRIVATE_KEY` | GPG private key (use `-` for stdin or `@path` for file) |
| `-p, --passphrase` | `GPG_PASSPHRASE` | Passphrase for the GPG key |
| `-f, --fingerprint` | `GPG_FINGERPRINT` | Fingerprint of a specific key or subkey to use for signing |
| `-t, --trust-level` | `GPG_TRUST_LEVEL` | Trust level for the key (1-5) |
| `-s, --skip-git` | `GPG_SKIP_GIT` | Skip git configuration |
| `--git-global-config` | `GPG_GIT_GLOBAL_CONFIG` | Apply git config globally instead of locally |
| `--git-committer-name` | `GPG_GIT_COMMITTER_NAME` | Override committer name |
| `--git-committer-email` | `GPG_GIT_COMMITTER_EMAIL` | Override committer email |
| `--dry-run` | `GPG_DRY_RUN` | Preview changes without applying them |
### Trust Levels
| Level | Description |
| ----- | ------------------------- |
| 1 | I don't know or won't say |
| 2 | I do NOT trust |
| 3 | I trust marginally |
| 4 | I trust fully |
| 5 | I trust ultimately |
## Examples
### Basic import with passphrase
```sh
gpg-import --key "$GPG_PRIVATE_KEY" --passphrase "$GPG_PASSPHRASE"
```
### Import from stdin
Pipe a key directly from GPG:
```sh
gpg --armor --export-secret-key batman@dc.com | gpg-import --key -
```
### Import from file
Read a key from a file:
```sh
gpg-import --key @/path/to/private.key
```
### Global git configuration
Apply signing configuration to your global git config instead of the local repository:
```sh
gpg-import --key "$GPG_PRIVATE_KEY" --git-global-config
```
### Using a specific subkey
Select a specific subkey for signing by its fingerprint:
```sh
gpg-import --key "$GPG_PRIVATE_KEY" --fingerprint "A6780D53C3236724F960FD8AC07848F38C66CF48"
```
### Override committer identity
Use a different committer identity than the one in the GPG key:
```sh
gpg-import --key "$GPG_PRIVATE_KEY" \
--git-committer-name "Bruce Wayne" \
--git-committer-email "bruce@wayne.enterprises"
```
### Dry run
Preview what would happen without making any changes:
```sh
gpg-import --key "$GPG_PRIVATE_KEY" --dry-run
```