Let’s preface this article with a little bit of context for those who’re new here. Incredibuild is a build acceleration product that installs alongside your existing CI setup, hashes compile, link, and test tasks, and either returns a cached result instantly or distributes the work across idle compute. It doesn’t replace GitHub Actions or any other CI platform; it sits underneath one.
This is written for teams whose GitHub Actions builds have gotten slow specifically because the codebase got large, not because the workflow is misconfigured. If a full build is still under 10 minutes, most of what follows won’t matter yet. If it’s climbing past 20 to 40 minutes on a monorepo with a few hundred thousand lines or more, this is the integration guide for that specific problem.
GitHub’s own 2025 Octoverse report (github.blog/news-insights/octoverse) found Actions minutes spent running tests up 35% year over year. None of that came with a matching bump in compute, and large codebases feel it first: more files means more that has to get recompiled somewhere every time a branch touches a shared header.
A quick methodology note: two integration paths are covered below, Build Runners (currently in Early Access) and the core Incredibuild agent installed on self-hosted runners. Pick the one that matches your setup; they solve the same problem differently.
Both paths described below apply the same underlying mechanism: a shared cache keyed on the actual inputs to a build step, and distributed compute for anything that isn’t already cached. Neither requires rewriting a workflow’s triggers, jobs, or overall structure. The change is scoped to how and where the build steps actually execute, which is why the setup itself, covered next, is short even though the codebases this is written for usually aren’t.
Before you start
You’ll need a GitHub Actions workflow already running, either on GitHub-hosted or self-hosted runners. For the core agent path specifically, you need self-hosted runners already registered, since the agent installs onto machines you control. For the Build Runners path, you need nothing extra beyond an Incredibuild account and EAP access, since the runners themselves are managed.
Language support matters here. The distributed compilation and caching underneath both paths works with C, C++, C#, and other compiled languages by default. Build steps that are pure test execution or interpreted-language work benefit mainly from the caching half, not the distribution half, worth knowing before expecting the same multiplier everywhere in a mixed-language pipeline.
Repository access is worth planning for too, particularly at larger organizations. Whichever path you pick, the agent or the managed runner needs the same checkout access your existing workflow already has; nothing new to grant there. What is worth flagging to a security team ahead of time: the core agent path installs software onto machines your organization controls, which typically needs a lighter review than a fully managed third-party runner, since nothing leaves infrastructure you already own. Build Runners, by contrast, means workload actually running on infrastructure Incredibuild manages, which is a different conversation for a security team even if the technical fit is identical; budget time for whichever review process applies before the first production rollout, separate from the technical setup itself.
One more thing worth checking before starting: how your build system currently handles incremental versus clean builds. If CI is already configured to run a full clean build on every trigger, as many pipelines are by default for reproducibility, that’s fine for this integration; the shared cache still applies. If CI is doing something unusual, like wiping and reinstalling a language toolchain on every run, that’s worth resolving first, since it will limit how much benefit either integration path can show.
Path A: Build Runners (fastest to set up)
This works today for GitHub Actions, GitLab CI, and Azure DevOps, and it’s the simpler of the two paths because there’s no infrastructure to stand up. The change is a one-line swap in an existing workflow file.
jobs:
build:
runs-on: incredibuild-runner
steps:
- uses: actions/checkout@v4
- name: Configure
run: cmake -B build -G Ninja
- name: Build
run: cmake --build build --parallelThat’s the entire change for a CMake-based project: runs-on: ubuntu-latest becomes runs-on: incredibuild-runner. Everything else in the workflow, the checkout step, the build commands, the triggers, stays exactly as it was. The runner itself carries more cores and faster storage than GitHub’s default pool, with Incredibuild’s caching active from the first build.
Path B: Core agent on self-hosted runners
If your CI platform isn’t one of the three Build Runners currently supports, or you’re already running self-hosted runners and want to keep that setup, install the agent directly onto the runner machines instead.
jobs:
build:
runs-on: [self-hosted, linux]
steps:
- uses: actions/checkout@v4
- name: Start Incredibuild agent
run: ibagent start
- name: Build through Incredibuild
run: ibconsole cmake --build build --parallelThe exact agent commands (ibagent and ibconsole above are illustrative) change between product versions, so confirm current flags against the installed agent’s own help output before scripting this into a production pipeline. The shape of it doesn’t change: install once per runner, then prefix your existing build command.
Which path fits your setup
| Build Runners (EAP) | Core agent on self-hosted runners | |
|---|---|---|
| Setup time | Minutes; one line changed | Longer; you manage the runner fleet |
| Works with GitHub-hosted runners | Yes | No, self-hosted only |
| Platform support today | GitHub Actions, GitLab CI, Azure DevOps | Any CI platform, including Jenkins and others |
| Who maintains the compute | Incredibuild | Your infra team |
| Best for | Teams already on GitHub-hosted runners wanting the fastest path | Teams already running self-hosted runners, or needing platforms outside the EAP |
Verifying it worked
The first build after switching won’t show much of a difference; there’s nothing in the cache yet. The second build on the same branch, or the first build on a second branch that shares files with the one just built, is where the difference shows up. Check the build log for cache hit statistics; a healthy setup on a large codebase typically shows a growing hit rate over the first few days as the shared cache fills in across branches and developers.
If the second build looks identical in duration to the first, the most common cause is a workflow step that invalidates the cache unintentionally, usually a clean step running before the build step that wipes intermediate artifacts Incredibuild would otherwise reuse. Removing an unnecessary clean step is often the single biggest fix at this stage.
Troubleshooting the first week
Cache hit rate stays near zero after several builds. Usually a clean step wiping artifacts before the build runs, or a build path that includes a timestamp or unique ID in a way that changes the cache key on every run even when the actual inputs haven’t changed. Check the build path configuration first.
Build time barely changes on the second run. Confirm the workflow is actually routing to the new runner label or picking up the agent; a leftover job in the same workflow still pointed at the old runner will make the whole pipeline look unchanged even if one step sped up.
Distribution isn’t spreading work across machines. Check how much idle compute is actually available at build time; a small self-hosted pool or a Build Runners tier sized for a smaller team will bottleneck on available machines before it bottlenecks on anything else.
Works on one workflow but not a second, similar one. Compare the two workflows’ build paths and toolchain versions directly; small differences here (a different compiler flag, a different working directory) are enough to keep the cache from recognizing that the two workflows are doing overlapping work.
Tuning for genuinely large codebases
Everything above works at any scale, but a few things matter more once a monorepo crosses a few hundred thousand lines or several hundred contributors.
Header hygiene affects the cache hit rate directly. A shared header pulled into hundreds of translation units means a one-line change to that header invalidates the cache for all of them at once, cache-friendly or not. This isn’t specific to Incredibuild; it’s the same reason header discipline matters for build time generally, but it shows up more visibly once a shared cache is doing the heavy lifting elsewhere.
Distributed compute scales with how much idle capacity is actually available to the agent, whether that’s Build Runners’ managed pool or your own self-hosted fleet. A team running one shared self-hosted runner and expecting monorepo-scale distribution will be disappointed; the distribution half of this needs multiple machines’ worth of headroom to spread work across, the same logic that applies to any distributed build system, not something specific to this integration.
Matrix builds, testing several OS or compiler combinations per commit, multiply the benefit and the setup effort together. Each matrix leg can share the same underlying cache if the inputs are genuinely identical across legs, but a matrix that varies compiler flags meaningfully across legs won’t see much sharing between them, since the cache is keyed on the actual inputs, not just the source files.
A mid-size fintech platform team we’ve talked with hit exactly this during their rollout: their first attempt showed almost no cache sharing because their matrix build varied a debug flag across every leg by default, a setting left over from an earlier debugging session nobody had removed. Once that flag was scoped down to only the legs that actually needed it, cache sharing across the rest of the matrix jumped immediately. The fix took an afternoon; finding it took most of a week, mainly because nobody thought to check a setting that had nothing to do with the integration itself.
Common mistakes during setup
The most frequent one: testing the integration on a small, fast-building sample repo instead of the actual large codebase it’s meant for. A five-minute repo won’t show a meaningful multiplier either way, and teams sometimes conclude the integration “didn’t do much” based on exactly the kind of build this guide says not to expect much from.
The second: rolling this out to every pipeline at once instead of one representative workflow first. Cache behavior, matrix interactions, and header-hygiene issues are all easier to diagnose against one pipeline you’re watching closely than across a dozen at the same time with no clear baseline.
The third: assuming a slow test-execution step will speed up the same way a slow compile step does. Test runtime, especially for suites that aren’t parallelized internally, benefits far less from this integration than compilation and linking do; a slow test suite calls for a different fix entirely.
The fourth: skipping the verification step because the setup itself completed without errors. A workflow that runs successfully with the new runner label or the agent installed isn’t the same as one that’s actually caching and distributing work; the two failure modes covered in the troubleshooting section above both produce a clean-looking build log with no errors at all, just no speed improvement either.
The honest limits of this integration
This doesn’t fix a workflow that’s slow because of queue time on a busy shared runner pool; that’s a concurrency problem, not a compute one, and it calls for more runners or a different concurrency tier, not caching. It doesn’t fix flaky tests, doesn’t reduce the size of a matrix build’s true combinatorial cost, and doesn’t do anything for steps that are already fast. If a workflow’s actual bottleneck is somewhere other than compile and link time, this integration will show a smaller improvement than the headline numbers below, or none at all.
The results teams report on codebases this integration was built for aren’t small. Adobe cut a build from 7.5 hours to 15 minutes (case study, incredibuild.com/case-studies). Cerence went from 15 minutes to seconds (case study, incredibuild.com/case-studies). Neither team rewrote their CI configuration beyond the runner or agent change covered above.
A word on cost, since it factors into which path makes sense before either one gets set up. Build Runners is billed as a managed service, no infrastructure to buy, but no infrastructure to amortize either, which tends to favor teams without spare compute sitting around. The core agent path has no separate compute cost beyond what a team already runs on its self-hosted fleet, but that fleet is the thing being sized and maintained, so the cost shows up as infrastructure and operational time rather than a subscription line. Neither is free; it’s a question of which column the cost shows up in.
It’s also worth naming that this isn’t the only way to attack the underlying problem. sccache and ccache handle compiler-level caching on their own, free and open source, without an organization-wide sharing layer. distcc and Icecream distribute compilation across machines without the caching half. Both are legitimate starting points for a team not ready to adopt a commercial layer, and both stop short of combining caching and distribution the way the two paths above do.
Future outlook
Build Runners’ platform coverage is the thing most likely to change in the near term; EAP support today covers GitHub Actions, GitLab CI, and Azure DevOps specifically, and expanding that list is a reasonable expectation over the next year given how the product is positioned. The core agent path already works everywhere, so that expansion mainly narrows the gap between the two paths rather than closing it entirely.
The more speculative possibility: as agent-driven development pushes commit volume higher across the industry (the same Octoverse and Stack Overflow trends covered elsewhere on this blog), the cache-hit economics this guide describes should improve on their own, since a larger, more active developer base sharing one cache produces more hits per build without any configuration change. That’s a reasonable expectation based on how the caching model works, not a guarantee specific to any one team’s results.
Worth watching from the other direction too: as AI coding agents start running their own build-and-test loops before a human ever sees a pull request, the caching layer described here starts serving two different consumers of the same cache, a human’s CI run and an agent’s pre-submission check, rather than one. Nothing about the integration changes to support that. It’s simply more traffic hitting the same shared cache, which is either a non-event or a capacity-planning question depending on how much of that agent activity a team ends up running.
Key takeaways
Two integration paths exist depending on setup: Build Runners for a one-line swap on GitHub-hosted workflows currently limited to three platforms, or the core agent for self-hosted runners on any platform. Both apply the same underlying fix, a shared cache plus distributed compute, to the same underlying problem: large codebases redoing the same compile and link work across branches and CI runs. Neither path requires restructuring the workflow itself, and both show their real effect starting on the second build, not the first, once the cache has something to actually reuse.
Start with one representative workflow rather than a full rollout, watch the cache-hit rate over the first few days, and check for the specific failure modes covered above (an unintended clean step, a stray debug flag varying across a matrix, a workflow still pointed at the old runner) before assuming the integration itself didn’t work. From there, a free trial or Build Runner Early Access is the fastest way to see the actual numbers against your own codebase rather than the ones cited here.
Dana Marsh is a Field CTO at Incredibuild focused on build acceleration, CI/CD performance, and software supply chain security. She spent over a decade as a build and release engineer in gaming and financial services before moving into developer advocacy.
