gpg --detach-sign: Detached Signatures for Artifacts

gpg --detach-sign (-b) produces a standalone signature file that travels alongside the artifact.

Release artifacts are signed with a detached signature so the file itself stays untouched. The .asc or .sig sits next to it and verifiers check both together.

What it does

gpg --detach-sign creates a signature in a separate file rather than wrapping the data. The original artifact is unchanged; the signature (.sig binary, or .asc with --armor) is distributed next to it and checked with gpg --verify.

Common usage

Terminal

# binary detached signature -> file.tar.gz.sig
gpg --detach-sign file.tar.gz
# armored detached signature -> file.tar.gz.asc, non-interactive
gpg --batch --yes --pinentry-mode loopback \
  --passphrase "$GPG_PASSPHRASE" \
  --local-user you@example.com \
  --armor --detach-sign file.tar.gz

Options

Flag	What it does
--detach-sign / -b	Write a detached signature file
--armor / -a	ASCII-armor the signature (.asc instead of .sig)
--local-user <id> / -u	Choose which secret key signs
--output <file> / -o	Name the signature file explicitly
--pinentry-mode loopback	Take the passphrase from the command, not a prompt

In CI

Signing needs the passphrase but there is no terminal, so combine --batch, --pinentry-mode loopback, and --passphrase (or --passphrase-fd 0). Pick the key with --local-user when more than one secret key is present. Set GPG_TTY only matters for interactive use; in CI loopback is the reliable path.

Common errors in CI

"gpg: signing failed: Inappropriate ioctl for device" means gpg tried to prompt for the passphrase with no TTY; add --pinentry-mode loopback and supply --passphrase or --passphrase-fd. "gpg: no default secret key" means no signing key is set; pass --local-user or set default-key. "gpg: signing failed: No secret key" means only the public key was imported.