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

# GitGuardian

> Learn how to connect Opal to GitGuardian to manage workspace roles and team incident permissions.

With the GitGuardian integration, you can manage access to your GitGuardian workspace from Opal:

* Allow users to request just-in-time access to a workspace role, such as **Manager**, from the web and Slack
* Allow users to request access to a GitGuardian team's incidents, at the exact incident permission they need
* Set the right resource owners to delegate approvals to those with the most context
* Automatically revoke access when a time-bound grant expires

Opal connects to one GitGuardian workspace through a personal access token. To manage several workspaces, add a GitGuardian app in Opal for each one.

## Supported resources

| Resource | Read | Grant and revoke access |
| - | - | - |
| GitGuardian workspace roles | ✔️ | ✔️ (Revoke: Manager only) |
| GitGuardian teams (incident permissions) | ✔️ | ✔️ |

Opal syncs every active member of your workspace. The integration doesn't invite or remove members, which arrive through SSO or your identity provider, and it doesn't sync deactivated members, pending invitations, sources, or incidents.

### How GitGuardian access maps to Opal

* **Workspace roles**: your workspace appears in Opal as **GitGuardian Workspace**, with the access levels **Restricted**, **Member**, **Manager**, and **Owner**. Each member holds one role, so requesting a different role changes the existing one.
  * Revoking **Manager** returns the user to **Member**.
  * Opal doesn't revoke **Member** or **Restricted**, because GitGuardian has no lower role, so revoking them would mean deleting the user from the workspace. Remove users through your identity provider instead.
  * **Owner** is synced, but GitGuardian only lets the current Owner transfer ownership, in GitGuardian itself.
* **Teams**: each team appears in Opal as a **GitGuardian Team**, with the access levels **View incidents**, **Edit incidents**, and **Full access**. Each team member holds one incident permission, so requesting a different level on a team changes the existing one, and a team leader stays a team leader. Revoking a grant removes the user from the team, including team leadership. GitGuardian's built-in **All incidents** team isn't synced, because it can't be joined.
* **Managers on teams**: GitGuardian gives workspace Managers and Owners **Full access** on every team they belong to, and rejects other incident permissions for them. Managers already see every incident, so they don't need team access.

### Limitations

* Opal doesn't manage team leadership. Set team leaders in GitGuardian.
* Teams require a paid GitGuardian plan. On the free plan, GitGuardian blocks the teams API, and the app's sync fails.
* Because Opal can't revoke **Member** or **Restricted**, don't make those grants time-bound. Use time-bound access for **Manager** and for team access.
* Revoking **Manager** always returns the user to **Member**, even if they were **Restricted** before the grant.

## Requirements

Before you begin, you must:

* Be an Opal Admin
* Be a GitGuardian workspace Owner or Manager, on a plan that includes teams
* Ask the Opal team to enable the GitGuardian integration for your organization

## Configuration steps

### 1. Create a personal access token

1. In GitGuardian, go to **API** > **Personal access tokens**, and select **Create token**.
2. Name the token, for example `Opal`, and choose an expiration. When the token expires, Opal can no longer sync or change access, so set a reminder to replace it.
3. Select the following scopes:
   * `members:read`
   * `members:write`
   * `teams:read`
   * `teams:write`
4. Select **Create token**, then copy the token. GitGuardian shows it only once. You'll enter it in Opal in step 2.

The token acts as the user who created it. If that user stops being an Owner or Manager, Opal can no longer change access.

### 2. Create the GitGuardian app in Opal

In Opal, go to **Inventory** > **+App** and select **GitGuardian**. Fill in the following fields:

| Field | Value |
| - | - |
| App name | A name for the GitGuardian app in Opal, for example `GitGuardian`. |
| App admin | The owner who administers the app in Opal. |
| Description | A short description that helps requesters understand what this app is. |
| Visibility | Who in your organization can see the app. |
| Region | `api.gitguardian.com` for the US region, or `api.eu1.gitguardian.com` for the EU region. A token only works in its own region. |
| API token | The personal access token from step 1. |

Opal checks the API token when you save the app.

### 3. Import the workspace and teams

After you save the app, import the items you want to manage: on the app's **Assets** tab, select **Import assets**, choose **GitGuardian Workspace** and the teams, and turn on requests for them. Opal pulls access only for imported items, so roles and team members appear after the next sync.

## Troubleshooting

| Error | Fix |
| - | - |
| An authentication error when you save the app | Copy the token again, and check that **Region** matches the region you sign in to GitGuardian in. |
| The sync fails with a `403` error | Check that your workspace's plan includes teams, and that the token has the `members:read` and `teams:read` scopes. |
| An access change fails with a `403` error | Check that the token has the `members:write` and `teams:write` scopes, and that its creator is still an Owner or Manager. |
| A grant of team access to a Manager fails | GitGuardian doesn't allow team permissions for Managers, who already see every incident. No team access is needed. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.