Implement GPG Commit Signing with Seamless Multi-Environment Support

[LTSCommerce]

Overview

Implement GPG commit signing across all development environments (local desktop, LXC containers, Docker containers including Claude YOLO) with full security and minimal hassle.

User Experience Requirements

Security Goals

• ✅ Full cryptographic verification - All commits verifiable on GitHub with "Verified" badge
• ✅ Private key protection - Keys never leave the host system
• ✅ Agent-based authentication - Passphrase entered once, cached securely via gpg-agent
• ✅ No key duplication - Single GPG key on host, forwarded to all containers

Usability Goals

• ✅ Zero manual intervention - After initial setup, signing should be transparent
• ✅ Single passphrase prompt - Enter passphrase once per session (or once per day)
• ✅ Automatic in all environments - Works seamlessly in:
  • Local desktop git operations
  • LXC container development
  • Docker containers (Claude YOLO via ccy)
  • Any future containerized workflows
• ✅ No per-container setup - Containers inherit signing capability automatically
• ✅ Integrated with gnome-keyring - Passphrase cached by GNOME Keyring on host
• ✅ Survives reboot - Configuration persists across system restarts

Target Environments

1. Host (Fedora Desktop) - Primary GPG key storage and gpg-agent
2. LXC Containers - Development containers with full system access
3. Docker Containers - Isolated containers (especially Claude YOLO)
4. Future Containers - Any new containerized development workflows

Implementation Scope

Phase 1: Host Setup

• GPG key generation (RSA 4096 or Ed25519)
• Configure git for automatic commit signing
• Set up gpg-agent with passphrase caching
• Integrate with gnome-keyring for GUI passphrase prompts
• Export public key for GitHub upload (manual step with instructions)

Phase 2: Container Forwarding

• Configure gpg-agent extra-socket for forwarding
• LXC container gpg-agent socket mounting
• Docker container gpg-agent socket mounting (especially Claude YOLO)
• Handle UID/permission mappings between host and containers
• Set required environment variables (GPG_TTY, GNUPGHOME)

Phase 3: Automation

• Ansible playbook for host GPG setup
• Ansible playbook for container configuration
• Update Claude YOLO wrapper to mount GPG socket
• Documentation and troubleshooting guide

Success Criteria

• Can make signed commits on host with single passphrase prompt per session
• LXC containers can make signed commits without passphrase prompts
• Claude YOLO (ccy) can make signed commits without passphrase prompts
• All commits show "Verified" badge on GitHub
• Setup is reproducible via Ansible playbooks
• No keys exist in containers (only on host)
• Passphrase caching works across all environments

Non-Goals

• ❌ Multiple GPG keys per environment
• ❌ Hardware token (YubiKey) support in v1 (future enhancement)
• ❌ Automatic public key upload to GitHub (requires API, manual is fine)

References

• TODO: Add research findings in comments below

[LTSCommerce]

Triage & Complexity Assessment

Complexity: Medium-High
Estimated Implementation Time: 8-12 hours
Testing Time: 4-6 hours across all environments

Complexity Breakdown

Component	Complexity	Risk	Notes
Host GPG setup	Low	Low	Well-documented, standard process
gpg-agent config	Medium	Medium	Socket paths vary by distro, requires testing
Docker forwarding	High	Medium	UID mapping, socket permissions, SELinux
LXC forwarding	Medium	Low	Similar to Docker but simpler permissions
gnome-keyring integration	Low	Low	Already integrated on Fedora
Ansible automation	Medium	Low	Standard playbook patterns

Key Challenges

1. Socket Path Variations - gpg-agent socket location differs:

   • Traditional: ~/.gnupg/S.gpg-agent
   • Modern systemd: /run/user/{UID}/gnupg/S.gpg-agent
   • Need to detect and handle both

2. UID Mapping in Rootless Docker - Host UID must map to container UID correctly for socket permissions

3. SELinux Context - Fedora requires correct SELinux labels on mounted sockets (:Z or :z flag)

4. Environment Variables - Multiple env vars needed:

   • GPG_TTY=$(tty) - Required for terminal-based pinentry
   • GNUPGHOME - Optional, for non-standard key locations
   • Socket paths may need explicit configuration

5. Claude YOLO Integration - Requires modifying the wrapper script to mount GPG socket alongside existing SSH key mounts

Testing Requirements

Must verify in:

• Fresh Fedora desktop (clean slate)
• Existing Fedora desktop (upgrade path)
• LXC container with user account
• LXC container as root
• Claude YOLO Docker container (rootless Docker)
• Passphrase caching after timeout
• Reboot persistence
• Multiple concurrent container sessions

[LTSCommerce]

Research Findings: GPG Agent Forwarding

Core Concepts

gpg-agent Sockets:
GnuPG 2.1+ creates multiple sockets for different purposes:

1. Primary Socket (S.gpg-agent) - Full access to all gpg-agent functions
2. Extra Socket (S.gpg-agent.extra) - Restricted socket designed for forwarding
   • More limited access (no admin functions)
   • Safer for remote/container access
   • Different pinentry messages to indicate remote operation
3. SSH Socket (S.gpg-agent.ssh) - For using GPG keys as SSH keys

The extra socket is specifically designed for container/remote forwarding and should be used instead of the primary socket.

Docker Forwarding Pattern

Basic Approach:

# Find the extra socket location
EXTRA_SOCKET=$(gpgconf --list-dir agent-extra-socket)

# Mount into container
docker run \
  --volume "${EXTRA_SOCKET}:/root/.gnupg/S.gpg-agent:ro" \
  -e "GPG_TTY=$(tty)" \
  your-image

Key Considerations:

• Use :ro (read-only) mount for security
• Socket must be mounted to expected GnuPG directory in container
• Container user must have matching permissions (UID issues)
• For rootless Docker, socket is typically at /run/user/{UID}/gnupg/S.gpg-agent.extra

LXC Forwarding Pattern

LXC Configuration:

# In LXC config file
lxc.mount.entry = /run/user/1000/gnupg/S.gpg-agent.extra run/user/1000/gnupg/S.gpg-agent none bind,create=file 0 0

LXC forwarding is generally simpler than Docker because:

• LXC containers often use same UID as host
• Direct filesystem access makes socket mounting straightforward
• Fewer isolation layers to work through

Permission Handling

UID Mapping Issues:
The most common failure mode is permission denied on the socket due to UID mismatches:

• Host user: UID 1000
• Container user: UID 0 (root) or different UID
• Socket owned by UID 1000 on host

Solutions:

1. Run container with matching UID: docker run --user 1000:1000
2. Use user namespaces in Docker
3. For rootless Docker, UIDs are automatically mapped
4. Create symbolic links inside container if needed

SELinux (Fedora-specific):
When mounting sockets on Fedora, use SELinux context flags:

docker run --volume "${EXTRA_SOCKET}:/root/.gnupg/S.gpg-agent:z"

• :z - Private container mount (for single container)
• :Z - Shared mount (for multiple containers)

Environment Configuration

Required in Container:

export GPG_TTY=$(tty)
# Inside container's .bashrc or entrypoint

Optional but Recommended:

export GNUPGHOME=/root/.gnupg
# Explicitly set GnuPG home directory

Not Needed:

• GPG_AGENT_INFO - Deprecated in GnuPG 2.1+, agent auto-discovered via socket

References

• GnuPG Agent Forwarding Wiki
• Unix StackExchange: Forward gpg-agent to Docker
• ktdreyer Blog: Forwarding gpg-agent to container
• transifex/docker-gpg-agent-forward - Reference implementation

[LTSCommerce]

Proposed Implementation Approach

Phase 1: Host GPG Setup (Ansible Playbook)

File: playbooks/imports/optional/common/play-gpg-commit-signing.yml

---
- hosts: desktop
  name: GPG Commit Signing Setup
  become: false
  tasks:
    - name: Install GPG and Pinentry Packages
      become: true
      dnf:
        name:
          - gnupg2
          - gnupg2-smime
          - pinentry-gnome3  # GUI passphrase prompt
        state: present

    - name: Configure gpg-agent for Passphrase Caching
      blockinfile:
        path: ~/.gnupg/gpg-agent.conf
        create: true
        mode: '0600'
        marker: "# {mark} ANSIBLE MANAGED: Agent Configuration"
        block: |
          # Cache passphrase for 8 hours
          default-cache-ttl 28800
          max-cache-ttl 28800
          
          # Use GNOME pinentry for GUI prompts
          pinentry-program /usr/bin/pinentry-gnome3
          
          # Enable extra socket for container forwarding
          extra-socket {{ lookup('env', 'XDG_RUNTIME_DIR') }}/gnupg/S.gpg-agent.extra

    - name: Reload gpg-agent with New Configuration
      shell: |
        gpgconf --kill gpg-agent
        gpgconf --launch gpg-agent
      changed_when: false

    - name: Configure Git for Automatic Commit Signing
      shell: |
        git config --global commit.gpgsign true
        git config --global gpg.program gpg2

    - name: Check for Existing GPG Key
      shell: gpg --list-secret-keys --keyid-format LONG
      register: existing_keys
      changed_when: false
      failed_when: false

    - name: Display GPG Key Instructions
      debug:
        msg:
          - "════════════════════════════════════════════════════════"
          - "GPG Key Setup"
          - "════════════════════════════════════════════════════════"
          - ""
          - "{% if existing_keys.stdout %}✓ Existing GPG key(s) found:{% else %}⚠ No GPG key found. Generate one with:{% endif %}"
          - "  {{ existing_keys.stdout if existing_keys.stdout else 'gpg --full-generate-key' }}"
          - ""
          - "{% if not existing_keys.stdout %}Recommended settings:"
          - "  • Type: RSA and RSA"
          - "  • Key size: 4096 bits"
          - "  • Expiration: 2 years (renew before expiry)"
          - "  • Real name: {{ user_name }}"
          - "  • Email: {{ user_email }}"
          - ""
          - "After generating, configure git with your key ID:"
          - "  gpg --list-secret-keys --keyid-format LONG"
          - "  git config --global user.signingkey <KEY_ID>"
          - ""
          - "{% endif %}Upload public key to GitHub:"
          - "  gpg --armor --export <KEY_ID> | xclip -selection clipboard"
          - "  Then paste at: https://github.com/settings/keys"
          - ""
          - "Test signing:"
          - "  echo 'test' | gpg --clearsign"
          - ""

Phase 2: Docker Container Support (Claude YOLO)

Modify: /workspace/files/var/local/claude-yolo/claude-yolo

Add GPG socket mounting to the Docker run command:

# After line 291 (where SSH mounts are configured)

# Build GPG socket mount arguments
GPG_MOUNTS=()
GPG_EXTRA_SOCKET=$(gpgconf --list-dir agent-extra-socket 2>/dev/null || echo "")

if [ -n "$GPG_EXTRA_SOCKET" ] && [ -S "$GPG_EXTRA_SOCKET" ]; then
    # Mount GPG extra socket for commit signing
    # Use :z for SELinux private container label
    GPG_MOUNTS+=("-v" "${GPG_EXTRA_SOCKET}:/root/.gnupg/S.gpg-agent:z")
    echo "✓ GPG agent forwarding enabled (commit signing available)"
else
    echo "⚠ GPG agent extra socket not found - commit signing unavailable"
    echo "  Run: ansible-playbook playbooks/imports/optional/common/play-gpg-commit-signing.yml"
fi

# Then in the docker run command (line 396), add:
    "${GPG_MOUNTS[@]}" \
    -e "GPG_TTY=/dev/console" \

Modify: /workspace/files/var/local/claude-yolo/entrypoint.sh

Add GPG_TTY setup in the entrypoint:

# After copying config files
export GPG_TTY=$(tty)

Phase 3: LXC Container Support

Add to: playbooks/imports/play-lxc-install-config.yml

- name: Configure GPG Agent Forwarding in LXC Containers
  blockinfile:
    path: /etc/lxc/default.conf
    marker: "# {mark} ANSIBLE MANAGED: GPG Agent Forwarding"
    block: |
      # Forward GPG agent socket for commit signing
      lxc.mount.entry = /run/user/{{ lookup('env', 'SUDO_UID') | default(ansible_user_uid) }}/gnupg/S.gpg-agent.extra run/user/1000/gnupg/S.gpg-agent none bind,create=file 0 0
  become: true
  tags:
    - lxc
    - gpg

- name: Set GPG_TTY in Container Profile
  blockinfile:
    path: /etc/profile.d/gpg-tty.sh
    create: true
    mode: '0644'
    marker: "# {mark} ANSIBLE MANAGED: GPG TTY"
    block: |
      export GPG_TTY=$(tty)
  become: true
  tags:
    - lxc
    - gpg

Phase 4: Validation Playbook

File: playbooks/imports/optional/common/play-gpg-verify.yml

---
- hosts: desktop
  name: Verify GPG Commit Signing Configuration
  become: false
  tasks:
    - name: Check GPG Key Exists
      shell: gpg --list-secret-keys --keyid-format LONG
      register: gpg_keys
      changed_when: false
      failed_when: gpg_keys.rc != 0

    - name: Check Git GPG Configuration
      shell: |
        git config --global commit.gpgsign
        git config --global user.signingkey
      register: git_gpg_config
      changed_when: false
      failed_when: false

    - name: Test GPG Signing
      shell: echo "test" | gpg --clearsign
      register: gpg_test
      changed_when: false
      failed_when: gpg_test.rc != 0

    - name: Check GPG Extra Socket
      stat:
        path: "{{ lookup('env', 'XDG_RUNTIME_DIR') }}/gnupg/S.gpg-agent.extra"
      register: extra_socket

    - name: Display Verification Results
      debug:
        msg:
          - "════════════════════════════════════════════════════════"
          - "GPG Commit Signing Verification"
          - "════════════════════════════════════════════════════════"
          - ""
          - "✓ GPG keys found: {{ 'YES' if gpg_keys.rc == 0 else 'NO' }}"
          - "✓ Git signing enabled: {{ 'YES' if 'true' in git_gpg_config.stdout else 'NO' }}"
          - "✓ Git signing key set: {{ 'YES' if git_gpg_config.stdout_lines | length > 1 else 'NO' }}"
          - "✓ GPG agent working: {{ 'YES' if gpg_test.rc == 0 else 'NO' }}"
          - "✓ Extra socket exists: {{ 'YES' if extra_socket.stat.exists else 'NO' }}"
          - ""
          - "{% if extra_socket.stat.exists %}Ready for container forwarding!{% else %}⚠ Extra socket not configured{% endif %}"

Alternative: SSH-based Commit Signing

Modern Alternative to GPG:

Git 2.34+ supports SSH key signing as an alternative to GPG:

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

Pros:

• Simpler setup (no GPG key generation)
• Uses existing SSH keys
• SSH agent forwarding already solved problem
• GitHub supports SSH signature verification

Cons:

• Requires Git 2.34+ (Fedora has this)
• Less mature ecosystem than GPG
• Some tools may not recognize SSH signatures

Recommendation: Research SSH signing as potential Phase 5 alternative or replacement.

Implementation Priority

1. P0 (Must Have): Host GPG setup playbook
2. P0 (Must Have): Claude YOLO Docker integration
3. P1 (Should Have): LXC container support
4. P2 (Nice to Have): Validation playbook
5. P3 (Future): SSH signing as alternative option

[LTSCommerce]

Additional Research: SSH Commit Signing (Simpler Alternative?)

Overview

Git 2.34+ (released November 2021) added support for SSH-based commit signing. This could be significantly simpler than GPG since:

1. SSH agent forwarding is already solved in this project
2. No separate key management - reuse existing SSH keys
3. GitHub supports it - Signatures show as "Verified" just like GPG
4. Already have SSH keys set up - github_* keys from play-github-cli-multi.yml

Current SSH Infrastructure in Project

The project already has robust SSH key management:

# From claude-yolo script (line 114-179)
GITHUB_KEYS=($(find "$HOME/.ssh" -type f -name "github_*" ! -name "*.pub"))

SSH keys are:

• ✅ Already generated and managed
• ✅ Already forwarded to Docker containers (Claude YOLO lines 295-296)
• ✅ Already authenticated with GitHub
• ✅ Already have interactive selection UX

SSH Signing Setup

On Host:

# Use existing SSH key for signing
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/github_primary.pub
git config --global commit.gpgsign true

# Optional: Set allowed signers file for verification
git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers

# Create allowed signers file
echo "$(git config user.email) $(cat ~/.ssh/github_primary.pub)" >> ~/.ssh/allowed_signers

In Containers:

• SSH agent forwarding already mounts socket
• Git configs are already copied (claude-yolo line 279-281)
• Just need to ensure gpg.format=ssh is set

Comparison: GPG vs SSH Signing

Aspect	GPG Signing	SSH Signing
Setup Complexity	High (key gen, gpg-agent, pinentry)	Low (reuse SSH keys)
Agent Forwarding	New (gpg-agent extra socket)	Done (SSH agent)
Key Management	Separate GPG keys	Reuse SSH keys
Passphrase Caching	gpg-agent + gnome-keyring	ssh-agent (already working)
GitHub Support	Full support	Full support (since 2022)
Verification	gpg --verify	ssh-keygen -Y verify
Ecosystem Maturity	Mature (decades old)	Newer (2021+)
Container Integration	Medium effort	Minimal effort

SSH Signing Advantages for This Project

1. Zero new infrastructure - SSH agent already forwarded to Claude YOLO
2. No socket mounting needed - SSH_AUTH_SOCK already available
3. No UID/permission issues - SSH agent forwarding already handles this
4. One less daemon - No gpg-agent needed
5. Consistent key story - Same keys for push and sign
6. Already tested - SSH forwarding proven working in project

Implementation Complexity Comparison

GPG Implementation: ~8-12 hours

• Host GPG setup: 2 hours
• gpg-agent configuration: 2 hours
• Docker socket mounting: 3 hours
• LXC integration: 2 hours
• Testing & debugging: 3-5 hours

SSH Implementation: ~2-4 hours

• Git config changes: 1 hour
• Container git config sync: 1 hour
• Testing: 1-2 hours

Potential Concerns with SSH Signing

1. Newer technology - Less battle-tested than GPG (but 3+ years old now)
2. Tool support - Some Git tools may not recognize SSH signatures yet
3. Key rotation - If you rotate SSH keys, old commits become unverifiable (same issue with GPG though)
4. Allowed signers file - Need to maintain mapping of emails to SSH keys for verification

Recommendation

Propose two-phase approach:

Phase 1: SSH Signing (Quick Win)

• Implement SSH-based signing first
• Leverage existing SSH infrastructure
• Get "Verified" badges on commits quickly
• Low risk, high value

Phase 2: GPG Signing (Optional Enhancement)

• Add GPG support as optional alternative
• For users who prefer GPG ecosystem
• For scenarios where SSH signing isn't sufficient

Or offer both as optional playbooks:

• play-commit-signing-ssh.yml (recommended, simple)
• play-commit-signing-gpg.yml (advanced, comprehensive)

Required Research

Before committing to SSH signing:

• Verify Fedora's Git version supports SSH signing (git --version >= 2.34)
• Test SSH signing with existing github_* keys
• Verify Claude YOLO container has Git 2.34+
• Test signature verification on GitHub
• Check if any development tools in the stack have issues with SSH signatures

References

• GitHub: SSH Commit Verification
• Git 2.34 Release Notes
• SSH Signing Guide

[LTSCommerce]

Known Pitfalls & Edge Cases

Common Failure Modes

1. Socket Permission Issues

Symptom: gpg: signing failed: Inappropriate ioctl for device

Causes:

• Socket mounted with wrong permissions
• UID mismatch between host and container
• SELinux blocking socket access

Solutions:

# Check socket permissions
ls -l $(gpgconf --list-dir agent-extra-socket)

# Verify SELinux context
ls -Z $(gpgconf --list-dir agent-extra-socket)

# Test in container
docker run -it --rm -v "$(gpgconf --list-dir agent-extra-socket):/root/.gnupg/S.gpg-agent:z" fedora:latest bash

2. TTY Not Set

Symptom: gpg: signing failed: No such device or address

Cause: GPG_TTY environment variable not set

Solution:

export GPG_TTY=$(tty)
# Add to container entrypoint or .bashrc

3. Agent Not Running

Symptom: gpg: can't connect to the agent: IPC connect call failed

Causes:

• gpg-agent not started on host
• Socket not created yet

Solutions:

# Start agent
gpgconf --launch gpg-agent

# Check agent status
gpg-connect-agent /bye

# Verify extra socket exists
test -S $(gpgconf --list-dir agent-extra-socket) && echo "Socket exists"

4. Passphrase Prompt in Container

Symptom: Pinentry tries to open GUI in container (fails)

Causes:

• DISPLAY not set or not forwarded
• Using wrong pinentry program

Solutions:

# In container, use terminal pinentry
export GPG_TTY=$(tty)

# Or configure agent to use curses pinentry for containers
echo "pinentry-program /usr/bin/pinentry-curses" >> ~/.gnupg/gpg-agent.conf

5. Multiple Concurrent Containers

Symptom: Passphrase prompt in wrong container or session

Cause: gpg-agent can only show one pinentry at a time

Solutions:

• Use longer cache times (default-cache-ttl 28800)
• Enter passphrase before starting multiple containers
• Consider passwordless key for automated environments (security tradeoff)

Environment-Specific Issues

Rootless Docker on Fedora

Issue: Socket paths include UID

• Host: /run/user/1000/gnupg/S.gpg-agent.extra
• Container: Must map to /run/user/0/gnupg/S.gpg-agent or ~/.gnupg/S.gpg-agent

Solution: Mount to container's expected location, not host's path

LXC Unprivileged Containers

Issue: UID namespace mapping

• Host UID 1000 → Container UID 100000

Solution: Use privileged containers for development, or configure subuid/subgid mapping

Systemd Socket Activation

Issue: gpg-agent started by systemd may not create extra socket

Solution: Explicitly configure extra-socket in gpg-agent.conf

Testing Checklist

Before marking implementation complete, verify:

# Host: Can sign commits
cd /tmp && git init test && cd test
git commit --allow-empty -m "test" && git verify-commit HEAD

# LXC: Can sign commits  
lxc-attach -n container -- su - user -c 'cd /tmp && git init test && cd test && git commit --allow-empty -m "test"'

# Docker: Can sign commits
docker run --rm -v "$(gpgconf --list-dir agent-extra-socket):/root/.gnupg/S.gpg-agent:z" -e GPG_TTY=/dev/console -v /tmp/test:/test fedora:latest bash -c 'cd /test && git commit --allow-empty -m "test"'

# Claude YOLO: Can sign commits
cd /tmp/test && ccy "make an empty commit"

# Passphrase caching: Only prompted once
# Make commits in multiple environments without re-entering passphrase

# Reboot: Configuration persists
sudo reboot
# After reboot, verify signing still works

Rollback Plan

If GPG signing causes issues:

1. Disable signing globally:

   git config --global --unset commit.gpgsign

2. Per-repo override:

   # In problematic repo
   git config commit.gpgsign false

3. Remove configuration:

   rm ~/.gnupg/gpg-agent.conf
   gpgconf --kill gpg-agent

4. Container isolation: Containers without mounted socket continue working normally

Security Considerations

Private Key Protection:

• ✅ Keys never leave host (only socket forwarded)
• ✅ Extra socket has restricted permissions
• ⚠️ Compromised container could sign commits (but not export keys)

Passphrase Caching:

• ✅ Cached in memory only (gpg-agent)
• ✅ Cleared after timeout or logout
• ⚠️ Long cache times increase risk if session compromised

Container Isolation:

• ✅ Read-only socket mount (:ro or :z)
• ✅ No write access to GPG home directory
• ⚠️ Container can sign arbitrary commits while socket mounted

Recommendations:

1. Use reasonable cache timeout (8 hours, not unlimited)
2. Lock screen when away from desk (passphrase required to unlock)
3. Don't mount GPG socket to untrusted containers
4. Consider separate signing key vs. encryption key

Documentation Requirements

When implemented, document:

1. User guide: How to use commit signing
2. Setup guide: Running the Ansible playbook
3. Troubleshooting: Common issues and solutions
4. Key management: Generating, backing up, rotating keys
5. GitHub integration: Uploading public key
6. Container usage: How signing works in containers
7. Security model: What protection this provides