Content only available in english

How to add, update and remove encrypted files

This guide assumes SOPS and age are already set up on your machine. If not, follow How to set up SOPS with age keys first. For what happens to these files on the server, see How encrypted files work across the deployment lifecycle.

Add a new encrypted file

Open SOPS on the new filename directly — SOPS will create the file if it does not exist:

sops integrationm/services/com.cultofbits.web.integration.properties.enc

Write the content in the editor and save. SOPS encrypts using the rules defined in .sops.yaml and writes integrationm/services/com.cultofbits.web.integration.properties.enc. Commit and deploy as usual:

git add integrationm/services/com.cultofbits.web.integration.properties.enc
git commit

On the next cob-cli deploy, the .enc file is transferred to the server and decrypted automatically. The server will have both integrationm/services/com.cultofbits.web.integration.properties.enc and integrationm/services/com.cultofbits.web.integration.properties in the live directory.

Convert an existing cleartext file

If a file is already in the repository and on the server in plaintext, use this process to encrypt it without disrupting the running application.

Encrypt the existing file and remove the plaintext from the repository:

sops --encrypt integrationm/services/com.cultofbits.web.integration.properties > integrationm/services/com.cultofbits.web.integration.properties.enc
git rm integrationm/services/com.cultofbits.web.integration.properties
git add integrationm/services/com.cultofbits.web.integration.properties.enc
git commit

On the next deploy, the .enc file is uploaded and cob-decrypt produces integrationm/services/com.cultofbits.web.integration.properties on the server, replacing the previous cleartext version. The application sees no interruption.

Note: The cleartext file remains in the git history. Anyone with access to the repository can still read the secrets from previous commits. All secrets in the file should be rotated after this change is deployed.

Update an existing encrypted file

The simplest way to edit an encrypted file is to let SOPS decrypt it, open it in your editor, and re-encrypt it on save:

sops integrationm/services/com.cultofbits.web.integration.properties.enc

When you close the editor, SOPS writes the updated encrypted content back to integrationm/services/com.cultofbits.web.integration.properties.enc. Commit and deploy as usual.

Convert an encrypted file back to cleartext

When a file no longer holds any secret — for example after its credentials were moved to a dedicated secrets file — it can go back to being a plain file in the repository, so that it can be read, diffed and edited without a key.

Only files with no secrets left

Once a file is committed in cleartext, its content stays in the git history forever. Before adding the decrypted file to git, open it and confirm that nothing sensitive remains. If something sensitive is still there, move it out first or keep the file encrypted. If a secret does get committed by mistake, rotate it.

Decrypt the file into its final name, remove the .enc from the repository and commit both changes together:

sops --decrypt integrationm/services/com.cultofbits.web.integration.properties.enc > integrationm/services/com.cultofbits.web.integration.properties
# review the decrypted file before going on
git rm integrationm/services/com.cultofbits.web.integration.properties.enc
git add integrationm/services/com.cultofbits.web.integration.properties
git commit

On the next deploy the .enc file is removed from the server and the cleartext file is synced like any other project file. The application sees no interruption.

If the file has environment-specific variants, such as com.cultofbits.web.integration.ENV__qual__.properties.enc, convert every variant in the same commit. .sops.yaml needs no change, unless it has a path_regex rule that existed only for this file.

Deploy it, do not test it

Make this change through cob-cli deploy, not inside a cob-cli test session. When a test session sees a .enc file disappear locally, it removes both the .enc and its decrypted sibling from the server — and here that sibling is the very cleartext file the session has just synced. The end-of-session restore has the same problem. Commit and deploy instead.

See also

• How encrypted files work across the deployment lifecycle — what cob-cli and cob-decrypt do on the server in each direction.
• How to set up SOPS with age keys — toolchain and .sops.yaml rules, including per-environment keys.