# Connect GitLab to EkLine Docs Agent

import { Steps, Aside } from '@astrojs/starlight/components';

Connect GitLab to EkLine so the Docs Agent can reference your merge requests, issues, and repository files when it generates and updates documentation.

GitLab connects with a GitLab access token. You add the token once at the organization level, and every member of your EkLine organization can then reference GitLab content in their Docs Agent sessions.

## Prerequisites

- An EkLine account with an organization. [Sign up](https://ekline.io) if you haven't already.
- A GitLab account with access to the projects you want EkLine to reference.
- Permission in GitLab to create an access token with the required scopes.

## Generate a GitLab group access token

A group access token covers every project in the group with a single token, so it's the recommended option when your organization has multiple projects. EkLine also accepts personal and project access tokens if you prefer to scope access differently. For full details, see the [GitLab group access tokens reference](https://docs.gitlab.com/user/group/settings/group_access_tokens/).

<Steps>

1. **Open the group's access tokens page in GitLab.**

   Go to the group you want EkLine to access, then navigate to **Settings > Access tokens**.

   <Aside type="note">
   You need the Owner role on the group to create a group access token.
   </Aside>

2. **Add a new token.**

   Click **Add new token** and enter a recognizable name, such as `EkLine Integration`.

3. **Set an expiration date.**

   Set the expiration as needed. EkLine tracks the expiration date and shows you when the token is close to expiring.

4. **Select a role.**

   Select the **Developer** role or higher. The role determines what the token can read across the group's projects.

5. **Select the required scopes.**

   Select both the `api` and `read_repository` scopes. The connection fails without both.

6. **Create and copy the token.**

   Click **Create group access token** and copy the generated token. The token starts with `glpat-`.

   <Aside type="caution">
   GitLab shows the token value only once. Copy it before you leave the page.
   </Aside>

</Steps>

## Connect GitLab in EkLine

<Steps>

1. **Open GitLab integration settings.**

   Go to your [EkLine Dashboard](https://ekline.io/dashboard) and navigate to **Settings > Organization > GitLab Integration**.

2. **Add your token.**

   Click the **Update Token** button. Paste your GitLab token into the **GitLab Token** field.

3. **Save the token.**

   Save your changes. EkLine validates the token, confirms the scopes, and stores it encrypted. When the connection succeeds, the status changes to **Token is set**.

   <Aside type="note">
   If you see the error "Invalid GitLab token", confirm that the token starts with `glpat-` and has both the `api` and `read_repository` scopes.
   </Aside>

</Steps>

## Select code repositories

After you connect a token, EkLine loads the GitLab projects the token can access.

<Steps>

1. **Find the Code Repositories section.**

   The **Code Repositories** section lists the GitLab projects available to the token.

2. **Select your projects.**

   Select the GitLab projects you want to use with the Docs Agent.

3. **Save your selection.**

   Save your changes to make the selected projects available in Docs Agent sessions.

</Steps>

## Configure the GitLab webhook

A webhook lets GitLab notify EkLine about events in your project, such as new merge requests and comments. After you add a token, EkLine shows the **Webhook Configuration** section with the values you need.

<Steps>

1. **Copy the webhook details from EkLine.**

   In the **Webhook Configuration** section on the GitLab integration settings page, copy the **Webhook URL** and the **Secret Token**.

2. **Open the webhooks page in GitLab.**

   In your GitLab project, navigate to **Settings > Webhooks** and click **Add new webhook**.

3. **Enter the webhook URL and secret.**

   Paste the EkLine webhook URL into the **URL** field, then paste the secret into the **Secret token** field.

4. **Select the triggers.**

   Enable these triggers: **Push events**, **Comments**, **Emoji events**, and **Merge request events**.

5. **Save the webhook.**

   Click **Add webhook**. GitLab now sends events to EkLine for that project.

</Steps>

<Aside type="tip">
Add the webhook to each GitLab project you want EkLine to monitor.
</Aside>

## Verify the connection

Confirm that the integration is ready:

- The token status shows **Token is set**.
- Your selected projects appear under **Code Repositories**.
- The **Webhook URL** and **Secret Token** appear in the **Webhook Configuration** section.
- A team member can reference a GitLab merge request or issue in a Docs Agent session and the agent fetches the content.

## Use GitLab content in the Docs Agent

After you connect GitLab, reference GitLab content directly in your prompts. The agent recognizes GitLab URLs and IDs automatically and pulls the details from your connected projects.

```text
Create a changelog entry based on this GitLab merge request:
https://gitlab.com/your-org/platform/-/merge_requests/42
```

```text
Update the authentication docs based on the changes in
GitLab issue #215.
```

```text
Document the new API endpoints by referencing the files
changed in merge request !87.
```

The agent accesses content using the permissions of the account that created the token. You can only pull content that account has permission to view.

<Aside type="note" title="Organization-level access">
GitLab connects at the organization level. Once a team member adds a token, any organization member can use the integration through the Docs Agent.
</Aside>

## Next steps

- [Docs Agent integrations](/agent/integrations) — see every source you can reference, including Slack, Notion, Jira, and Confluence.
- [Create documentation](/agent/create) — generate a draft from your connected sources.
- [Update and review](/agent/update-review) — refine and review documentation with the agent.

---

## Stuck?

Reply to your welcome email or contact support@ekline.io. We read every message.