Guide: Encrypted .netrc file with GPG for Gitea access instead of SSH

Encrypted .netrc file with GPG for Gitea access

A Gitea Installation with Docker requires a workaround if you are authenticating with SSH. While it’s not difficult per se, I am documenting an alternative method in this post. It is based on this tutorial.


Simply put, a ~/.netrc file enables you to authenticate with Gitea via HTTPS using a password or access token. Just create one in your home directory, and Git requests should automatically be authenticated.

machine <>
login <user>
password <password or access token>
protocol https
chmod 600 ~/.netrc


As the Git credentials are stored in plain text, we can use GPG to encrypt it. Generate a GPG key if one doesn’t exist. Make sure to put a passphrase on that key.

gpg --gen-key

Encrypt the ~/.netrc file and delete it afterwards. We just need the encrypted ~/.netrc.gpg file.

gpg -e -r ~/.netrc
rm ~/.netrc

Credential helper

Git needs a .netrc credential helper to decrypt ~/.netrc.gpg on the fly. I put it under /usr/bin, but it should also work in other locations.

curl -s '' > /usr/bin/git-credential-netrc
chmod 755 /usr/bin/git-credential-netrc

Finally, set up Git to use the helper:

git config --global credential.helper "/usr/bin/git-credential-netrc -f ~/.netrc.gpg -v"

That’s it! You should be able to authenticate to Gitea using just your GPG key.

Using GPG Agents

To avoid typing in your GPG key every time you make a request, you can use an agent. (I haven’t tested this part because my system uses another key ring.)

Install gpg-agent

sudo apt-get install gnupg-agent

Add to ~/.profile:

export GPG_TTY=`tty`

Security implications

GPG is considered robust in terms of cryptographic security. Moreover, the credential helper is not deprecated. However, please review this method and use it at your risk.

Please note that this method is just for accessing Gitea. It has nothing to do with signing commits.

Update: If you use gnome-keyring, adding pinentry-program /usr/bin/pinentry-gnome3 to ~/.gnupg/gpg-agent.conf is all you have to do to save the gnupg passphrase.