diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 0000000..a067e6c
--- /dev/null
+++ b/.github/workflows/test.yml
@@ -0,0 +1,44 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  # Allow manual runs from the Actions tab.
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          # Track the version in go.mod so this never drifts from the module.
+          go-version-file: go.mod
+
+      - name: Check formatting
+        # gofmt -l lists misformatted files and exits 0 either way, so fail
+        # explicitly when the list is non-empty.
+        run: |
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            echo "These files need gofmt:"
+            echo "$unformatted"
+            exit 1
+          fi
+
+      - name: Build
+        run: go build ./...
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Test
+        run: go test -race ./...
diff --git a/AGENTS.md b/AGENTS.md
index 56d1666..475e038 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -45,6 +45,8 @@ This is a flat `package main`, one concern per file:
 | `util.go`       | Tiny shared helpers.                                                     |
 | `discord_test.go` | Unit test for `buildContent` (placeholder/plural expansion).          |
 
+CI lives in `.github/workflows/` — see [CI](#ci).
+
 ## Build / run / verify
 
 All commands run from this directory.
@@ -68,6 +70,20 @@ only the immediate `runOnStart` check fires) and `markExistingOnFirstRun: false`
 After a `go build .` here, delete the stray `hoyo-codes` binary it drops
 (already gitignored).
 
+### CI
+
+Two GitHub Actions workflows, both in `.github/workflows/`:
+
+| Workflow             | Runs on                              | Does                                    |
+| -------------------- | ------------------------------------ | --------------------------------------- |
+| `test.yml`           | pushes to `main`, **every** PR       | gofmt gate, build, vet, `go test -race`. |
+| `docker-publish.yml` | pushes to `main`, `v*` tags          | builds and pushes the image to ghcr.io.  |
+
+`test.yml` takes its Go version from `go.mod` (`go-version-file`), so bumping the
+module bumps CI too. The gofmt step fails the build on any misformatted file —
+`gofmt -l` alone always exits 0, so it checks for non-empty output explicitly.
+Run the same gate locally before pushing (the one-liner above).
+
 ## Configuration reference
 
 All config lives in `config.yaml` (gitignored — it holds webhook URLs). See