The usual workarounds — a separate secrets manager, a wall of kubectl create secret commands, a shared password vault that nobody keeps in sync — all break the “Git is the source of truth” promise.

SOPS (Secrets OPerationS) and age solve this neatly. Together they let you commit encrypted secrets straight into Git, review them in pull requests, and decrypt them only where they’re needed.

The plaintext never touches the repo; the ciphertext lives right next to the code it belongs to.

This post covers what each tool is, how the encryption works under the hood (including the role of public keys), and why the combination fits GitOps so well.

It then shows how the pair enables team collaboration, walks through a runnable example that uses mise to install both tools, and lists the limitations to know before adopting it.

What are SOPS and age?

They solve two different halves of the same problem.

age is a modern, opinionated file-encryption tool — think “GPG without the footguns”. It has no configuration knobs, no cipher negotiation, and tiny keys.

A public key looks like age1nwhnh2qv6yealq4npum4tlzl0uyev5haa7y355znqjhwuxu8l3qsc4h8mc and a private key is a single line you can paste anywhere. age encrypts a whole file (or stdin) for one or more recipients. That’s it.

SOPS is an editor for structured secret files — YAML, JSON, ENV, INI, or binary. Instead of encrypting the whole file into an opaque blob, it encrypts only the values, leaving keys, structure, and comments readable.

SOPS delegates the actual cryptography to a backend: AWS KMS, GCP KMS, Azure Key Vault, HashiCorp Vault, PGP — or age.

The combination is powerful precisely because each tool stays in its lane. age provides simple, auditable encryption with portable keys; SOPS provides a structure-aware, Git-friendly workflow on top of it.

No cloud account required.

How it works internally

This is the part worth understanding, because it explains every design decision that follows.

age: envelope encryption with X25519

age uses a classic envelope (hybrid) encryption scheme. When you encrypt a file for a recipient’s public key:

1. age generates a random 128-bit (16-byte) symmetric file key for this one file.
2. The file body is encrypted with a payload key derived from the file key (via HKDF-SHA-256, salted with a random nonce) using ChaCha20-Poly1305, an authenticated cipher (confidentiality and integrity). The body is split into 64 KiB chunks so it can be streamed.
3. For each recipient, age wraps (encrypts) the file key so only that recipient’s private key can unwrap it. This wrapped copy is stored in a per-recipient stanza in the file header.

The wrapping for an age1... recipient uses X25519, an Elliptic-Curve Diffie–Hellman function over Curve25519:

• age generates an ephemeral keypair just for this encryption.
• It combines the ephemeral private key with the recipient’s public key via Diffie–Hellman to derive a shared secret.
• It runs that shared secret through HKDF-SHA-256 to get a wrap key, which encrypts the file key into the recipient’s stanza. The stanza also stores the ephemeral public key.

To decrypt, the recipient combines their private key with the stored ephemeral public key, derives the same shared secret, unwraps the file key, and decrypts the body.

The math of Diffie–Hellman guarantees both sides arrive at the same secret without it ever crossing the wire.

The key insight: the public key only lets you wrap (encrypt) the file key; it cannot unwrap it. So a public key is safe to share, commit, and put in a PR.

You can encrypt for someone without being able to decrypt what you just wrote — and that’s exactly what makes multi-recipient, GitOps-friendly secrets possible.

Because the file key is wrapped once per recipient, encrypting for ten teammates just means ten small stanzas in front of one shared ciphertext body.

An age file header is plainly visible:

1
2
3
4
5
6

-----BEGIN AGE ENCRYPTED FILE-----
-> X25519 kR7t8qV5zwYtVRhb...       # ephemeral pubkey + wrapped file key (recipient 1)
-> X25519 9aB2cD...                 # recipient 2
--- <header MAC, HMAC-SHA-256 over the header>
<ciphertext body, ChaCha20-Poly1305 in 64 KiB chunks>
-----END AGE ENCRYPTED FILE-----

SOPS: a data key on top of age

SOPS adds one more layer so it can encrypt values individually while still only doing public-key crypto once:

1. SOPS generates a random data key (an AES-256 key) for the file.
2. It encrypts each secret value in place with that data key using AES256-GCM — so password: hunter2 becomes password: ENC[AES256_GCM,data:...,iv:...,tag:...,type:str]. Keys and structure stay in cleartext, which is what makes diffs reviewable.
3. The data key itself is then encrypted for every configured recipient. With the age backend, that means handing the data key to age, which wraps it for each age1... public key and stores the resulting age blob in the file’s sops: metadata block.
4. SOPS computes a MAC — a SHA-512 hash over all the plaintext values — and stores it encrypted with the data key (AES256-GCM), which is the mac: ENC[AES256_GCM,...] field you’ll see in the file. On decryption SOPS recomputes the hash over the decrypted values and compares; if they differ (e.g. someone added, removed, or swapped a ciphertext value), decryption fails.

So there are two nested envelopes: age wraps the SOPS data key (per recipient, via X25519), and the data key encrypts each value (via AES-GCM).

To decrypt, SOPS asks age to unwrap the data key with your private key, then decrypts every ENC[...] value and verifies the MAC.

You’ll see this structure directly in an encrypted file’s footer:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

sops:
    age:
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----   # the data key, wrapped by age
            ...
            -----END AGE ENCRYPTED FILE-----
          recipient: age1nwhnh2qv6yealq4npum4tlzl0uyev5haa7y355znqjhwuxu8l3qsc4h8mc
    encrypted_regex: ^(data|stringData)$
    mac: ENC[AES256_GCM,data:...]                 # integrity check
    version: 3.13.1

Why this combination, and common use cases

A few properties fall out of the design above:

• Secrets live in Git. The ciphertext is committed alongside the manifests it configures. One repo, one source of truth — the GitOps ideal.
• Diffs stay meaningful. Because only values are encrypted, a PR shows which keys changed, even if it can’t show the new plaintext. Reviewers see structure and intent.
• No central secret server required. Decryption needs only a private key file. Great for homelabs, edge, air-gapped, or “I don’t want to pay for a KMS” setups. (You can still use KMS — SOPS supports mixing backends.)
• Asymmetric trust. Anyone with the public key can add or update secrets; only holders of a private key can read them. CI can encrypt without being able to decrypt.

Typical use cases:

• Kubernetes secrets in GitOps. Commit encrypted Secret manifests and let Flux’s SOPS integration or ksops for Argo CD decrypt them in-cluster using a private key stored once as a cluster secret.
• App config / .env files. Encrypt config.prod.yaml or .env.production and decrypt at deploy time.
• Terraform / Ansible variables. Keep secrets.auto.tfvars or Ansible vault-style data encrypted in the repo.
• CI/CD pipelines. Store the age private key as a single CI secret; pipelines decrypt everything else from the repo on demand.

How it enables team collaboration

This is age’s quiet superpower. Because you encrypt for a list of public keys, onboarding a teammate is a metadata change, not a secret re-share.

1. Each engineer (and each environment, and CI) generates their own age keypair and publishes only the public key — in the repo, a wiki, or chat. Private keys never leave their owner’s machine.
2. A .sops.yaml file in the repo lists which public keys may decrypt which paths.
3. To add a new member, you append their public key to .sops.yaml and run sops updatekeys on the affected files. SOPS unwraps the data key, re-wraps it for the new recipient list, and writes the file back — without ever exposing the plaintext values. The change is a reviewable diff in the sops: block.
4. To off-board someone, remove their key and run updatekeys again, then rotate the underlying secrets.

You can even encrypt to different recipient sets per path — say, dev secrets readable by the whole team but prod secrets restricted to the CI key and two leads.

All of it is declared in one .sops.yaml:

1
2
3
4
5

creation_rules:
  - path_regex: secrets/dev/.*\.ya?ml$
    age: "age1dev...,age1alice...,age1bob..."
  - path_regex: secrets/prod/.*\.ya?ml$
    age: "age1ci...,age1lead..."

No shared master password, no “DM me the prod creds”, no secret that’s only in one person’s head.

A runnable example

Let’s encrypt a Kubernetes Secret end to end. We’ll use mise to install sops and age so the versions are pinned and reproducible. (New to mise? See my getting started post.)

1. Create the project and install the tools

1
2
3
4

mkdir sops-age-demo && cd sops-age-demo

# install both tools, pinned in mise.toml
mise use sops@latest age@latest

This writes a mise.toml and installs the binaries:

1
2
3
4

# mise.toml
[tools]
age = "latest"
sops = "latest"

Confirm they’re active:

1
2

mise exec -- sops --version    # sops 3.13.1 (latest)
mise exec -- age --version     # v1.3.1

Pin real versions (e.g. sops@3.13.1, age@1.3.1) and commit a mise.lock if you want byte-for-byte reproducibility — see the mise lockfile docs.

2. Generate an age keypair

1
2

mise exec -- age-keygen -o keys.txt
# Public key: age1nwhnh2qv6yealq4npum4tlzl0uyev5haa7y355znqjhwuxu8l3qsc4h8mc

keys.txt holds your private key — never commit it. The public key is printed and also stored as a comment inside the file. You can re-derive the public key from the private file at any time:

1
2

mise exec -- age-keygen -y keys.txt
# age1nwhnh2qv6yealq4npum4tlzl0uyev5haa7y355znqjhwuxu8l3qsc4h8mc

Tell SOPS where your private key lives (SOPS reads this env var when decrypting):

1

export SOPS_AGE_KEY_FILE=$PWD/keys.txt

3. Declare encryption rules in .sops.yaml

Put your public key here. The encrypted_regex tells SOPS to only encrypt values under data/stringData, leaving the rest of the manifest readable:

1
2
3
4
5
6

# .sops.yaml
creation_rules:
  - path_regex: secrets/.*\.ya?ml$
    encrypted_regex: '^(data|stringData)$'
    age: >-
      age1nwhnh2qv6yealq4npum4tlzl0uyev5haa7y355znqjhwuxu8l3qsc4h8mc

4. Write and encrypt a secret

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

mkdir -p secrets
cat > secrets/db.yaml <<'EOF'
apiVersion: v1
kind: Secret
metadata:
  name: db-credentials
stringData:
  username: app
  password: s3cr3t-p@ssw0rd
EOF

mise exec -- sops encrypt --in-place secrets/db.yaml

The result is safe to commit. Note that metadata and the keys stay readable — only the values are ENC[...]:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

apiVersion: v1
kind: Secret
metadata:
    name: db-credentials
stringData:
    username: ENC[AES256_GCM,data:/UNE,iv:JpHY...,tag:pEdX...,type:str]
    password: ENC[AES256_GCM,data:lk6v7...,iv:NflK...,tag:d9sz...,type:str]
sops:
    age:
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
            ...the data key, wrapped for your public key...
            -----END AGE ENCRYPTED FILE-----
          recipient: age1nwhnh2qv6yealq4npum4tlzl0uyev5haa7y355znqjhwuxu8l3qsc4h8mc
    encrypted_regex: ^(data|stringData)$
    mac: ENC[AES256_GCM,data:...]
    version: 3.13.1

5. Decrypt, edit, and extract

Decrypt the whole file (needs your private key via SOPS_AGE_KEY_FILE):

1
2

mise exec -- sops decrypt secrets/db.yaml
# ...stringData.password: s3cr3t-p@ssw0rd

Edit in place — SOPS decrypts into a temp editor session and re-encrypts on save:

1

mise exec -- sops edit secrets/db.yaml

Pull out a single value (handy in deploy scripts):

1
2

mise exec -- sops decrypt --extract '["stringData"]["password"]' secrets/db.yaml
# s3cr3t-p@ssw0rd

Pipe a decrypted manifest straight to your cluster, so plaintext never lands on disk:

1

mise exec -- sops decrypt secrets/db.yaml | kubectl apply -f -

6. Add a teammate (key rotation)

Append a second public key to the age: line in .sops.yaml, then re-wrap the data key for the new recipient list — no plaintext exposure:

1

mise exec -- sops updatekeys secrets/db.yaml

The only change in the diff is a new stanza in the sops: block. The teammate can now decrypt with their private key, and the original ENC[...] values are untouched.

7. What to commit (and what not to)

1
2
3
4

echo 'keys.txt' >> .gitignore   # NEVER commit private keys

git add mise.toml .sops.yaml secrets/db.yaml .gitignore
git commit -m "Add encrypted db credentials"

Commit the encrypted secret, the .sops.yaml, and mise.toml. Keep keys.txt out of Git — distribute private keys out-of-band (a password manager, your CI’s secret store, or a sealed cluster secret).

8. Clean up (optional)

1

cd .. && rm -rf sops-age-demo

Limitations and gotchas

No tool is free of trade-offs. Know these before you commit:

• Key distribution is on you. age has no PKI, no web of trust, no revocation lists. Getting private keys safely onto machines/CI and proving a public key really belongs to a teammate is a manual, out-of-band process.
• Removing a recipient doesn’t un-leak a secret. sops updatekeys stops future access, but anyone who already decrypted (or kept an old Git revision) still has the plaintext. Off-boarding means rotating the actual secret values, not just the keys.
• Git history is forever. If you ever commit a plaintext secret by mistake, it lives in history until you rewrite it. Encrypt before the first commit.
• Metadata isn’t secret. Keys, structure, and comments stay in cleartext by design. Don’t put sensitive data in a key name like aws_root_password_for_acme_corp. The value lengths are also roughly observable.
• Per-value encryption only suits structured files. SOPS shines on YAML/JSON/ENV. For arbitrary binaries it falls back to whole-file encryption, losing the nice diffs — at which point plain age may be simpler.
• Decryption needs the private key present at runtime. In Kubernetes that usually means storing the age key as an in-cluster secret for Flux/Argo to use — so your cluster’s secret store becomes the new root of trust you must protect.
• No built-in auditing or rotation policy. Unlike a managed KMS, there’s no access log, automatic rotation, or fine-grained IAM. You build process around it yourself. For high-compliance environments, SOPS can target KMS backends instead of (or alongside) age.
• Whitespace/formatting churn. SOPS rewrites files on encrypt and may normalize formatting, which can produce noisier diffs than expected.

None of these are dealbreakers — they’re the cost of a serverless, Git-native model. For most teams, homelabs, and GitOps setups, the simplicity is well worth it.

Wrapping up

SOPS + age turns “secrets in Git” from an oxymoron into a clean workflow.

age gives you small, portable keys and a dead-simple envelope-encryption scheme where public keys safely wrap a file key for any number of recipients.

SOPS layers a structure-aware, per-value editor on top, so your encrypted secrets diff and review like normal config.

Pin both with mise, declare recipients in .sops.yaml, and your secrets become just another reviewable, version-controlled, GitOps-friendly file — with the plaintext staying exactly where it belongs: nowhere near the repo.

Useful links

• SOPS — getsops/sops
• age — FiloSottile/age
• age design & specification
• Flux: Manage Kubernetes secrets with SOPS
• Argo CD secret management
• Getting started with mise

It replaces all of them with a single tool and a single mise.toml config file.

In this post I’ll introduce the three major concepts that make mise useful day to day:

1. Dev tools — install and switch between runtimes like Node, Python, and Go.
2. Environments — load the right environment variables per directory.
3. Tasks — a built-in task runner for builds, tests, linting, and scripts.

Then I’ll walk through a small but fully runnable example that ties all three together.

What is mise?

mise is a polyglot tool manager, environment manager, and task runner rolled into one binary.

It is a spiritual successor to asdf (and is compatible with asdf’s .tool-versions files), but written in Rust and considerably faster.

The core idea: you declare what a project needs in a mise.toml file, and mise makes sure those tools, versions, and environment variables are active whenever you’re inside that directory.

Install mise

On Linux or macOS:

1

curl https://mise.run | sh

By default mise installs to ~/.local/bin. Verify it:

1
2

~/.local/bin/mise --version
# mise 2026.x.x

See the installation guide for other methods: Homebrew, apt, dnf, Snap, Nix, Windows, and more.

Activate mise (recommended)

mise exec works for one-off commands, but for interactive shells you’ll want to activate mise so tools and env vars load automatically as you cd around.

Add the appropriate line to your shell’s rc file:

1
2
3
4
5
6
7
8

# bash
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc

# zsh
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc

# fish
echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish

Restart your shell, then run a health check:

1

mise doctor

For CI/CD, IDEs, and non-interactive scripts, mise also supports shims instead of shell activation.

Concept 1: Dev tools

mise manages multiple versions of programming language runtimes and CLI tools on the same machine, then switches between them automatically based on the directory you’re in.

Tools are declared in the [tools] section of mise.toml:

1
2
3
4
5

# mise.toml
[tools]
node = '24'
python = '3'
go = 'latest'

You rarely write this by hand. The mise use command adds tools for you and installs them:

1
2
3
4
5

# add to the current project's mise.toml
mise use node@24

# install globally (~/.config/mise/config.toml)
mise use --global node@24

To run a tool once without installing it permanently, use mise exec (aliased to mise x):

1
2

mise exec node@26 -- node -v
# downloads node 26 if needed, then prints v26.x.x

How version switching works

Once mise is activated, it walks up the directory tree looking for config files (mise.toml, .tool-versions, .node-version, etc.), resolves the requested versions, and prepends the correct binaries to your PATH:

1
2
3
4
5
6

# inside a project pinned to node 20
echo $PATH
# /home/user/.local/share/mise/installs/node/20.x.x/bin:/usr/local/bin:...

node -v
# v20.x.x

Move to another project pinned to a different version and node changes automatically.

Tools come from multiple backends — core, aqua, npm, pipx, cargo, github, and asdf plugins — so the same mise use workflow installs almost anything. Browse the registry to see what’s available.

Concept 2: Environments

mise can load environment variables per project from the [env] section of mise.toml:

1
2
3
4

# mise.toml
[env]
NODE_ENV = 'production'
APP_PORT = '3000'

When mise is activated, these are set automatically when you cd into the project and unset when you leave. You can also manage them from the CLI:

1
2
3
4
5
6

mise set NODE_ENV=development
mise set
# key       value        source
# NODE_ENV  development  mise.toml

mise unset NODE_ENV

A few handy features:

• Unset a variable inherited from a parent config by setting it to false:

  1 2	[env] NODE_ENV = false

• Provide a fallback that only applies if the variable isn’t already set, using default:

  1 2	[env] NODE_ENV = { default = "development" }

• Load a dotenv file with the _.file directive:

  1 2	[env] _.file = '.env'

• Redact secrets so they don’t leak into task output:

  1 2	[env] SECRET = { value = "my_secret", redact = true }

Because env vars resolve alongside tools, you get a single source of truth for “what does this project need to run” — versions and configuration together.

Concept 3: Tasks

mise has a built-in task runner, so you can replace a Makefile or a pile of npm scripts. Tasks run with the full mise context loaded — your tools and env vars are already on PATH.

Define tasks in the [tasks] section:

1
2
3
4
5
6
7
8
9

# mise.toml
[tasks.build]
description = "Build the project"
run = "go build ./..."

[tasks.test]
description = "Run the test suite"
run = "go test ./..."
depends = ["build"]

Run them with mise run (aliased to mise r):

1
2
3

mise run build
mise run test     # runs build first because of `depends`
mise tasks        # list all available tasks

Task dependencies

The depends array is what turns a list of tasks into a build graph.

When you run a task, mise first runs everything in its depends list, and because dependencies execute in parallel by default, independent steps don’t block each other:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# mise.toml
[tasks.lint]
run = "golangci-lint run ./..."

[tasks.test]
run = "go test ./..."

[tasks.ci]
description = "Run lint and test, then build"
depends = ["lint", "test"]   # these two run concurrently
run = "go build ./..."        # runs only after both succeed

Running mise run ci executes lint and test at the same time, waits for both to finish, and only then runs ci’s own run command.

There are related keys too — depends_post for cleanup steps that run afterwards, and wait_for for soft ordering without forcing a task to run. See task dependencies for the full list.

Some other highlights:

• File watching with mise watch to rerun a task when sources change.

• File tasks — instead of inlining shell into TOML strings, you can drop an executable script into a mise-tasks/ directory and get proper syntax highlighting and linting:

  1 2 3

  #!/usr/bin/env bash #MISE description="Build the CLI" go build ./...

Tasks also receive useful variables like MISE_PROJECT_ROOT and MISE_TASK_NAME, so scripts can be location-independent.

A runnable example

Let’s combine all three concepts into one small Go web project you can actually run. We’ll also add golangci-lint as an additional tool to show how mise manages more than just language runtimes.

1. Create the project

1

mkdir mise-demo && cd mise-demo

2. Add the tools

Pin the exact Go version for this project. This creates mise.toml and installs Go if needed:

1

mise use go@1.26.4

Then add golangci-lint at a specific version. It lives in mise’s registry, so the same mise use workflow installs it:

1

mise use golangci-lint@2.12.2

3. Configure environment and tasks

Open the generated mise.toml and make it look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# mise.toml
[settings]
lockfile = true

[tools]
go = "1.26.4"
golangci-lint = "2.12.2"

[env]
APP_NAME = "mise-demo"
APP_PORT = "8080"

[tasks.build]
description = "Compile the web server"
run = "go build -o bin/server ."

[tasks.lint]
description = "Run golangci-lint"
run = "golangci-lint run ./..."

[tasks.serve]
description = "Run the web server"
run = "go run ."

[tasks.ci]
description = "Lint and build (lint runs first)"
depends = ["lint"]
run = "go build -o bin/server ."

The [tasks.ci] task uses depends to guarantee linting happens before the build — a small example of the task dependencies covered above.

4. Lock the tool versions with mise.lock

We set lockfile = true above, but lockfiles are not generated automatically. Run mise lock (or just mise install) to create one:

1

mise lock

This writes a mise.lock file next to mise.toml, pinning the exact resolved versions, checksums, and per-platform download URLs (truncated here for brevity):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# mise.lock
# @generated - this file is auto-generated by `mise lock`

[[tools.go]]
version = "1.26.4"
backend = "core:go"

[tools.go."platforms.linux-x64"]
checksum = "sha256:1153d3d50e0ac764b447adfe05c2bcf08e889d42a02e0fe0259bd47f6733ad7f"
url = "https://dl.google.com/go/go1.26.4.linux-amd64.tar.gz"

[[tools.golangci-lint]]
version = "2.12.2"
backend = "aqua:golangci/golangci-lint"

[tools.golangci-lint."platforms.linux-x64"]
checksum = "sha256:8df580d2670fed8fa984aac0507099af8df275e665215f5c7a2ae3943893a553"
url = "https://github.com/golangci/golangci-lint/releases/download/v2.12.2/golangci-lint-2.12.2-linux-amd64.tar.gz"
provenance = "github-attestations"

Commit mise.lock alongside mise.toml. Now even loose specs (like go = "1") resolve to the locked version on every machine, giving you reproducible installs.

In CI you can go a step further with the locked setting (or mise install --locked) to fail fast if the lockfile is missing or incomplete.

5. Add the application code

Initialize the Go module:

1

go mod init mise-demo

Create main.go:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

package main

import (
	"fmt"
	"log"
	"net/http"
	"os"
	"runtime"
)

func main() {
	name := envOr("APP_NAME", "unknown")
	port := envOr("APP_PORT", "8080")

	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		if _, err := fmt.Fprintf(w, "Hello from %q, served by Go %s\n", name, runtime.Version()); err != nil {
			log.Printf("write response: %v", err)
		}
	})

	addr := ":" + port
	log.Printf("%s listening on http://localhost%s", name, addr)
	log.Fatal(http.ListenAndServe(addr, nil))
}

func envOr(key, fallback string) string {
	if v := os.Getenv(key); v != "" {
		return v
	}
	return fallback
}

Note that the handler checks the error returned by fmt.Fprintf. This isn’t just good practice.

Without it, golangci-lint’s default errcheck linter would flag the unchecked return value and the ci task would fail at the lint step.

6. Run it

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# confirm the tools are active
mise exec -- go version
# go version go1.26.4 ...
mise exec -- golangci-lint version
# golangci-lint has version 2.12.2 ...

# list the tasks mise discovered
mise tasks
# build  Compile the web server
# ci     Lint and build (lint runs first)
# lint   Run golangci-lint
# serve  Run the web server

# lint then build in one shot (lint runs first via `depends`)
mise run ci

# start the server (uses APP_PORT from [env])
mise run serve
# mise-demo listening on http://localhost:8080

In another terminal:

1
2

curl localhost:8080
# Hello from "mise-demo", served by Go go1.26.4

That’s the whole loop. mise.toml declares the tools (Go 1.26.4 plus golangci-lint 2.12.2), the environment (APP_NAME, APP_PORT), and the tasks (build, lint, serve, ci); mise.lock pins exactly what gets installed.

Anyone who clones the repo and runs mise install followed by mise run ci gets the exact same setup — no README full of “first install the right Go version, then go install golangci-lint, then…” steps.

7. Clean up (optional)

1

cd .. && rm -rf mise-demo

Bonus: global quality-of-life CLI tools

So far we’ve used mise for per-project toolchains, but it’s just as handy for the CLI tools you want available everywhere.

The -g (--global) flag installs a tool and records it in your global config at ~/.config/mise/config.toml instead of a project mise.toml.

Here’s a starter kit of quality-of-life tools, each pulled from mise’s registry across different backends (core, aqua, npm, GitHub releases):

1
2
3
4
5
6
7

mise use -g lazygit@latest    # terminal UI for git
mise use -g fzf@latest        # fuzzy finder
mise use -g ripgrep@latest    # fast grep (rg)
mise use -g fd@latest         # fast, friendly find
mise use -g gh@latest         # GitHub CLI
mise use -g copilot@latest    # GitHub Copilot CLI
mise use -g neovim            # hyperextensible Vim-based editor

Each command updates the same global config:

1
2
3
4
5
6
7
8
9

# ~/.config/mise/config.toml
[tools]
lazygit = "latest"
fzf = "latest"
ripgrep = "latest"
fd = "latest"
gh = "latest"
copilot = "latest"
neovim = "latest"

Because this file lives in your dotfiles location, you can commit it to your dotfiles repo and reproduce your entire CLI toolbox on a new machine with a single command:

1

mise install

A couple of tips:

• Run mise ls to see everything mise manages (global and local) and which versions are active.
• Pin a tool to a real version instead of latest (e.g. mise use -g fzf@0.56.3) when you want reproducibility over always-newest.
• Upgrade everything later with mise upgrade.

Why this matters

The payoff is reproducibility with almost no ceremony. A single committed mise.toml answers three questions at once:

• Which tool versions does this project use?
• Which environment variables does it expect?
• How do I build, test, and run it?

New contributors run mise install and they’re ready — and because mise.lock pins exact versions, they get the same toolchain you do.

CI runs the same mise run commands as your laptop. And you stop maintaining three separate tools to do one job.

Useful links

• mise — Getting Started
• Dev Tools
• Environments
• Tasks
• Configuration reference
• Lockfiles (lockfile setting)
• Tool registry
• Comparison to asdf

A note on Workers vs. Pages: Cloudflare is consolidating static site hosting from Cloudflare Pages into Cloudflare Workers.

As of 2025, Workers Static Assets is the recommended way to host new static sites, and Pages is in maintenance mode.

In the dashboard both still live under the unified Workers & Pages section, which is why the deploy commands below use wrangler deploy (a Workers command) rather than the older Pages workflow.

Here is the setup this post builds toward:

• GitHub repository: vancanhuit/personal-blog
• Live site: blog.canhdinh.com
• Static site generator: Hugo
• Theme: PaperMod
• Hosting/deployment: Cloudflare Workers (Static Assets)

The Cloudflare build and deploy commands are:

1

git submodule update --init --recursive && hugo --gc --minify

1

npx wrangler deploy

The Workers deployment options live in a wrangler.jsonc file committed to the repository (covered later).

Why Hugo?

Hugo is a static site generator written in Go. It is fast, simple, and works very well for technical blogs.

A static blog suits my use case because I mostly write posts made up of:

• Markdown content
• Source code examples
• DevOps notes
• Infrastructure experiments

Hugo generates plain HTML, CSS, JavaScript, images, and fonts, so the final site is easy to host on Cloudflare.

Why PaperMod?

I chose PaperMod because it is clean, fast, and well suited to technical writing.

The features I wanted are:

• Clean blog layout
• Dark/light mode
• Table of contents
• Reading time
• Tags and categories
• Good source code block rendering
• Code copy button
• Minimal maintenance

PaperMod is a practical choice for a technical blog: it stays out of the way and lets the content stand out.

Create the Hugo site

Create a new Hugo project. Hugo defaults to a TOML config file, so pass --format yaml to get hugo.yaml instead:

1
2
3

hugo new site personal-blog --format yaml
cd personal-blog
git init

Then add PaperMod as a Git submodule:

1

git submodule add https://github.com/adityatelange/hugo-PaperMod themes/PaperMod

Adding PaperMod as a submodule creates a .gitmodules file in the repository.

Check it with:

1

cat .gitmodules

Example:

1
2
3

[submodule "themes/PaperMod"]
  path = themes/PaperMod
  url = https://github.com/adityatelange/hugo-PaperMod

Configure Hugo

Here is a simplified hugo.yaml configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

baseURL: "https://blog.canhdinh.com/"
locale: "en-us"
title: "Canh Dinh"
theme: "PaperMod"

pagination:
  pagerSize: 10

outputs:
  home:
    - HTML
    - RSS
    - JSON

params:
  env: "production"
  description: "Notes on DevOps practices, self-hosting and software delivery."
  author: "Canh Dinh"
  mainSections:
    - posts
  homeInfoParams:
    Title: "Hi there 👋"
    Content: >
      Welcome to my blog.
  defaultTheme: "auto"
  disableThemeToggle: false
  ShowReadingTime: true
  ShowShareButtons: false
  ShowPostNavLinks: true
  ShowBreadCrumbs: true
  ShowCodeCopyButtons: true
  ShowWordCount: true
  ShowRssButtonInSectionTermList: true
  ShowToc: true
  TocOpen: false
  UseHugoToc: true
  socialIcons:
    - name: "github"
      url: "https://github.com/vancanhuit"

menu:
  main:
    - identifier: "tags"
      name: "Tags"
      url: "/tags/"
      weight: 20
    - identifier: "archives"
      name: "Archives"
      url: "/archives/"
      weight: 30
    - identifier: "search"
      name: "Search"
      url: "/search/"
      weight: 40

markup:
  highlight:
    codeFences: true
    guessSyntax: true
    lineNos: true
    lineNumbersInTable: true
    noClasses: false

The two most important values are the production domain and the theme:

1
2

baseURL: "https://blog.canhdinh.com/"
theme: "PaperMod"

A few PaperMod-specific options are worth highlighting:

• mainSections: [posts] makes the home page (/) list posts from content/posts/, so the landing page doubles as the posts archive.
• homeInfoParams renders an intro block (title plus content) above the post list on the home page.
• outputs.home adds a JSON output, which generates the search index used by the search page.

Home, archives, and search pages

PaperMod renders the post list on the home page automatically, but the Archives and Search pages each need a content file that selects the right layout. Without them, the menu links return 404.

Create the archives page:

1

hugo new content archives.md

1
2
3
4
5
6

---
title: "Archives"
layout: "archives"
url: "/archives/"
summary: "archives"
---

Create the search page:

1

hugo new content search.md

1
2
3
4
5
6
7

---
title: "Search"
layout: "search"
url: "/search/"
summary: "search"
placeholder: "Search posts..."
---

The search page relies on the JSON home output configured earlier. PaperMod ships with Fuse.js and runs fuzzy, client-side search over that index, so no server-side component is required.

Add a blog post

Create a new post:

1

hugo new content posts/hello-world.md

Example post:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

---
title: "Hello World"
date: 2026-06-21T10:00:00+07:00
draft: false
tags: ["hugo", "cloudflare", "devops"]
categories: ["devops"]
showToc: true
---

This is my first post using Hugo, PaperMod, GitHub, and Cloudflare.

```go
package main

import "fmt"

func main() {
    fmt.Println("Hello from my blog")
}
```

Make sure the post is publishable:

1

draft: false

If draft is set to true, Hugo excludes the post from production builds.

Run locally

For local development, run:

1

hugo server -D --disableFastRender

Then open:

1

http://localhost:1313

The -D flag includes draft posts.

If the site looks stale after changing CSS, fonts, or theme files, clean the generated output and rebuild:

1
2
3

rm -rf public resources/_gen
hugo --gc --minify
hugo server -D --disableFastRender

Push to GitHub

Commit and push the project:

1
2
3
4
5

git add .
git commit -m "Initial Hugo blog with PaperMod"
git branch -M main
git remote add origin https://github.com/vancanhuit/personal-blog.git
git push -u origin main

Configure Cloudflare deployment

In the Cloudflare dashboard, open Workers & Pages, create a new Worker, connect the GitHub repository, and set the following commands.

Build command

1

git submodule update --init --recursive && hugo --gc --minify

This does two things:

1. Fetches the PaperMod theme submodule.
2. Builds and minifies the Hugo site into the public/ directory.

The git submodule update --init --recursive step matters because PaperMod is stored as a Git submodule.

Deploy command

1

npx wrangler deploy

The deploy command stays minimal because the Workers options live in a wrangler.jsonc file at the repository root:

1
2
3
4
5
6
7
8
9

{
  "name": "personal-blog",
  "compatibility_date": "2026-06-21",
  "assets": {
    "directory": "public",
  },
  "preview_urls": false,
  "workers_dev": false
}

This file tells Wrangler the Worker name, the compatibility date, and the directory (public/) to serve as static assets.

Two settings disable Cloudflare’s automatic preview endpoints, since I only want the production domain to serve the site:

• "preview_urls": false turns off the per-version preview URLs Cloudflare generates for each deployment.
• "workers_dev": false disables the default *.workers.dev subdomain, so the Worker is reachable only through my custom domain.

Environment variables

I also recommend setting HUGO_VERSION in Cloudflare:

1

HUGO_VERSION = 0.163.3

Pinning the Hugo version avoids unexpected build differences between local and Cloudflare environments.

Self-host fonts

I self-host two fonts so the site does not depend on a third-party font CDN:

• Inter for body and UI text.
• Maple Mono NL for code blocks.

Font files are stored under:

1
2

static/fonts/inter/
static/fonts/maple-mono/

For example:

1
2
3

static/fonts/maple-mono/MapleMonoNL-Regular.ttf.woff2
static/fonts/maple-mono/MapleMonoNL-Bold.ttf.woff2
static/fonts/maple-mono/MapleMonoNL-Italic.ttf.woff2

I then define the code font in:

1

assets/css/extended/custom-fonts.css

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

@font-face {
  font-family: "Maple Mono NL";
  src: url("/fonts/maple-mono/MapleMonoNL-Regular.ttf.woff2") format("woff2");
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

@font-face {
  font-family: "Maple Mono NL";
  src: url("/fonts/maple-mono/MapleMonoNL-Bold.ttf.woff2") format("woff2");
  font-weight: 700;
  font-style: normal;
  font-display: swap;
}

code,
pre,
kbd,
samp,
.highlight pre,
.highlight code,
.chroma,
.chroma code {
  font-family: "Maple Mono NL", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
  font-feature-settings: "liga" 0, "calt" 0;
  font-variant-ligatures: none;
}

I disable ligatures because I prefer code to display exactly as typed.

For body text, I load Inter as a variable font (two woff2 files cover every weight) and set it as the base font:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

@font-face {
  font-family: "Inter";
  src: url("/fonts/inter/inter-latin-wght-normal.woff2") format("woff2-variations");
  font-weight: 100 900;
  font-style: normal;
  font-display: swap;
}

body {
  font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
}

Because the extended stylesheet loads after the theme’s CSS, this body rule overrides PaperMod’s default font stack.

Custom styling

PaperMod automatically bundles any CSS placed in assets/css/extended/, loaded after the theme styles. I use a custom.css file there to make the content stand out and improve reading comfort:

1

assets/css/extended/custom.css

The main tweaks are:

• An accent color for in-content links, with the default underline removed and an underline that animates in on hover.
• Styled blockquotes with an accent border, a tinted background, and a decorative quote mark.
• Subtle borders on inline code, rounded tables with a shaded header row, and a slim centered horizontal rule.
• A softer light palette, brighter dark-mode text, and a larger line height for more comfortable reading.

All colors are driven by CSS variables, including PaperMod’s own --theme, --content, and --border, plus an --accent variable defined separately for light and .dark modes, so the styling adapts to both themes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

:root {
  --accent: #2563eb;
}

.dark {
  --accent: #6ea8fe;
}

.post-content a:not(.anchor) {
  color: var(--accent);
  text-decoration: none;
}

.post-content blockquote {
  border-inline-start: 0.25rem solid var(--accent);
  background: var(--quote-bg);
}

PaperMod underlines content links via .md-content a:not(.anchor). That selector has higher specificity than a plain .post-content a, so the override matches it with .post-content a:not(.anchor) to actually remove the underline.

Normal publishing workflow

After the initial setup, publishing a new post is simple.

Create a post:

1

hugo new content posts/my-new-post.md

Preview locally:

1

hugo server -D --disableFastRender

When ready, commit and push:

1
2
3

git add .
git commit -m "Add new blog post"
git push

Cloudflare then rebuilds and redeploys the site automatically.

Troubleshooting

Theme is missing

If Cloudflare cannot find PaperMod, make sure the theme submodule is committed:

1
2

git submodule status
cat .gitmodules

Also make sure the build command includes:

1

git submodule update --init --recursive

Code blocks look broken

Clean Hugo’s generated files locally, then rebuild:

1
2
3

rm -rf public resources/_gen
hugo --gc --minify
hugo server -D --disableFastRender

Also check the Markdown code fence format:

1
2
3

```go
fmt.Println("hello")
```

New font does not appear

Hard refresh the browser:

1

Ctrl + Shift + R

On macOS:

1

Cmd + Shift + R

If fonts are cached aggressively, rename the font folder or font files and update the CSS paths.

Deployment fails after successful build

If the log shows Hugo built successfully but deployment failed, check the deploy command and the wrangler.jsonc file.

For this setup, use:

1

npx wrangler deploy

And make sure wrangler.jsonc points the assets directory at the Hugo output:

1
2
3
4
5
6
7
8
9

{
  "name": "personal-blog",
  "compatibility_date": "2026-06-21",
  "assets": {
    "directory": "public",
  },
  "preview_urls": false,
  "workers_dev": false
}

If wrangler.jsonc is missing or assets.directory is wrong, Wrangler has nothing to upload and the deploy fails even though the build succeeded.

Useful links

• Hugo official website
• Hugo documentation
• PaperMod GitHub repository
• PaperMod installation guide
• Cloudflare Workers
• Cloudflare Workers static assets
• Migrate from Pages to Workers
• Wrangler deploy command

Final setup

The final setup is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

Hugo static site
PaperMod theme
GitHub repository
Cloudflare build command:
  git submodule update --init --recursive && hugo --gc --minify

Cloudflare deploy command:
  npx wrangler deploy

Workers options stored in wrangler.jsonc