go-ethereum/.github/workflows/RELEASE_SIGNING.md

Release Signing Setup

This document explains how release signing is implemented for bera-geth, including PGP signing for binaries and Cosign signing for Docker images.

Overview

The bera-geth release process includes cryptographic signing for all release artifacts:

• Binary releases: Signed with PGP/GPG
• Docker images: Signed with Cosign (keyless signing via OIDC)

Configuration

Prerequisites for Release Managers

PGP Signing Setup

1. Create the LINUX_SIGNING_KEY secret in GitHub:

   # Export your PGP private key
   gpg --export-secret-keys --armor YOUR_KEY_ID > private.key
   
   # Base64 encode it
   cat private.key | base64 -w 0
   
   # Copy the output and add it as the LINUX_SIGNING_KEY secret in GitHub repository settings
   

2. Ensure the public key matches: The public key at .github/workflows/release.asc should correspond to the private key used for signing.

Cosign Setup

Cosign uses keyless signing (no secret required). The workflow uses GitHub's OIDC provider to sign images, which means:

• No private keys to manage
• Signatures are tied to the GitHub Actions workflow identity
• Full transparency via Rekor transparency log

Release Process

Triggering a Release

Releases are triggered by:

• Pushing a tag matching v1.* (e.g., v1.0.0, v1.0.0-rc1)
• The workflow will automatically create a draft release with all signed artifacts

What Gets Signed

1. Binary Archives:

   • bera-geth-linux-amd64-*.tar.gz → bera-geth-linux-amd64-*.tar.gz.asc
   • bera-geth-linux-arm64-*.tar.gz → bera-geth-linux-arm64-*.tar.gz.asc
   • bera-geth-alltools-linux-amd64-*.tar.gz → bera-geth-alltools-linux-amd64-*.tar.gz.asc
   • bera-geth-alltools-linux-arm64-*.tar.gz → bera-geth-alltools-linux-arm64-*.tar.gz.asc

2. Docker Images:

   • Multi-arch images at ghcr.io/berachain/bera-geth:VERSION
   • Signed with Cosign using keyless signing

Verification Instructions

Verifying Binary Signatures

Users can verify the PGP signatures of release binaries:

# Download and import the public key
curl -sSL https://raw.githubusercontent.com/berachain/bera-geth/main/.github/workflows/release.asc | gpg --import

# Download a release archive and its signature
wget https://github.com/berachain/bera-geth/releases/download/v1.0.0/bera-geth-linux-amd64-v1.0.0.tar.gz
wget https://github.com/berachain/bera-geth/releases/download/v1.0.0/bera-geth-linux-amd64-v1.0.0.tar.gz.asc

# Verify the signature
gpg --verify bera-geth-linux-amd64-v1.0.0.tar.gz.asc bera-geth-linux-amd64-v1.0.0.tar.gz

Expected output:

gpg: Signature made [date] using RSA key ID [key-id]
gpg: Good signature from "bera-geth-linux-signing-key"

Verifying Docker Images

Docker images are signed with Cosign and can be verified:

# Install cosign if not already installed
brew install cosign  # macOS
# or see https://docs.sigstore.dev/cosign/installation/

# Verify a specific version
cosign verify ghcr.io/berachain/bera-geth:v1.0.0

# Verify the latest image
cosign verify ghcr.io/berachain/bera-geth:latest

The verification will show:

• The GitHub Actions workflow that created the image
• The commit SHA
• The OIDC issuer (GitHub)

Security Considerations

1. PGP Key Security:

   • The PGP private key should be kept secure and only accessible to authorized release managers
   • Regularly rotate keys and update the public key in the repository
   • Use a strong passphrase for the private key

2. Cosign Keyless Signing:

   • Signatures are tied to the GitHub Actions workflow identity
   • Verification includes checking the workflow that signed the image
   • All signatures are recorded in the Rekor transparency log

3. Best Practices:

   • Always verify signatures before using release artifacts in production
   • Check that the signing workflow matches the official repository
   • Monitor the repository for any changes to signing keys or workflows

Troubleshooting

PGP Signing Issues

If PGP signing fails:

1. Check that the LINUX_SIGNING_KEY secret is properly set
2. Verify the key hasn't expired: gpg --list-secret-keys
3. Ensure the base64 encoding was done correctly

Cosign Signing Issues

If Cosign signing fails:

1. Ensure the workflow has id-token: write permission
2. Check that the Docker image was successfully pushed before signing
3. Verify the image tag/digest is correct

Release Draft Issues

If the release draft fails:

1. Ensure all artifacts were successfully uploaded
2. Check that the tag follows the correct format (v1.*)
3. Verify the workflow has contents: write permission