Send GitLab logs to LogPulse

The audit events of a GitLab group and its projects: members and roles, access tokens, protected branches, settings and sign-ins.

In short
To send GitLab logs to LogPulse, add GitLab under Configure → Sources → Cloud. LogPulse reads the GitLab audit events API itself, without an agent. Events land in the audit index with source gitlab and fill the Change data model.

Overview

How GitLab data reaches LogPulse
Vendor
GitLab audit events API
Collect
Integration pollerreads new events, maps the fields
Store
index=audit
  1. GitLab audit events API to Integration poller
  2. Integration poller to index=audit

LogPulse signs in to GitLab with the credential you give it and fetches new events every five minutes by default. You can set the interval per integration, from one minute to 24 hours.

What you need

  • GitLab Premium or Ultimate on gitlab.com or GitLab Dedicated
  • A token with read_api from an Owner of the group
  • In LogPulse: a role that may manage API keys. Cloud integrations fall under that right.

1. Create a credential in GitLab

Field in LogPulseWhere you find it
GitLab address (optional)Leave empty for gitlab.com. For GitLab Dedicated: your tenant, such as acme.gitlab-dedicated.com.
GroupThe path or ID of your top-level group. Its subgroups and projects are included.
Access tokenA group access token or personal access token with read_api, from an Owner of the group. Stored encrypted and never shown again.

2. Add the integration in LogPulse

Go to Configure → Sources → Cloud and choose GitLab. Fill in the fields, tick the data sources you want and save. LogPulse first tests the connection with your credential and tells you what is wrong when it fails.

Tip: Secrets are stored encrypted and never shown again. To change one, paste a new value; the rest stays.

What arrives

Data sourceIndexSourceSourcetypeWhat it holds
Audit eventsauditgitlabgitlab:audit:jsonChanges in the group and its projects: who, what, on which project or user, and from which address.

The index is the kind of data and the source is the product, so detection rules for that kind of data find GitLab without changes.

Note: Group audit events need GitLab Premium or Ultimate, on gitlab.com or GitLab Dedicated.

Fields and data models

Data modelWhat you get
ChangeWho changed what, on which project or user, from which address.

Field names follow the CIM field names. These are the fields LogPulse sets on GitLab events; a field is left out when GitLab did not send a value.

  • action
  • dest
  • id
  • object
  • object_category
  • object_id
  • object_path
  • result
  • signature
  • src_ip
  • user
  • user_id

The original record of GitLab is kept with each event under raw, so nothing the vendor sent is lost.

3. Check the data

The first events arrive within a few minutes. Check what came in:

earliest=-1h index IN (audit) source IN (gitlab)
| stats count by index, source, sourcetype

The integration page in LogPulse shows when it last read events and the last error, if any.

Troubleshooting

The connection test names what is wrong. These are the answers you are most likely to see.

What you seeWhat to do
GitLab refused the token. Check that it has not expired.Create a new group access token or personal access token with read_api.
The token needs read_api and the Owner role on the group. Group audit events need GitLab Premium or Ultimate.Create the token as an Owner of the top-level group. On GitLab Free there are no group audit events to read.
GitLab is read from gitlab.com or GitLab Dedicated (<tenant>.gitlab-dedicated.com)Self-managed GitLab cannot be read by this integration. Send its audit log file through the LogPulse agent.
The test passes but no events arrive.Run the search above over a longer time. No results: check on the integration page that the data source is switched on and when it last read events. GitLab may also simply have had nothing new.

Frequently asked questions

How do I send GitLab logs to LogPulse?
Add the GitLab cloud integration under Configure, Sources, Cloud in LogPulse and fill in Group, Access token. LogPulse reads the GitLab audit events API itself, every five minutes by default; there is nothing to install.
Which permissions does LogPulse need in GitLab?
GitLab Premium or Ultimate on gitlab.com or GitLab Dedicated. A token with read_api from an Owner of the group. Read access is enough for collecting logs.
Which index does GitLab data go to?
The index is the kind of data: audit. The source is the product: gitlab. Each data source has its own sourcetype, listed on this page.
Which data models does GitLab fill?
Change. Detection rules and dashboards written for a data model work on GitLab without changes.