Troubleshoot Socket for GitLab

Fix the Socket GitLab app when the container restarts, webhook deliveries fail, or pushes don't create scans.

🧪
Socket for GitLab is in beta. Behavior may change between releases.

Start with the symptom you see. Most problems come from the network path between GitLab and the app, certificates, or token permissions.

Container keeps restarting at startup

At startup, the app calls GitLab with GITLAB_TOKEN and stops if the call fails. A bad or expired token logs GitbeakerRequestError: 401 Unauthorized. Every other failure logs only TypeError: fetch failed. To see the cause, run this command in the folder that holds socket-gitlab.env. It runs one request to GitLab from the app's image and prints the result. Leave out the -v line if you don't use an internal certificate authority.

docker run --rm --env-file socket-gitlab.env \
  -v "$PWD/internal-ca.pem:/certs/internal-ca.pem:ro" \
  socketdev/gitlab:VERSION node -e '
    fetch(process.env.GITLAB_INSTANCE + "/api/v4/version")
      .then(r => console.log("Reached GitLab: HTTP", r.status),
            e => console.log(String(e.cause || e)))
      .finally(() => process.exit())'

Replace VERSION with the tag of the app you run. The output points to the fix:

Output	Cause and fix
`Reached GitLab: HTTP 401`	Network, DNS, and certificates work. Check `GITLAB_TOKEN` and its expiry date.
`unable to get local issuer certificate`, or another certificate error	The container doesn't trust your GitLab's CA. See network and certificates.
`getaddrinfo ENOTFOUND`	The host can't resolve the name in `GITLAB_INSTANCE`. Check it for typos.
`connect ECONNREFUSED`, or another connect error	A firewall or the network path blocks the host from GitLab.

Webhook deliveries fail

Open the webhook in GitLab and check its recent events, or the error GitLab shows when you save the webhook. The response tells you what to fix:

Response in GitLab	Cause and fix
400, `headers must have required property 'idempotency-key'`	Your GitLab is older than 17.4. Upgrade GitLab.
400, `Unexpected webhook!`	`DISABLE_WEBHOOK_AUTO_SETUP` is `true`, but `GITLAB_WEBHOOK_SECRET` is missing.
403, `No valid x-gitlab-token`	The webhook's secret token doesn't match `GITLAB_WEBHOOK_SECRET`.
Saving fails with `Url is blocked: Requests to the local network are not allowed`	See Allow webhooks to the app's address.
Connection error or timeout	GitLab can't reach `EXTERNAL_WEBHOOK_URL`. Check the network path to TCP 5050.

Pushes create no scans

If the app is up but a push creates no scan, check these causes in order:

The project was created after the app started. Projects get a webhook only when the app starts, so run docker restart socket-gitlab.
The webhook delivery failed. See Webhook deliveries fail.
The commit has no supported manifest files, or projectIgnorePaths in the project's socket.yml covers them.

Messages in the app log

These log messages have known causes:

Message	Cause and fix
`Ignoring extra certs from /certs/internal-ca.pem`	The container started without the certificate mount. Recreate it with the `-v` line.
`CAUGHT: GitbeakerRequestError: Invalid url given`	GitLab refused the webhook URL. Allow the app's address, then run `docker restart socket-gitlab`.
`Push to unknown project id`	The project was created after the app started. Restart the app.
`409 Conflict: A diff scan with these before and after full scans already exists`	A known issue in 0.4.1 when GitLab sends a merge request event again. The first comment stays.
`has broader scopes than needed`	A token carries more scopes than its job needs. See Socket for GitLab permissions.

Repository links open GitLab.com

On scans from self-managed GitLab, the repository, branch, and commit links in the Socket dashboard point at gitlab.com. Open the project in your own GitLab instead.

Share logs with Socket

Get the app's log with docker logs socket-gitlab. Before you share it, remove token values: GitLab tokens start with glpat-, and Socket tokens start with sktsec_.