Proxies for GitLab: How to Configure Access for Teams and CI/CD Pipelines Seamlessly

GitLab is a popular platform for code storage and managing DevOps processes, used by thousands of teams worldwide. But what to do if access to GitLab is blocked at the provider level, corporate network, or even an entire country? Even worse is when the CI/CD pipeline fails in the middle of the night simply because the runner cannot reach the repository.

In this article, we will discuss how to set up a proxy for GitLab at the Git client, GitLab Runner, and corporate server levels — so that the entire team can work reliably from anywhere in the world.

Why a Proxy is Needed for GitLab: Real Scenarios

Before setting up a proxy, it is important to understand what specific problem you are solving. Situations vary, and this affects the choice of proxy type and how to connect it.

Scenario 1: GitLab is Blocked by the Provider or at the Country Level

In several countries and corporate networks, access to gitlab.com is restricted. A developer opens the terminal, types git pull — and receives a timeout. In this case, the proxy acts as an intermediary: traffic does not go directly to gitlab.com, but through an intermediate server in a country where there are no restrictions.

Scenario 2: Distributed Team in Different Countries

Imagine: part of the team works from Russia, part from Kazakhstan, and part from Europe. Each has different network conditions and restrictions. To ensure everyone works reliably and at the same speed, companies deploy a corporate proxy server through which all traffic to GitLab flows through a single channel.

Scenario 3: CI/CD Runner Cannot Access External Dependencies

GitLab Runner starts a pipeline, and at the npm install or pip install stage, everything fails — because the server running the runner is in a closed network without direct internet access. The proxy allows the runner to obtain external dependencies without granting full internet access to the entire server.

Scenario 4: Self-hosted GitLab Behind a Corporate Firewall

The company maintains its own GitLab server within the internal network. Remote developers need to connect to it. Instead of using a VPN for all traffic, a proxy can be set up just for GitLab traffic — this is faster and easier to manage.

Scenario 5: Traffic Monitoring and Auditing

Large companies route all traffic to repositories through a corporate proxy to log activity, control who pushes what, and block undesirable operations. This is a security requirement, not a way to bypass restrictions.

It is important to understand before setting up:

A proxy for GitLab may be required at three levels simultaneously: on the developer's machine (Git client), on the server with GitLab Runner (CI/CD), and on the GitLab server itself (if self-hosted). Each level is configured separately.

Which Type of Proxy is Suitable for GitLab

GitLab operates over HTTPS and SSH protocols. This immediately determines which types of proxies are applicable and which are not. Let's explore the options.

Type of Proxy	Protocol	Suitable for GitLab	When to Use
HTTP/HTTPS Proxy	HTTP, HTTPS	✓ Yes	Git over HTTPS, GitLab web interface
SOCKS5 Proxy	TCP (any)	✓ Yes (best option)	Git over HTTPS and SSH, CI/CD
SOCKS4 Proxy	TCP	~ Partially	Only if SOCKS5 is not available
Transparent Proxy	HTTP	✗ No	Not suitable — does not bypass restrictions

For working with GitLab, the optimal choice is SOCKS5. It operates at the TCP level, so it proxies both HTTPS connections (web interface, git clone over HTTPS) and SSH connections (git push/pull over SSH on port 22 or 443) equally well.

Residential vs Datacenter Proxies for GitLab

Here, it depends on the task. If the goal is to bypass GeoIP restrictions or obtain a stable IP for authentication, datacenter proxies will suffice — they are faster, cheaper, and provide low latency, which is critical when working with large repositories.

However, if your corporate IP has been blacklisted by GitLab (which can happen during aggressive scanning or after security incidents), then consider residential proxies — their IP addresses belong to real home users and are rarely blocked by platforms.

Setting Up a Proxy for the Git Client (Globally)

This is the most common scenario: a developer on their machine cannot connect to GitLab. The setup is done through the Git configuration itself — once, and it works for all repositories.

Option A: HTTPS Proxy for Git

If you are working with GitLab over HTTPS (the repository address starts with https://), execute the following in the terminal:

# Set HTTP proxy globally
git config --global http.proxy http://YOUR_PROXY_IP:PORT

# If the proxy requires authentication
git config --global http.proxy http://USERNAME:PASSWORD@YOUR_PROXY_IP:PORT

# For SOCKS5 proxy (recommended)
git config --global http.proxy socks5://YOUR_PROXY_IP:PORT

# Check that the setting has been applied
git config --global --get http.proxy

Option B: Proxy Only for gitlab.com (does not affect other repositories)

If you do not want the proxy to apply to all Git operations (for example, GitHub or Bitbucket work fine), you can set the proxy only for a specific domain:

# Proxy only for gitlab.com
git config --global http.https://gitlab.com.proxy socks5://YOUR_PROXY_IP:PORT

# Or for your self-hosted GitLab
git config --global http.https://git.yourcompany.com.proxy socks5://YOUR_PROXY_IP:PORT

Option C: SSH Through Proxy (for those working over SSH)

If you are cloning repositories over SSH ([email protected]:...), the proxy setup is done in the SSH config, not in Git. Open the file ~/.ssh/config and add:

# For Linux/macOS — through nc (netcat)
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand nc -X 5 -x YOUR_PROXY_IP:PORT %h %p

# For Windows — through connect.exe (Git for Windows)
Host gitlab.com
    HostName gitlab.com
    User git
    ProxyCommand connect -S YOUR_PROXY_IP:PORT %h %p

After setting up, check the connection with the command ssh -T [email protected]. If everything is set up correctly, you will see a welcome message from GitLab.

How to Disable the Proxy When It Is No Longer Needed

# Remove global proxy
git config --global --unset http.proxy

# Remove proxy for a specific domain
git config --global --unset http.https://gitlab.com.proxy

Proxy for GitLab Runner and CI/CD Pipelines

GitLab Runner is an agent that executes jobs from .gitlab-ci.yml. If the runner is in a closed network or on a server with limited internet access, the proxy needs to be set up separately. The developer's Git client settings will not help here — the runner operates on a different machine.

Method 1: Environment Variables in the Runner Configuration

Open the GitLab Runner configuration file (usually /etc/gitlab-runner/config.toml) and add environment variables in the [runners.env] section:

[[runners]]
  name = "my-runner"
  url = "https://gitlab.com/"
  token = "YOUR_TOKEN"
  executor = "shell"
  environment = [
    "HTTP_PROXY=http://YOUR_PROXY_IP:PORT",
    "HTTPS_PROXY=http://YOUR_PROXY_IP:PORT",
    "NO_PROXY=localhost,127.0.0.1,your-internal-domain.com"
  ]

After modifying the config, restart the runner: sudo gitlab-runner restart

Method 2: Variables in .gitlab-ci.yml (at the Pipeline Level)

If you are not the runner administrator or want to set up a proxy only for a specific project, add the variables directly in the pipeline file:

variables:
  HTTP_PROXY: "http://YOUR_PROXY_IP:PORT"
  HTTPS_PROXY: "http://YOUR_PROXY_IP:PORT"
  NO_PROXY: "localhost,127.0.0.1,.internal.company.com"

stages:
  - build
  - test
  - deploy

build:
  stage: build
  script:
    - npm install   # now it will go through the proxy
    - npm run build

Method 3: Variables in GitLab Project Settings (without committing to the repository)

The best way for sensitive data (proxy with authentication): go to Settings → CI/CD → Variables of your project and add the variables HTTP_PROXY, HTTPS_PROXY, NO_PROXY as protected (masked) variables. They will automatically be available in all pipelines but will not be visible in the logs.

Proxy for Docker Executor

If the runner uses the Docker executor, containers do not inherit the host's proxy settings by default. You need to either add the variables in config.toml in the [runners.docker] section or create a file /etc/systemd/system/docker.service.d/proxy.conf on the host with the runner:

[Service]
Environment="HTTP_PROXY=http://YOUR_PROXY_IP:PORT"
Environment="HTTPS_PROXY=http://YOUR_PROXY_IP:PORT"
Environment="NO_PROXY=localhost,127.0.0.1"

After this: sudo systemctl daemon-reload && sudo systemctl restart docker

Proxy for Self-hosted GitLab Server

If you administer your own GitLab server (installed via Omnibus or Helm), a proxy is needed for GitLab itself to access external services: sending notifications, connecting to external CI systems, uploading user avatars, integrating with Jira or Slack.

Configuration in gitlab.rb (Omnibus Installation)

Open the file /etc/gitlab/gitlab.rb and add or uncomment the following lines:

# Proxy for GitLab (Omnibus)
gitlab_rails['env'] = {
  "http_proxy" => "http://YOUR_PROXY_IP:PORT",
  "https_proxy" => "http://YOUR_PROXY_IP:PORT",
  "no_proxy" => "localhost,127.0.0.1,YOUR_INTERNAL_DOMAIN"
}

# If the proxy requires authentication:
gitlab_rails['env'] = {
  "http_proxy" => "http://USERNAME:PASSWORD@YOUR_PROXY_IP:PORT",
  "https_proxy" => "http://USERNAME:PASSWORD@YOUR_PROXY_IP:PORT",
  "no_proxy" => "localhost,127.0.0.1"
}

After modifying the config, apply the settings: sudo gitlab-ctl reconfigure

Setting Up Outgoing Connections via Admin Area

In GitLab 15.0+, it became possible to configure the proxy directly through the web interface: go to Admin Area → Settings → Network → Outbound requests. Here you can specify a proxy for outgoing webhooks and restrict the IP ranges that GitLab can access. This is useful for security — it prevents SSRF attacks through webhooks.

Organizing Access for the Entire Team Through a Proxy

When stable access to GitLab is needed for a team of 5–50 people, individual setup on each machine is not the best approach. Let's consider more scalable solutions.

Approach 1: Corporate Proxy Server

One proxy server (for example, Squid or 3proxy) is deployed with internet access. All developers configure Git to use this server. Advantages: centralized management, a single point of control, traffic logging is possible. Disadvantage: the server becomes a single point of failure.

Approach 2: Repository Mirror

GitLab supports repository mirroring. You can set up a self-hosted GitLab in the internal network as a mirror of gitlab.com. Developers work with the internal server, which synchronizes with the external one through the proxy. This reduces dependency on the quality of the proxy connection for each developer.

Approach 3: Automatic Setup via Dotfiles or Onboarding Script

For teams where each developer sets up their environment themselves, it is convenient to create an onboarding script that automatically writes the necessary Git settings. The script is stored in a corporate repository and is executed when setting up a new workplace.

#!/bin/bash
# setup-git-proxy.sh — to be run when setting up a new workplace

PROXY_HOST="proxy.company.com"
PROXY_PORT="3128"

echo "Setting up Git proxy for access to GitLab..."
git config --global http.https://gitlab.com.proxy "socks5://${PROXY_HOST}:${PROXY_PORT}"
git config --global http.sslVerify true
echo "Done! Check: git config --global --list | grep proxy"

Checklist for Team Deployment

• Determine if a proxy is needed at the developer, runner, or GitLab server level (or all three)
• Choose the type of proxy: SOCKS5 for maximum compatibility
• Configure NO_PROXY for all internal domains and services
• Check the operation of SSH keys through the proxy (a separate step!)
• Document the settings in the corporate wiki
• Create an onboarding script for new employees
• Set up monitoring for the availability of the proxy server

Common Issues and Their Solutions

Even after proper setup, sometimes things go wrong. Here are the most common problems and how to diagnose them.

Problem 1: SSL certificate problem: unable to get local issuer certificate

This error occurs when the proxy server (especially corporate) performs SSL inspection — replacing GitLab's certificate with its own. Git does not trust this certificate. Solution: add the corporate root certificate to the trusted ones.

# Temporary solution (for debugging, not for production!)
git config --global http.sslVerify false

# Proper solution: add the corporate certificate
git config --global http.sslCAInfo /path/to/corporate-ca-bundle.crt

Problem 2: Proxy works for HTTPS, but SSH does not

This is a classic situation: you set up http.proxy in Git, HTTPS cloning works, but SSH operations still do not go through. The reason: SSH traffic does not go through the HTTP proxy. You need to separately configure ~/.ssh/config as described in the Git client section.

Alternatively, switch to working with GitLab over HTTPS instead of SSH. To do this, change the remote URL:

# Check the current remote
git remote -v

# Change from SSH to HTTPS
git remote set-url origin https://gitlab.com/username/repo.git

Problem 3: CI/CD pipeline hangs at the repository cloning stage

The runner clones the repository directly from GitLab using a token. If the runner is behind a proxy, this cloning must also go through the proxy. Ensure that the HTTP_PROXY and HTTPS_PROXY variables are set in config.toml, not just in .gitlab-ci.yml — variables from the CI file are applied after cloning, not before.

Problem 4: Proxy works, but very slowly

If push/pull operations work but take 5–10 times longer than usual, the problem may lie in the bandwidth of the proxy server or its geographical location. For working with large repositories (100+ MB), it is important to choose a proxy with low latency and high bandwidth. Datacenter proxies are preferable in this case over residential ones — they provide a more stable channel.

Problem 5: Authentication through the proxy requires re-entering the password

If the proxy requires Basic authentication and Git prompts for the password each time, configure the credential helper:

# macOS — use Keychain
git config --global credential.helper osxkeychain

# Windows — use Windows Credential Manager
git config --global credential.helper manager

# Linux — cache for 1 hour
git config --global credential.helper "cache --timeout=3600"

Conclusion and Recommendations

Setting up a proxy for GitLab is a task that is solved at multiple levels simultaneously. A developer on their work machine only needs to write a couple of lines in the Git or SSH config. For CI/CD, environment variables need to be added to the runner's config or project settings. And for self-hosted GitLab — update gitlab.rb and reconfigure.

The main rules that will help avoid most problems:

• Use SOCKS5 — it works with both HTTPS and SSH
• Always configure NO_PROXY for internal services
• Do not disable SSL verification in production — add the corporate certificate
• For CI/CD, set the proxy in config.toml, not just in .gitlab-ci.yml
• Document the settings — a new developer on the team will thank you

If you are looking for a reliable proxy to organize stable access to GitLab from anywhere in the world, we recommend considering datacenter proxies — they provide high data transfer speeds and low latency, which is especially important when working with large repositories and intensive CI/CD pipelines. For teams that prioritize maximum anonymity or bypassing GeoIP restrictions, residential proxies with IPs of real home users will be suitable.