External GPG Agent


In order to use a GPG key that has a passphrase, an external gpg-agent must be running and seeded with your passphrase. This feature is enabled with the following configuration directive in /etc/packagecloud/packagecloud.rb:

packagecloud_gpg['use_external_agent'] = true


  • gpg-agent 2.0.x
  • gpg-connect-agent (might be a separate package for your system)


1) Start gpg-agent

gpg-agent --homedir /etc/packagecloud/gpgkey --allow-preset-passphrase --max-cache-ttl 31622400 --daemon --sh --write-env-file /etc/packagecloud/gpgkey/gpg_socket.env

The --write-env-file argument writes the gpg-agent's socket information into a file (henceforth referred to as the 'socket environment file') and it is how the application can locate and communicate with the gpg-agent. The example command above uses the default packagecloud_gpg['key_directory'] of "/etc/packagecloud/gpgkey".  The application will look for a `gpg_socket.env` file inside of the configured packagecloud_gpg['key_directory'].

2) Seeding the agent with your passphrase

Once the gpg-agent is running, you can set your passphrase by issuing the PRESET_PASSPHRASE instruction to gpg-agent using the gpg-connect-agent command. This instruction takes the full key fingerprint and a hexencoded passphrase as arguments. For example:

echo "PRESET_PASSPHRASE $GPG_FINGERPRINT -1 $GPG_PASSPHRASE_HEX" | gpg-connect-agent --homedir /etc/packagecloud/gpgkey

Where the variables $GPG_FINGERPRINT and $GPG_PASSPHRASE_HEX are set to the full fingerprint (without colons) and the hexencoded passphrase, respectively. Example implementations using the Bash shell are provided below:

2.1) Getting the $GPG_FINGERPRINT
GPG_FINGERPRINT=`gpg --homedir /etc/packagecloud/gpgkey --fingerprint user@email.com | grep fingerprint | awk -F= '{print $2}' | sed -e 's/[[:blank:]]//g'`
env | grep GPG
2.2) Getting the $GPG_PASSPHRASE_HEX
GPG_PASSPHRASE_HEX=`cat /path/to/passphrase | tr -d '\n' | hexdump -v -e '/1 "%02X"'`


Once enabled, the application will rely solely on gpg-agent running in order to sign repository metadata, so it's important that it is always available, and restarted in the event that it stops working. Otherwise repository updates might stop working unexpectedly.

Max Cache TTL

After you seed your passphrase, it will eventually expire according to the max-cache-ttl setting used when starting up the agent. If this is desired, you'll need to use a periodic process, like a cron job to continually reseed the passphrase before it expires, or alternatively, you can set it to a year (31622400 seconds).

Common Errors

When using the Indexer Status area, you might see recently failed jobs with the following errors:

ErrorDescriptionTroubleshooting Tips
NoSocketEnvironmentFileThe socket environment file cannot be located.

Is the --write-env-file option being used correctly?

SocketEnvironmentFileUnreadableThe socket environment file is unreadable.Are the permissions of the socket environment file readable by the packagecloud user?
CannotParseSocketEnvironmentFileThe socket file is malformed and cannot be parsed.Contact support@packagecloud.io with the contents of the socket environment file.