UP

upgrading-golang

Comprehensive automation for upgrading Go versions across source code, Docker images, and CI/CD pipelines.

Install

mkdir -p .claude/skills/upgrading-golang && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/2473" && unzip -o skill.zip -d .claude/skills/upgrading-golang && rm skill.zip

Installs to .claude/skills/upgrading-golang

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Upgrades Go version across the entire Chainloop codebase including source files, Docker images, CI/CD workflows, and documentation. Use when the user mentions upgrading Go, golang version, or updating Go compiler version.
221 chars✓ has a “when” trigger
Intermediate

Key capabilities

  • →Update go.mod files with new Go versions
  • →Reconcile Docker image SHA256 digests
  • →Update project documentation in CLAUDE.md
  • →Update Atlas migration Docker images
  • →Sync Atlas CLI versions in common.mk

How it works

The tool performs a multi-step update by pulling official Docker images to extract SHA256 digests, then applying these versions and hashes across specific project configuration files and documentation.

Inputs & outputs

You give it
Target Go version string
You get back
Updated project files including go.mod, Dockerfiles, and documentation

When to use upgrading-golang

  • →Update Go version in project configuration
  • →Sync Docker images with new Go compiler
  • →Refresh documentation with new language version

About this skill

Upgrading Golang Version

This skill automates the comprehensive Go version upgrade process across all components of the Chainloop project.

Process

1. Confirm Target Versions

Ask the user:

  1. What Go version they want to upgrade to (e.g., "1.25.3"). If they give only a minor version (e.g., "1.27"), use the latest patch from curl -s 'https://go.dev/dl/?mode=json'.
  2. Whether they also want to upgrade Atlas migrations Docker image (if yes, ask for target Atlas version, e.g., "0.38.0")

2. Get Docker Image Digest

Pull the official golang Docker image and extract its SHA256 digest:

docker pull golang:X.XX.X

Extract the SHA256 digest from the output (format: sha256:abc123...).

If the Docker daemon is not running, read the multi-arch index digest from the registry instead:

TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/golang:pull" | jq -r .token)
curl -sI -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.oci.image.index.v1+json" \
  -H "Accept: application/vnd.docker.distribution.manifest.list.v2+json" \
  https://registry-1.docker.io/v2/library/golang/manifests/X.XX.X | grep -i docker-content-digest

3. Update Source Code

Update the go directive in:

  • ./go.mod

IMPORTANT: Do NOT update ./extras/dagger/go.mod per project policy.

Pattern to replace:

go X.XX.X

Then run go mod tidy and go build ./....

4. Update Docker Images

Update all Dockerfiles with the new version and SHA256 digest. See files-to-update.md for the complete list.

Pattern to replace:

FROM golang:X.XX.X@sha256:OLD_DIGEST AS builder

With:

FROM golang:X.XX.X@sha256:NEW_DIGEST AS builder

5. Update golangci-lint

golangci-lint refuses to run when it was built with a Go version older than the go directive in go.mod ("the Go language version (goX.YY) used to build golangci-lint is lower than the targeted Go version"). On a Go minor upgrade, bump it to a release that supports the new Go version.

  1. Find the first golangci-lint release that adds support for the new Go minor (its changelog has a "goX.YY support" entry): gh release list -R golangci/golangci-lint. Prefer the latest release.
  2. Update every version: of golangci/golangci-lint-action in .github/workflows/lint.yml.
  3. Update the install version in the init target of ./common.mk to the same version.
  4. Verify locally the way CI runs it (CI uses only-new-issues), from the repo root and from app/cli, app/controlplane and app/artifact-cas:
GOBIN=<scratch-dir> go install github.com/golangci/golangci-lint/v2/cmd/[email protected]
<scratch-dir>/golangci-lint run --new-from-rev=<upstream>/main

For a Go patch upgrade, the golangci-lint bump is not required.

5b. Regenerate Protobuf Code

The protoc plugins (protoc-gen-go, etc.) format their output with the go/format of the Go toolchain that built them. A new Go minor can change how comments in generated .pb.go files are formatted, and the CI Test (main-module) job fails with "The Git repository is dirty" when the committed files do not match.

  1. Rebuild the codegen tools with the new Go: make init-api-tools.
  2. Run make api (the openapi step needs Docker running) and make config.
  3. Commit the regenerated .pb.go files. The changes are expected to be comment-only; investigate anything else.

6. Update Documentation

Update the version reference in ./CLAUDE.md under "Key Technologies":

- **Language**: Go X.XX.X

7. Update Atlas Docker Image and CLI (Optional)

If the user requested an Atlas upgrade:

7a. Pull the Atlas Docker image and extract its SHA256 digest:

docker pull arigaio/atlas:X.XX.X

Extract the SHA256 digest from the output (format: sha256:abc123...).

7b. Update ./app/controlplane/Dockerfile.migrations:

Pattern to replace:

FROM arigaio/atlas:X.XX.X@sha256:OLD_DIGEST as base

With:

FROM arigaio/atlas:X.XX.X@sha256:NEW_DIGEST as base

7c. Update ./common.mk for make init:

IMPORTANT: Before updating the version in common.mk, ALWAYS test that the Atlas version is available via the curl command:

curl -sSf https://atlasgo.sh | ATLAS_VERSION=vX.XX.X sh -s -- --version

If the command fails or the version is not available, do NOT update common.mk. Only the Docker image should be updated in this case.

Update the Atlas CLI installation version in the init target:

curl -sSf https://atlasgo.sh | ATLAS_VERSION=vX.XX.X sh -s -- -y

8. Verify Changes

Run verification commands:

make test
make lint

If errors occur, address them before completing the upgrade.

9. Final Checks

  • Search for leftover references to the old version: grep -rnE "golang:OLD|go OLD|OLD_MINOR\.[0-9]" --exclude=go.sum .
  • Ensure all license headers are updated (2024 → 2024-2025 or add current year)
  • Run buf format -w if any proto files were affected
  • Run wire ./... if any constructor dependencies changed
  • Verify go.mod changes with go mod tidy

Important Notes

  • Always use SHA256 digests for Docker images for security and reproducibility
  • The dagger module (./extras/dagger/go.mod) must NOT be updated
  • GitHub Actions workflows read the Go version from go.mod (go-version-file), so they need no change for Go itself
  • Test thoroughly as Go upgrades can introduce breaking changes
  • Multiple components use Go: CLI, Control Plane, and Artifact CAS

When not to use it

  • →Updating the dagger module go.mod file
  • →Updating Atlas versions without verifying availability via curl

Prerequisites

Dockercurl

Limitations

  • →Requires manual confirmation of Atlas version availability
  • →Does not update the dagger module

How it compares

This tool automates the synchronization of Go versions across multiple project components and documentation, ensuring consistent digests and avoiding manual file editing.

Compared to similar skills

upgrading-golang side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
upgrading-golang (this skill)18moReviewIntermediate
update-go-version19moReviewBeginner
upgrade-deps05moNo flagsAdvanced
bazel-build-optimization146moNo flagsAdvanced

Try saying

Example prompts that trigger this skill in your AI assistant.

Search skills

Search the agent skills registry