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

# GitGuardian

> Connect GitGuardian to CloudThinker for secrets detection, incident investigation, and honeytoken monitoring across your code

Connect your GitGuardian workspace to enable CloudThinker agents to browse secret incidents, investigate exposed credentials, and monitor honeytokens across your repositories. GitGuardian authenticates with a **Personal Access Token (PAT)**; CloudThinker derives the right endpoint from your dashboard URL, so the same setup works for US, EU, and self-hosted instances.

***

## Supported platforms

| Platform                    | URL                                                             |
| --------------------------- | --------------------------------------------------------------- |
| **GitGuardian US (SaaS)**   | `https://dashboard.gitguardian.com`                             |
| **GitGuardian EU (SaaS)**   | `https://dashboard.eu1.gitguardian.com`                         |
| **GitGuardian Self-Hosted** | Your instance URL (e.g. `https://gitguardian.your-company.com`) |

***

## Prerequisites

* A **GitGuardian workspace** with access to the incidents you want to review.
* A **Personal Access Token** with the scopes for the data CloudThinker should reach.
* For honeytoken creation: a workspace **Manager** role.

<Info>
  A PAT inherits the scopes you grant it and the role of the workspace member who creates it. Mint it from a least-privileged member that still covers what CloudThinker needs.
</Info>

***

## Setup

<Steps>
  <Step title="Open GitGuardian">
    Sign in to your GitGuardian dashboard (US, EU, or your self-hosted URL).
  </Step>

  <Step title="Create a Personal Access Token">
    On the sidebar, click **Settings**, then go to **API → Personal Access Tokens** and click **Create token**:

    * **Name**: `cloudthinker`
    * **Expiration**: set a rotation window
    * **Scopes**: select the scopes for the data CloudThinker should access (start with `incidents`)

    Copy the token immediately — it is shown only once.
  </Step>

  <Step title="Add the connection in CloudThinker">
    Navigate to **Connections → GitGuardian** and enter:

    * **GitGuardian URL**: your dashboard or instance URL
    * **Personal Access Token**: the token you just created

    Click **Connect**. CloudThinker verifies the token and shows a **Connected** status.
  </Step>
</Steps>

<Warning>
  Copy the Personal Access Token immediately after creation. GitGuardian shows it only once, and you'll need to mint a new one if it's lost.
</Warning>

***

## Connection details

| Field                                    | Description                           | Example                             |
| ---------------------------------------- | ------------------------------------- | ----------------------------------- |
| **GITGUARDIAN\_URL**                     | GitGuardian dashboard or instance URL | `https://dashboard.gitguardian.com` |
| **GITGUARDIAN\_PERSONAL\_ACCESS\_TOKEN** | GitGuardian Personal Access Token     | —                                   |

<Note>
  CloudThinker derives the API endpoint from the URL, so US, EU, and self-hosted forms all work without extra configuration.
</Note>

***

## Required permissions

GitGuardian access is **scope-driven**: each PAT scope unlocks the matching family of capabilities. If a capability is missing, the token usually lacks that scope rather than the connection being broken.

Select the scopes for the data CloudThinker should reach. Start with `incidents` for incident triage and add others as needed.

| Scope           | Enables                                              |
| --------------- | ---------------------------------------------------- |
| `scanning`      | Run secret and security scans on content             |
| `incidents`     | Browse, inspect, and manage secret incidents         |
| `secrets`       | Access detected secrets and their occurrence details |
| `sources`       | List and inspect monitored sources (repositories)    |
| `custom_tags`   | Read and manage custom tags                          |
| `honeytokens`   | List and create honeytokens                          |
| `members`       | View and manage workspace members                    |
| `teams`         | View and manage teams                                |
| `audit_logs`    | Read workspace audit logs                            |
| `api_tokens`    | View and manage API tokens                           |
| `ip_allowlist`  | View and manage the IP allowlist                     |
| `health_checks` | Validate connection and token health                 |

<Tip>
  Grant only the scopes CloudThinker needs. Many scopes offer separate **read** and **write** access — pick read-only unless a write capability is required.
</Tip>

***

## Agent capabilities

Once connected, agents have scope-gated access to your GitGuardian workspace.

| Capability                 | Description                                                      |
| -------------------------- | ---------------------------------------------------------------- |
| **Incident browsing**      | List and inspect secret incidents, including status and severity |
| **Incident investigation** | Review exposed credentials, sources, and occurrences for triage  |
| **Honeytokens**            | List honeytokens and, with Manager role, create new ones         |
| **Token inspection**       | Report the connected token's scopes and capabilities             |

<Warning>
  Honeytoken creation changes workspace state. CloudThinker requires explicit [approval](/guide/approval) and a Manager-role token before any write runs.
</Warning>

### Verify the connection

```text theme={null}
@oliver verify the GitGuardian connection: confirm the token is valid and report which scopes it carries
```

### Example prompts

```text theme={null}
@oliver list open GitGuardian secret incidents and #alert on anything touching production repos
@oliver investigate the most recent secret incident and summarize the exposed credential and its sources
@oliver report which scopes the connected GitGuardian token carries
```

***

## Troubleshooting

<Accordion title="Some GitGuardian tools are missing">
  The PAT lacks the matching scope. Re-mint or update the token with the needed GitGuardian scope, then reconnect.
</Accordion>

<Accordion title="401 Unauthorized from GitGuardian">
  The PAT is invalid, expired, or revoked. Create a new Personal Access Token and update the connection in CloudThinker.
</Accordion>

<Accordion title="403 Forbidden from GitGuardian">
  The token's scope or workspace role is insufficient. Grant the required scope or workspace role. Honeytoken writes require the **Manager** role.
</Accordion>

<Accordion title="Wrong region or instance">
  Incidents appear empty or the endpoint can't be reached. Confirm the **GitGuardian URL** matches your workspace region (US, EU) or self-hosted instance.
</Accordion>

***

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Scope-driven access** — grant only the scopes CloudThinker needs; prefer read-only access where a scope offers it.
- **Manager role for writes** — reserve Manager-role tokens for setups that must create honeytokens; keep honeytoken creation approval-gated.

***

## Related

<CardGroup cols={2}>
  <Card title="SonarQube Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/sonarqube.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=b667e04fbb28aa908d4777071a5a7414" href="/guide/connections/sonarqube" width="24" height="24" data-path="images/icons/sonarqube.svg">
    Code quality and security scanning
  </Card>

  <Card title="Atlassian Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/atlassian.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=64fcf0381646a233832602a9086a14eb" href="/guide/connections/atlassian" width="24" height="24" data-path="images/icons/atlassian.svg">
    Track incidents as Jira issues
  </Card>
</CardGroup>