Socket for GitLab network and certificates

The Socket GitLab app receives webhooks from GitLab and makes outbound HTTPS calls to GitLab and Socket. Open these paths before you start the app, and set up certificates and a proxy if your network needs them.

Connections the app makes

The app needs these network paths:

Allowlist api.socket.dev by hostname. Its DNS name returns more than one address, and a client connects to any of them.

The container serves plain HTTP on port 5050. To receive webhooks over HTTPS, put the app behind your load balancer or reverse proxy and use that address in EXTERNAL_WEBHOOK_URL.

Allow webhooks to the app's address

Self-managed GitLab blocks webhook requests to local network addresses by default. If the app's address is an internal IP address or hostname, an administrator must allow it before you start the app:

1. In GitLab, select Admin, and go to Settings > Network.
2. Expand Outbound requests.
3. Add the app's hostname or IP address to Local IP addresses and domain names that hooks and integrations can access, and select Save changes.

Selecting Allow requests to the local network from webhooks and integrations also works, but it opens every local address to every webhook. The allowlist entry is the narrower change.

Trust an internal certificate authority

If your GitLab's certificate is signed by an internal certificate authority (CA), or a proxy inspects outbound HTTPS, the container must trust that CA. Without it, the app restarts in a loop at startup.

1. Save the CA certificate in PEM format, with any intermediate CA certificates and any inspection CA, as internal-ca.pem in the folder that holds socket-gitlab.env.

2. Point two standard variables at the file. NODE_EXTRA_CA_CERTS covers the app's API calls, and GIT_SSL_CAINFO covers clones:

   Shell

   cat >> socket-gitlab.env <<'EOF'
   NODE_EXTRA_CA_CERTS=/certs/internal-ca.pem
   GIT_SSL_CAINFO=/certs/internal-ca.pem
   EOF

3. Mount the file by adding this line to the app's docker run command, above the image name. Keep it in the command every time you recreate or upgrade the container.

   Shell

     -v "$PWD/internal-ca.pem:/certs/internal-ca.pem:ro" \

GIT_SSL_CAINFO replaces git's default CA list. That works here because git connects only to your GitLab.

Route outbound traffic through a proxy

The app has no proxy setting of its own. If the host reaches the internet only through a proxy, append the standard proxy variables to socket-gitlab.env:

cat >> socket-gitlab.env <<'EOF'
https_proxy=PROXY_URL
no_proxy=GITLAB_HOST,socket-gitlab-db,localhost,127.0.0.1
NODE_USE_ENV_PROXY=1
EOF

Replace the following:

• PROXY_URL: your proxy's URL, such as http://proxy.example.com:8080.
• GITLAB_HOST: your GitLab's hostname, exactly as it appears in GITLAB_INSTANCE.

NODE_USE_ENV_PROXY=1 makes Node.js in the container send its API calls through the proxy, and no_proxy keeps GitLab and the database direct. Keep the variable names lowercase, because the app's error reporting library reads only the lowercase form. If the proxy inspects TLS, add its CA as described in Trust an internal certificate authority.

Related topics

• Install Socket for GitLab
• Troubleshoot Socket for GitLab