Install Socket for GitLab

Deploy the Socket GitLab app on a container host, connect it to one GitLab group, and confirm that pushes create scans. The app scans every project in the group and its subgroups.

Before you begin

Have the following ready:

• A container host with Docker that can reach your GitLab and api.socket.dev over HTTPS, and that GitLab can reach on TCP port 5050. If your GitLab uses an internal certificate authority or the host uses a proxy, see Socket for GitLab network and certificates.
• On self-managed GitLab, an administrator who has allowed webhooks to the app's address. See Allow webhooks to the app's address.
• A Socket organization used only by this app.
• The Owner role on the GitLab group, to create group access tokens.

Create a Socket API token

In the dedicated Socket organization, go to Settings > Integrations > API Tokens and create a token with every full-scans, diff-scans, and repo scope.

Find the GitLab group ID

On the group's page in GitLab, open the actions menu (three dots) and select Copy group ID.

Create the GitLab access tokens

Create the tokens under the group's Settings > Access Tokens. Put "socket" in each token name, because the app's merge request comments show the token's name as the author. Then choose one of two setups:

If you use GitLab.com Premium or Ultimate and the app manages webhooks, give GITLAB_TOKEN the Owner role, because the app manages a group webhook there. GitLab.com Free has no group access tokens: use a personal access token from a user with the Maintainer role on each project.

To register the webhook yourself, add it under the group's Settings > Webhooks on Premium or Ultimate, or on each project on Free. Use the address you'll set as EXTERNAL_WEBHOOK_URL, a long random secret token, and the Push events and Merge request events triggers. Every webhook must use the same secret.

Put each token's expiry date on a calendar. When a token expires, the app stops scanning and commenting.

Create the settings file

The app reads its settings from an environment file. This command creates one named socket-gitlab.env and restricts it to your user. Run it in an empty folder on the container host:

cat > socket-gitlab.env <<'EOF'
DATABASE_URL=postgres://socket:DB_PASSWORD@socket-gitlab-db:5432/socket-gitlab
SOCKET_ORG=SOCKET_ORG_SLUG
SOCKET_API_KEY=SOCKET_API_TOKEN
GITLAB_INSTANCE=GITLAB_URL
GITLAB_GROUP_ID=GROUP_ID
GITLAB_TOKEN=GITLAB_API_TOKEN
EXTERNAL_WEBHOOK_URL=WEBHOOK_URL
EOF
chmod 600 socket-gitlab.env

Replace the following:

• DB_PASSWORD: a password for the app's database. Use letters and digits only, so it fits in the URL.
• SOCKET_ORG_SLUG: the slug of the dedicated Socket organization, as it appears in its dashboard URL.
• SOCKET_API_TOKEN: the Socket API token.
• GITLAB_URL: your GitLab's base URL, such as https://gitlab.example.com. Without this line, the app connects to GitLab.com.
• GROUP_ID: the GitLab group ID.
• GITLAB_API_TOKEN: the api-scoped GitLab token.
• WEBHOOK_URL: the address GitLab calls, ending in /webhook/gitlab, such as http://socket-gitlab.example.com:5050/webhook/gitlab.

If you register the webhook yourself, or want clones to use the read-only token, append these settings:

cat >> socket-gitlab.env <<'EOF'
GITLAB_READ_TOKEN=GITLAB_CLONE_TOKEN
DISABLE_WEBHOOK_AUTO_SETUP=true
GITLAB_WEBHOOK_SECRET=WEBHOOK_SECRET
EOF

Replace the following:

• GITLAB_CLONE_TOKEN: the read_repository token. With it, the api-scoped token never reaches git clone.
• WEBHOOK_SECRET: the secret token you set on the GitLab webhook. Leave out this line and the DISABLE_WEBHOOK_AUTO_SETUP line if the app manages webhooks.

Start PostgreSQL and the app

Create a Docker network for the app and its database:

docker network create socket-gitlab

Start PostgreSQL 17 with a persistent volume. If you use your own PostgreSQL server, skip this step and set DATABASE_URL to its connection string.

docker run -d --name socket-gitlab-db --network socket-gitlab \
  --restart unless-stopped \
  -e POSTGRES_USER=socket -e POSTGRES_DB=socket-gitlab \
  -e POSTGRES_PASSWORD=DB_PASSWORD \
  -v socket-gitlab-db:/var/lib/postgresql/data \
  postgres:17

Start the app from the folder that holds socket-gitlab.env:

docker run -d --name socket-gitlab --network socket-gitlab \
  --restart unless-stopped -p 5050:5050 \
  --env-file socket-gitlab.env \
  socketdev/gitlab:VERSION

Replace the following:

• DB_PASSWORD: the same password as in DATABASE_URL.
• VERSION: a release tag from socketdev/gitlab on Docker Hub, such as 0.4.1. A pinned tag means the app changes only when you upgrade it.

At startup, the app runs its database migrations, sets up webhooks unless DISABLE_WEBHOOK_AUTO_SETUP is true, and creates a Socket repository for each project in the group. On the first start, the log can show connect ECONNREFUSED for port 5432 a few times while PostgreSQL initializes. The restart policy retries until the database is ready.

Verify the deployment

Check the health endpoint and the startup log:

curl -sS http://localhost:5050/health
docker logs socket-gitlab 2>&1 \
  | grep -iE "pg-boss started|listening|webhook configured|seeded|synced"

The health check returns {"statusCode":200,"status":"ok"}. These log lines confirm each part of the startup:

Then test both events:

1. Push a commit to any project in the group. Within a few seconds the log shows Found N manifest files, and the scan appears on the Scans page of the Socket dashboard.
2. Open a merge request that changes a manifest file and its lockfile. The app comments on it with the dependency changes and any alerts.

Add projects created after setup

The app finds the group's projects when it starts. On self-managed GitLab and GitLab.com Free, a project created later has no webhook and isn't scanned until the app restarts. Restart the app after you add projects:

docker restart socket-gitlab

To pick up new projects without a manual restart, schedule this command to run nightly. On GitLab.com Premium or Ultimate, the group webhook reports new projects and the app adds them without a restart.

Upgrade the app

The database and the settings file stay in place across upgrades. To upgrade:

1. Remove the running container with docker rm -f socket-gitlab.
2. Run the docker run command you used to start the app, with the new version tag and any certificate mount from Socket for GitLab network and certificates. The app applies new database migrations when it starts.

Settings reference

The app reads these settings from socket-gitlab.env:

Related topics

• Socket for GitLab network and certificates
• Socket for GitLab permissions
• Troubleshoot Socket for GitLab