CI/CD setup for Go applications: cache, linter, cross-compilation

Setting up CI/CD for Go: where builds break

Setting up CI/CD for Go almost never runs into the compiler itself — the build bottleneck lies in the environment. The module cache and compiled package cache do not survive a run, so every pipeline run downloads dependencies again and builds everything from scratch.

A full build without cache on a mid-sized service takes tens of minutes: commit feedback arrives later than the engineer manages to switch to another task.

The second typical failure is environment divergence.

Locally there is one toolchain branch, on the build agent another, in the base image a third: the build passes on the developer's machine and fails on the agent, and the culprit turns out to be not the logic but the environment mismatch.

In this setup, the linter is either moved to a separate optional step or disabled entirely — checks are skipped during rushed branch merges.

Next come tests and cross-compilation. Checks that depend on run order or external services produce unstable results: the build fails, a repeated run passes, and the team gets used to pressing restart instead of investigating the cause.

Building for all target platforms on every commit multiplies time, although most branches need a single binary for one system.

The list is rounded out by manual deployment. While the image and binary are built on the engineer's machine, the version on the environment diverges from the commit, and rollback turns into searching for the previous artifact in chat.

We break down how this is addressed: portable build cache, a single toolchain in the image, selection of checks by critical paths, and automatic deployment by tag.

What a well-tuned CI/CD pipeline provides: cache and build matrix

Dependency cache and build cache are the first things that deliver a measurable effect. We build the cache key from module description files: as long as the dependency set has not changed, jobs pull ready modules and compilation objects, and only touched packages are rebuilt.

Build time drops from several minutes to tens of seconds, and change-based checks return almost immediately — in GitLab CI this is done declaratively, without homemade scripts.

The build matrix covers cross-compilation: the same code is built for the required target platforms at once, with static linking and cgo disabled, so the binary does not pull system libraries on the server.

Parallel jobs divide the work: linter, tests, and build run as separate jobs, the fastest check fails first — you fix it without waiting for the rest.

Reproducibility rests on pinned versions of the linter and base image: dependencies are pulled strictly by a fixed set of hashes, and the build runs in read-only mode.

The class of failures "works locally, not in the pipeline" goes away because local and server builds use the same toolchain version and the same set of modules.

Deployment stops depending on a person: the artifact gets a version tag and is promoted across environments without manual steps, and reverting to the previous release is switching to an already built binary, not rebuilding from changed code.

Build modes: full, incremental, matrix

The build mode is chosen not by preference, but by what changed between runs and how impactful an error from an outdated artifact is.

A full build from scratch guarantees reproducibility, incremental saves minutes on every commit, and matrix covers several target platforms and flag sets in a single run.

In practice, the modes are combined: incremental build on every commit, full before deployment, matrix on the release branch.

In GitLab CI this is described by run rules, cache scope, and job parallelism; we record such rules in the configuration so the result does not depend on who started the build and when.

Implementation stages: from repository audit to handover

We start with an audit because the order of work depends on what is already in the repository: how modules are laid out, what manages dependencies, which checks run now, and where the build most often stalls.

Then we proceed through stages — from pipeline design to handover of guidelines, so that after us the team can change it themselves rather than reverse-engineering someone else's logic from logs.

1. Repository audit. We review module structure, dependency files, failure history, and the time of each build stage. The output is a list of bottlenecks: where the cache does not work, which checks duplicate each other, and what takes up most of the time.
2. Pipeline design. We agree on the stages and their order: environment preparation, dependencies, static analysis, tests, build, artifact publication. Separately, we record which stages block a branch merge and which only signal.
3. Cache. We configure the module cache and the cache of intermediate build results separately, with keys based on the contents of dependency files. A repeated run without code changes no longer pulls everything again.
4. Linter and static analysis. We select a rule set for the codebase so that warnings are meaningful. New errors block the build; accumulated debt is added to an exception list.
5. Cross-compilation. We build for all target platforms with a single job matrix, with reproducible flags. Artifacts are named consistently so the release is not assembled by hand.
6. Build verification in the production environment. We run the pipeline on a real branch and on the release branch, check rollback to the previous artifact, and test behavior when external sources are unavailable.
7. Handover of guidelines. We provide a description of stages, rules for changing the pipeline, access separation, and instructions for typical failures. The team resolves such incidents without us.

Configurations, access policies, and build guidelines

After implementation, the client is left not with a set of verbal agreements but with a working framework by which the build can be reproduced without us. Below is a list of what we hand over along with separated access to repositories and the build system.

• Build configurations — pipeline description in the repository, versioned together with the code; separate profiles for working branches, release tags, and change-based checks.
• Branching scheme and run conditions — which branches run fast checks, which run the full pipeline, and what blocks a merge.
• Dependency and artifact cache — cache keys, cleanup policy, and retention of recent builds: the stage fits into minutes, and the registry does not grow indefinitely.
• Access policies — roles in the build system: who edits the configuration, who triggers deployment to the production environment, who can see the logs.
• Secrets and variables — separation by environment, storage in a secure vault, visibility scope, rotation, and access log.
• Cross-compilation matrix — target platforms, set of compilation parameters, unified procedure for releasing executables.
• Documentation — pipeline map, instructions for reproducing the build locally, and the procedure for rolling back to the previous release.
• Maintenance guidelines — frequency of updating dependencies and base images, rules for extending checks, areas of responsibility.

The package is structured so that the pipeline can be changed by your team: rules are in the repository, access is separated, and rollback is described. We remain available for support, but there is no hard vendor lock-in.

Case study: build time and failure rate before and after

What it was like before the overhaul

The Go application was built by a single job: dependencies were pulled from the network on every run, tests ran sequentially, binaries were built in place — the build took 14–18 minutes.

The network connection to the package repository periodically dropped, and every fourth build failed not because of code: the share of failures due to external causes held at 22–25%.

Engineers got used to restarting the pipeline "just in case," and deployment to the environment took about 40 minutes.

What we changed

We rebuilt it on GitLab CI: the module cache and step cache were moved to separate storage with a key based on dependency files — a repeated run no longer goes to the network.

The linter and tests were split into parallel jobs, and cross-compilation was moved to a build matrix with a shared tool cache.

External sources were covered by a package mirror, and build and image publication were separated so that a network failure would not bring down code checks.

What the result was

The build fits into 3–5 minutes for a typical change, the share of failures due to external causes is about 3%, and these are now real errors in code rather than timeouts. Time to deployment dropped to 8–10 minutes, and rollback to the previous release is one operation.

The class of failures "the build failed by itself" no longer exists: engineers stopped restarting the pipeline and again trust its red status.

How does incremental build differ from full build?

A full build compiles all project packages from scratch; an incremental build compiles only those changed since the previous run, taking the rest from cache.

On a large project the difference is noticeable: a full run takes tens of minutes, while an incremental one fits into single digits. That is why both modes usually live in the pipeline, and they switch by event type rather than by engineer preference.

Build reproducibility is the second thing that distinguishes the modes. A full build in a clean environment produces the same artifact on any machine: the cache will not slip in an outdated object file or a locally substituted dependency.

Incremental inherits the cache state, so the key must account for the compiler version, flags, and module tags — otherwise it will show success where a clean build would have failed.

Go is predictable here: the cache is keyed by source contents, flags, and environment, so false hits are almost impossible — but only with the same set of fields in the CI key.

The choice for the task is determined by the impact of an error. Where the artifact goes to production, extra minutes are a better trade-off than a wrong binary — a full build with cache reset is used.

Where a fast signal about a regression is needed, incremental works, and its risks are covered by a scheduled full run.

Cross-compilation for several platforms in both modes relies on separate caches per target platform: mix them up, and you get object files from the wrong system.

Limitations, compatibility, and common technical questions

Technical limitations in setting up CI/CD for Go applications become clear not in a demo but in the second week of work: the cache stops helping with parallel branches, cross-compilation unexpectedly requires a native environment, and tests that are green locally fail on agents. Below is an analysis of the doubts engineering teams most often come with.

How do you migrate from a legacy pipeline without stopping releases?

We migrate in stages: first builds and checks in the new pipeline, then artifact publication, while the old one remains operational until the first stable run.

We compare the results of the two pipelines on the same commits — a discrepancy in artifacts or coverage is visible immediately, not on the switchover day.

Is it realistic to build for several platforms with one command?

Yes, cross-compilation covers most targets without a separate machine for each. The target matrix defines a list of "operating system + architecture" pairs, artifacts are named by target platform, and the release is built in parallel. Native builds remain only where the code calls system libraries.

What should be done about flaky tests?

We do not silently disable an unstable test: we place it in quarantine with an owner and a review deadline, fix the random seed and run order, and move tests with races into a separate step with a detector. This keeps the main run predictable and does not lose the cause.

How is the configuration handed over after completion?

The build and deployment guidelines, description of environment variables, cache storage scheme, and list of steps with their purpose — in the repository next to the code.

We hold a walkthrough with your team: how to change steps, where to view logs of a failed run, and how to roll back a release.

Let's discuss the task: what to send for an estimate

An estimate works best based on facts, not on the description "we want CI/CD for Go." Below is the minimum set of inputs after which we name the scope of work, timeline, and plan, rather than a range "from and to." If something is missing, send it as is; we will remove some items during a call.

• Link to the repository and module map: where services and shared libraries live and how they depend on each other.
• Current build scenario: build files, scripts, environment variables — even if everything is currently built manually on the developer's machine.
• Target cross-compilation platforms: which operating systems and architectures the binaries are needed for and in what form they are expected at the output.
• Cache requirements: what we reuse between runs — module dependencies, linter results, intermediate build artifacts, where cache keys are stored.
• Linter set and strictness threshold: which rules are enabled, what is considered a blocking error versus a warning, who fixes debt in existing code.
• Where artifacts and images are stored, how delivery to environments currently looks, who has access to the registry and the deployment environment.
• Branching model and release frequency: how many builds per day, whether manual on-demand runs are needed, whether there is a split between quick checks and the full run.
• Current build time and bottlenecks: which steps take up most of the time, what is critical to speed up first.

Describe the task in free form and attach what you have from the list — we will get back with a timeline estimate and work plan: what we do in the first stage, what we move to the second, and how we verify the result on your real repository.