> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parable.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Personal Access Token

> Connect Parable to GitLab using a personal access token

export const platform_1 = "GitLab"

export const limit_0 = "varies; typically 2,000 requests/minute for authenticated users"

export const platform_0 = "GitLab"

export const role_0 = undefined

export const tokenName_0 = "personal access token"

<Tabs>
  <Tab title="Setup">
    <Card title="What You'll Need" icon="key">
      | Credential   | What it is                                          |
      | ------------ | --------------------------------------------------- |
      | **Token**    | Personal access token with API scope                |
      | **Base URL** | `https://gitlab.com` or your self-hosted GitLab URL |
    </Card>

    ## Overview

    Connect Parable to GitLab for comprehensive DevOps and repository data.

    <CardGroup cols={2}>
      <Card title="Code & MRs" icon="code-branch">
        Projects, merge requests, commits
      </Card>

      <Card title="Issues & Planning" icon="list-check">
        Issues, milestones, labels
      </Card>
    </CardGroup>

    ## Prerequisites

    <Info>
      **Setup access in {platform_0}.** These steps require **{role_0}**, or a colleague with equivalent permissions who can create credentials for you.

      If that is not you, ask your {platform_0} administrator.
    </Info>

    * **Owner** or **Maintainer** role in the group/project
    * For group-level access, group owner permissions

    ## Setup Guide

    <Steps>
      <Step title="Access User Settings">
        1. Log in to GitLab (gitlab.com or your instance)
        2. Click your avatar → **Preferences**
        3. Navigate to **Access Tokens** in the sidebar
      </Step>

      <Step title="Create Personal Access Token">
        1. Click **Add new token**
        2. Fill in:

        | Field           | Value                  |
        | --------------- | ---------------------- |
        | Token name      | `Parable Integration`  |
        | Expiration date | 1 year (or per policy) |
      </Step>

      <Step title="Select Scopes">
        Enable these scopes:

        | Scope             | Purpose                     |
        | ----------------- | --------------------------- |
        | `api`             | Full API access             |
        | `read_api`        | Read-only API (alternative) |
        | `read_user`       | Read user information       |
        | `read_repository` | Read repository contents    |

        <Tip>
          For read-only integration, use `read_api` instead of `api`.
        </Tip>
      </Step>

      <Step title="Create and Copy Token">
        1. Click **Create personal access token**
        2. Copy the token immediately

        <Warning>
          **Copy your {tokenName_0} now!**

          This is the only time it will be displayed. Store it in a secure password manager before closing this page.
        </Warning>
      </Step>

      <Step title="Enter values in the form">
        1. **Token** and **GitLab URL**: Paste your personal access token and your GitLab instance base URL.
        2. Click **Save & test connection**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Reference">
    ## Verify Your Setup

    <CodeGroup>
      ```bash Test Authentication theme={null}
      curl -H "PRIVATE-TOKEN: YOUR_TOKEN" \
        "https://gitlab.com/api/v4/user"
      ```

      ```bash List Projects theme={null}
      curl -H "PRIVATE-TOKEN: YOUR_TOKEN" \
        "https://gitlab.com/api/v4/projects?membership=true&per_page=5"
      ```
    </CodeGroup>

    <Check>
      **Success!** If you received a `200 OK` response with valid data, your credentials are configured correctly. You can now proceed to configure this connector in Parable.
    </Check>

    <Tip>
      **Rate Limits:** {platform_1} enforces rate limits of **{limit_0}**.

      Parable handles rate limiting automatically with exponential backoff, but initial syncs of large datasets may take longer due to these limits.
    </Tip>

    ## Troubleshooting

    | Error              | Meaning               | Solution                                |
    | ------------------ | --------------------- | --------------------------------------- |
    | `401 Unauthorized` | Invalid token         | Verify token is correct and not expired |
    | `403 Forbidden`    | Insufficient scope    | Add required scope and regenerate       |
    | `404 Not Found`    | No access to resource | Check user has project/group membership |
    | `429 Rate Limited` | Too many requests     | Implement backoff                       |

    <Accordion title="Common Issues">
      ### Token expired

      GitLab PATs have expiration dates. Generate a new token with a longer expiration.

      ### Can't access group projects

      Ensure your GitLab user has at least Reporter access to the group.
    </Accordion>

    ## Additional Resources

    <CardGroup cols={2}>
      <Card title="GitLab API" icon="book" href="https://docs.gitlab.com/ee/api/">
        Official API documentation
      </Card>

      <Card title="Token Types" icon="key" href="https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html">
        Access token guide
      </Card>
    </CardGroup>
  </Tab>
</Tabs>