[![GitHub release](https://img.shields.io/github/release/crazy-max/ghaction-import-gpg.svg?style=flat-square)](https://github.com/crazy-max/ghaction-import-gpg/releases/latest) [![GitHub marketplace](https://img.shields.io/badge/marketplace-import--gpg-blue?logo=github&style=flat-square)](https://github.com/marketplace/actions/import-gpg) [![Test workflow](https://img.shields.io/github/actions/workflow/status/crazy-max/ghaction-import-gpg/test.yml?branch=master&label=test&logo=github&style=flat-square)](https://github.com/crazy-max/ghaction-import-gpg/actions?workflow=test) [![Codecov](https://img.shields.io/codecov/c/github/crazy-max/ghaction-import-gpg?logo=codecov&style=flat-square)](https://codecov.io/gh/crazy-max/ghaction-import-gpg) [![Become a sponsor](https://img.shields.io/badge/sponsor-crazy--max-181717.svg?logo=github&style=flat-square)](https://github.com/sponsors/crazy-max) [![Paypal Donate](https://img.shields.io/badge/donate-paypal-00457c.svg?logo=paypal&style=flat-square)](https://www.paypal.me/crazyws) ## About GitHub Action to easily import a GPG key. ![Import GPG](.github/ghaction-import-gpg.png) ___ * [Features](#features) * [Prerequisites](#prerequisites) * [Usage](#usage) * [Workflow](#workflow) * [Sign commits](#sign-commits) * [Use a subkey](#use-a-subkey) * [Set key's trust level](#set-keys-trust-level) * [Customizing](#customizing) * [inputs](#inputs) * [outputs](#outputs) * [Contributing](#contributing) * [License](#license) ## Features * Works on Linux, macOS and Windows [virtual environments](https://help.github.com/en/articles/virtual-environments-for-github-actions#supported-virtual-environments-and-hardware-resources) * Allow seeding the internal cache of `gpg-agent` with provided passphrase * Signing-only subkeys support * Purge imported GPG key, cache information and kill agent from runner * (Git) Enable signing for Git commits, tags and pushes * (Git) Configure and check committer info against GPG key ## Prerequisites First, [generate a GPG key](https://docs.github.com/en/github/authenticating-to-github/generating-a-new-gpg-key) and export the GPG private key as an ASCII armored version to your clipboard: ```shell # macOS gpg --armor --export-secret-key joe@foo.bar | pbcopy # Ubuntu (assuming GNU base64) gpg --armor --export-secret-key joe@foo.bar -w0 | xclip # Arch gpg --armor --export-secret-key joe@foo.bar | xclip -selection clipboard -i # FreeBSD (assuming BSD base64) gpg --armor --export-secret-key joe@foo.bar | xclip ``` Paste your clipboard as a [`secret`](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) named `GPG_PRIVATE_KEY` for example. Create another secret with the `PASSPHRASE` if applicable. ## Usage ### Workflow ```yaml name: import-gpg on: push: branches: master jobs: import-gpg: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Import GPG key uses: crazy-max/ghaction-import-gpg@v6 with: gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }} passphrase: ${{ secrets.PASSPHRASE }} - name: List keys run: gpg -K ``` ### Sign commits ```yaml name: import-gpg on: push: branches: master jobs: sign-commit: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Import GPG key uses: crazy-max/ghaction-import-gpg@v6 with: gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }} passphrase: ${{ secrets.PASSPHRASE }} git_user_signingkey: true git_commit_gpgsign: true - name: Sign commit and push changes run: | echo foo > bar.txt git add . git commit -S -m "This commit is signed!" git push ``` ### Use a subkey With the input `fingerprint`, you can specify which one of the subkeys in a GPG key you want to use for signing. ```yaml name: import-gpg on: push: branches: master jobs: import-gpg: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Import GPG key uses: crazy-max/ghaction-import-gpg@v6 with: gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }} passphrase: ${{ secrets.PASSPHRASE }} fingerprint: "C17D11ADF199F12A30A0910F1F80449BE0B08CB8" - name: List keys run: gpg -K ``` For example, given this GPG key with a signing subkey: ``` pub ed25519 2021-09-24 [C] 87F257B89CE462100BEC0FFE6071D218380FDCC8 Keygrip = F5C3ABFAAB36B427FD98C4EDD0387E08EA1E8092 uid [ unknown] Joe Bar sub ed25519 2021-09-24 [S] C17D11ADF199F12A30A0910F1F80449BE0B08CB8 Keygrip = DEE0FC98F441519CA5DE5D79773CB29009695FEB ``` You can use the subkey with signing capability whose fingerprint is `C17D11ADF199F12A30A0910F1F80449BE0B08CB8`. ### Set key's trust level With the `trust_level` input, you can specify the trust level of the GPG key. Valid values are: * `1`: unknown * `2`: never * `3`: marginal * `4`: full * `5`: ultimate ```yaml name: import-gpg on: push: branches: master jobs: import-gpg: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Import GPG key uses: crazy-max/ghaction-import-gpg@v6 with: gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }} passphrase: ${{ secrets.PASSPHRASE }} trust_level: 5 ``` ## Customizing ### inputs The following inputs can be used as `step.with` keys | Name | Type | Description | |-----------------------|--------|--------------------------------------------------------------------------------------------| | `gpg_private_key` | String | GPG private key exported as an ASCII armored version or its base64 encoding (**required**) | | `passphrase` | String | Passphrase of the GPG private key | | `trust_level` | String | Set key's trust level | | `git_config_global` | Bool | Set Git config global (default `false`) | | `git_user_signingkey` | Bool | Set GPG signing keyID for this Git repository (default `false`) | | `git_commit_gpgsign` | Bool | Sign all commits automatically. (default `false`) | | `git_tag_gpgsign` | Bool | Sign all tags automatically. (default `false`) | | `git_push_gpgsign` | String | Sign all pushes automatically. (default `if-asked`) | | `git_committer_name` | String | Set commit author's name (defaults to the name associated with the GPG key) | | `git_committer_email` | String | Set commit author's email (defaults to the email address associated with the GPG key) | | `workdir` | String | Working directory (below repository root) (default `.`) | | `fingerprint` | String | Specific fingerprint to use (subkey) | > **Note** > > `git_user_signingkey` needs to be enabled for `git_commit_gpgsign`, `git_tag_gpgsign`, > `git_push_gpgsign`, `git_committer_name`, `git_committer_email` inputs. ### outputs Following outputs are available | Name | Type | Description | |---------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `fingerprint` | String | Fingerprint of the GPG key (recommended as [user ID](https://www.gnupg.org/documentation/manuals/gnupg/Specify-a-User-ID.html)) | | `keyid` | String | Low 64 bits of the X.509 certificate SHA-1 fingerprint | | `name` | String | Primary name associated with the GPG key | | `email` | String | Primary email address associated with the GPG key | | `userids` | String (JSON) | All user ids (including primary) associated with the GPG Key.
The output is a JSON array where each object has a `name` and `email` key. Use [fromJson](https://docs.github.com/en/actions/learn-github-actions/expressions#fromjson) to turn the String back into a JSON array | ## Contributing Want to contribute? Awesome! The most basic way to show your support is to star the project, or to raise issues. You can also support this project by [**becoming a sponsor on GitHub**](https://github.com/sponsors/crazy-max) or by making a [PayPal donation](https://www.paypal.me/crazyws) to ensure this journey continues indefinitely! Thanks again for your support, it is much appreciated! :pray: ## License MIT. See `LICENSE` for more details.