> For the complete documentation index, see [llms.txt](https://docs.itoc360.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.itoc360.com/integrations/inbound-integrations/devops-and-ci-cd/gitlab-integration.md).
# GitLab Integration
[GitLab](https://about.gitlab.com/) is a complete DevOps platform that covers source code management, CI/CD pipelines, and project collaboration in a single interface. Through its built-in webhook system, GitLab can push pipeline status events to external systems like itoc360 the moment something changes — no polling, no delay.
### Prerequisites
* A GitLab account with at least one project
* A `.gitlab-ci.yml` file in your repository (required for pipeline events to fire)
* An ITOC360 source token for GitLab
### Navigating to Webhook Settings
Open your GitLab project. In the left sidebar, click **Settings** to expand the section, then select **Webhooks** from the list that appears.
The Webhooks page will show any existing hooks or an empty state if none have been configured yet.
### Adding the Webhook
Click **Add new webhook** to open the configuration form. Fill in the fields as follows:
* **Name:** Give it a recognizable name, such as `ITOC360`
* **URL:** Your ITOC360 webhook URL with the source token as a query parameter:
```
https://api.itoc360.app/functions/v1/events?token=
```
* **Secret token:** Leave empty — authentication is handled via the token in the URL
* **Trigger:** Scroll down and check **Pipeline events** only
Click **Add webhook** to save.
### Adding a CI Pipeline File
GitLab only fires pipeline events when the project has an active CI configuration. If your repository doesn't already have one, navigate to **Code → Repository** in the left sidebar.
Click the **+** button and select **New file**. Name the file `.gitlab-ci.yml` and add the following content:
```yaml
test-job:
script:
- echo "Hello itoc360"
```
Click **Commit changes** to save the file to the repository.
Once committed, GitLab will automatically trigger a pipeline run, which sends a webhook event to your ITOC360 endpoint.
### Verifying the Connection
After the pipeline runs, go back to **Settings → Webhooks**. You should see a success banner at the top confirming the hook was delivered, along with your webhook listed below showing **Pipeline events** and **SSL Verification: enabled**.
### How It Works
Every time a pipeline changes state in your GitLab project, ITOC360 receives a notification. The integration uses the `object_attributes.status` field to determine alert severity and whether to open or close an alert:
* **failed** pipelines create a HIGH priority alert
* **canceled** or **skipped** pipelines create a MEDIUM or LOW priority alert
* A pipeline reaching **success** resolves the existing alert for that branch
Alerts are correlated by project ID and branch name, so a failed pipeline on `main` and its eventual successful re-run are treated as the same incident lifecycle.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.itoc360.com/integrations/inbound-integrations/devops-and-ci-cd/gitlab-integration.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.