GitLab + AWS CodeBuild: managed runners with access to your VPC

One of the recurring challenges in continuous integration appears when build and test processes need to reach resources inside our VPC (internal services, private APIs) that are not accessible from the internet. A typical case: integrating with tools such as SonarQube hosted on private networks.

Traditionally, the solution meant using custom CI agents — for example GitLab runners hosted on EC2 instances. That strategy works, but it carries operational overhead: managing the EC2 instances, monitoring availability and performance, applying security patches, and handling scaling.

A simpler alternative arrived with AWS CodeBuild and its ability to act as a managed GitLab runner with access to your VPC resources. Let’s see how to set it up.

1. Create the connection between GitLab and CodeBuild

The first step is to connect the GitLab account with AWS Code services. We look for the CodeBuild service in the console.

1. In AWS CodeBuild, go to Settings → Connections and click Create Connection.
2. Select GitLab as the provider, enter a name for the connection, and click Connect to GitLab.
3. Authorize the connection in GitLab by clicking Authorize AWS Connector for GitLab.
4. Click Connect.
5. The connection is ready and visible in the Connections list.

2. Create a CodeBuild project

We configure a CodeBuild project that uses GitLab as the source code provider:

1. In the navigation bar, Build → Build Projects → Create build project.
2. Enter a name for the project (in this example we call it gitlab-runner).
3. In the Managed default source credentials section, select GitLab as the Source Provider.
4. The first time, you need to configure the connection: click Managed default source credentials.
5. Select the CodeConnection configured in the previous step and click Save.
6. Select the GitLab repository you want to work with.
7. In Primary source webhook events, select the option Rebuild every time a code change is pushed to this repository. For Event Type, choose WORKFLOW_JOB_QUEUED.
8. Leave the remaining settings as their defaults and click Create build project.

3. Create the pipeline in GitLab

Now we configure the pipeline in GitLab to run the CI/CD tasks using CodeBuild.

At the root of your GitLab repository, create a .gitlab-ci.yml file:

workflow:
  name: HelloWorld

stages:
  - build

build-job:
  stage: build
  script:
    - echo "Hello World!"
  tags:
    - codebuild-gitlab-runner-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME

Important: replace gitlab-runner with the name of your own CodeBuild project. The rest of the tag can stay as is — the variables $CI_PROJECT_ID, $CI_PIPELINE_IID, and $CI_JOB_NAME are assigned automatically by GitLab.

Example:

tags:
  - codebuild-my-project-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME

4. See the pipeline in action

Once the .gitlab-ci.yml file is saved, GitLab starts the pipeline. To verify:

• In GitLab, go to Build → Jobs inside the repository and select the newly created job to view the execution details.
• You can also check the execution in AWS CodeBuild by reviewing the project you created.

That’s it! With this setup, AWS CodeBuild handles GitLab’s CI/CD jobs while taking advantage of AWS-managed infrastructure.

Why make this change?

Aspect	EC2 self-managed runners	CodeBuild managed runners
Instance management	Manual (patching, scaling, monitoring)	Managed by AWS
VPC access	Yes, configurable	Yes, configurable
Billing	Per instance 24×7 (or spot)	Pay per build minute
Scaling	Spot Fleet or ASG	Automatic and instant
Maintenance	Significant operational overhead	Low

For teams with variable CI workloads (the common case), the CodeBuild model lowers total cost and frees the team from managing infrastructure. For very high, constant volume, solutions based on Jenkins + Spot Fleet remain competitive on unit cost.

How we apply this at Caleidos

For clients already running on GitLab who want to modernize their CI/CD, this architecture is usually the one with the least operational friction: native integration, VPC access, automatic scaling, and cost proportional to actual usage. Combined with Feature Flags in AppConfig and observability with Fluent Bit on EKS, it forms a modern DevOps platform on AWS.

Caleidos designs, implements, and operates end-to-end DevOps platforms as part of our DevOps & Automation service. Continuous operation with Caleidos Lens©.

Want to simplify your CI/CD platform? Let’s talk →