Safely store secrets in Git using Blackbox

Written by Ulises Gascón

Feb 06, 20235 min read

Storing secrets in a Git repository can be a dangerous proposition, as the information is often stored in plaintext and can be seen by anyone with access to the repository. It's important to remember that secrets should never be stored in plaintext and that measures should be taken to ensure that the secrets are encrypted and secure.

In this post, I will explain how to use Blackbox to safely store secrets within a Git repository as well as provide examples of how to use it in GitHub Actions as a secret repository to quickly load secrets into your pipelines.

Blackbox in a nutshell

Most developers understand the importance of keeping secrets safe and secure. Unfortunately, it can be difficult to achieve this when dealing with secrets that are stored in a Git repository. Fortunately, Blackbox is a great tool for securely storing secrets within Git. It helps streamline the process of working with secrets while ensuring the highest level of security possible. With its easy-to-use PGP encryption and automated processes, Blackbox ensures developers have a safe and efficient way of managing their secrets.


In mac the best way is to use Brew, so you should have Brew installed in your machine, in the first place.

Then, with this command, install Blackbox:

brew install blackbox

In case that you are using a different platform please check the official documentation.

Usage / How to

Initialize the project


Add users

♦️ Note: you need to have the user's pgp public key in your pgp keychain and you MUST be an ADMIN to run this command (you can't add yourself unless you are the first user in the project)

# Add the new key to the project
blackbox_addadmin {email}
# Re-encrypt the files including the new user

Remove users

# Remove the user from the project
blackbox_removeadmin {email}
# Re-encrypt the files without the previous key

Add a new file

By default, Backbox won't encrypt the new files, so you need to add them manually by using blackbox_register_new_file once your changes are done.

# Create the file
touch secrets/demo_file.txt
# ... do your things in the file...
# Encrypt the file
blackbox_register_new_file secrets/demo_file.txt

♦️ Note: when you encrypt the file, the file is renamed with a .gpg like secrets/demo_file.txt.gpg extension. Now the content is not legible (encrypted). When the file is encrypted, you are ready to commit the changes over that file :-)

Edit a file

You need to decrypt the file first and then re-encrypt the file at the end.

# Decrypt the file
blackbox_decrypt_file secrets/demo_file.txt
# ... make your changes in the file...
# Re-encrypt the file
blackbox_edit_end secrets/demo_file.txt

Once the file is decrypted, it will appear as a new file with the same name without the .pgp extension. The file now looks like this secrets/demo_file.txt and the content is in clear text (decrypted).

You can perform all the changes you want and then encrypt the file again when you are done. Then the plain file will be automatically removed and the encrypted file updated.

Delete a file

Use the command blackbox_deregister_file <file>. Afterwards, is very important to run the command blackbox_shred_all_files in order to remove decrypted files that could still exist in your machine. (Be aware: there is no typo in the command, the 'a' letter is NOT missed from the shred word).

Decrypt all files

If you need to perform changes in several files, the easiest way is to decrypt all the files at once:


Afterwards, when you're done, please manually encrypt all the files, one by one, with the command blackbox_edit_end secrets/{file_name}. There is no option to batch that process yet in Blackbox, but there is a discussion ongoing about it.

Check the differences between a clear file and a encrypted file:

blackbox_diff secrets/demo_file.txt

Using Blackbox in GitHub Actions

One of the coolest features is that you can use pgp to decrypt secrets in any CI process, this is a simple example that

  • Load the PGP keys in the machine
  • Clone the secret management repository using a github token
  • Decrypt one file and store it as .env
  • Source the .env file to the npm run build process.
name: Pull Request Check

on: [pull_request]

    runs-on: ubuntu-latest

      - uses: actions/[email protected]

      - name: Ensure Node Version
        uses: actions/setup-[email protected]

      - name: import GPG key
          GPG_KEY: ${{ secrets.GPG_KEY }}
        run: |
          echo $GPG_KEY | base64 --decode > signature.asc
          gpg --batch --import signature.asc
      - name: Clone secrets-management
          GH_EXTENDED_TOKEN: ${{ secrets.GH_EXTENDED_TOKEN }}
        run: git clone https://${GH_EXTENDED_TOKEN}:x-oauth-[email protected]/UlisesGascon/super-secrets-management.git

      - name: decrypt secrets (local environment)
          BRANCH: ${{ steps.vars.outputs.short_ref }}
          GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
        run: gpg --no-tty --batch --passphrase "$GPG_PASSPHRASE" --pinentry-mode loopback --output .env --decrypt super-secrets-management/secrets/app/.env.gpg

      - name: Install dependencies
        run: npm ci

      - name: Build the project
        run: |
          source .env
          npm run build

      #... MORE STEPS


Blackbox is a great tool for securely storing secrets within a Git repository. It provides an easy-to-use PGP encryption system, which ensures that secrets are kept safe and secure. Furthermore, Blackbox can also be used in GitHub Actions as a secret repository, allowing developers to quickly load secrets into their pipelines. With its robust security and automated processes, Blackbox is an excellent tool for securely storing secrets within Git.