> ## Documentation Index > Fetch the complete documentation index at: https://docs.amnify.ai/llms.txt > Use this file to discover all available pages before exploring further. # GitLab Permissions > How Amnify connects to a gitlab.com group with a service account you create, which projects it can reach, and how its token is stored and kept valid. ## How Amnify authenticates GitLab has no app installation to grant, so Amnify works in your group as a **service account you create**. You add that account to the projects Amnify may use, create an access token for it, and paste the token into Amnify once. From then on Amnify keeps the token valid by itself. Every action Amnify takes runs **as that service account**, so it can reach exactly the projects you added the account to, and nothing else in your group. You stay in control on the GitLab side: remove the account from a project, revoke its token or delete the account at any time. > [!NOTE] > > Amnify connects groups on **gitlab.com**, on the Free, Premium and Ultimate > tiers. Self-managed GitLab instances are not supported yet. ## Steps to connect **1. Create a service account in your group** In your top-level group, open **Settings > Service accounts** and add a service account, for example `amnify`. You need the Owner role in the group to do this. **2. Add it to the projects Amnify may use** In each project, open **Manage > Members**, invite the service account and give it the **Maintainer** role. Only projects the account is a Maintainer of are offered to Amnify. You can add it to a subgroup instead to cover every project in that subgroup. **3. Create an access token for the account** Back in **Settings > Service accounts**, open the account and add an access token with the **api** scope. Any expiry date works. Copy the token: GitLab shows it only once. **4. Paste the token into Amnify** In Amnify, open **Sources**, choose **Connect** on GitLab and paste the token. Amnify checks it with GitLab before storing anything, and tells you why if it cannot be used. **5. Select the projects** Amnify lists the projects the service account can reach, with nothing selected. Select the ones Amnify should work with and save. You can change the selection at any time. The token must belong to a service account: Amnify refuses a person's own access token. Use one service account for each top-level group. An account that has projects in more than one top-level group is refused, so that a source always means one group. ## What the service account needs | Requirement | Value | Why Amnify needs it | | - | - | - | | **Project role** | Maintainer | Read the code to assess it, deliver fixes as merge requests from a new branch, and receive the project's own push and merge request events. | | **Token scope** | `api` | Call the GitLab API and read repositories as the service account, and replace the token before it expires. | The account needs no role in the group itself. Projects you do not add it to stay invisible to Amnify. ## How the token is stored and kept valid * **Stored encrypted, never shown again.** Amnify encrypts the token before saving it. No screen and no member of your organization can read it back. * **Used only for your organization.** The token is tied to the organization that connected it and is only ever used for requests to gitlab.com. * **Never shown to an agent.** When an agent reads your code, it clones the project through a separate, encrypted credential store that holds a copy of the token and adds it only to requests to gitlab.com. The agent itself never sees the token. * **Replaced before it expires.** About a week before the token expires, Amnify asks GitLab for a replacement and stores that instead. You do not need to do anything. * **The value you pasted stops working.** GitLab revokes a token when it is replaced, so the token you copied is dead after the first replacement. Do not reuse it anywhere else. * **Replacements last 30 days.** If your group allows only a shorter lifetime, the replacement gets the lifetime GitLab assigns, and Amnify replaces it halfway through that instead. ## What Amnify does with selected projects A selected GitLab project is a repository like any other in Amnify: * **Code scanning.** Run a scan now or on a schedule from **Code**, and the initial scan covers your GitLab projects with the rest. * **Scans on push.** Turn on **Scan on push to default branch** for a project in **Code**, and every push to its default branch is scanned. Pushes to other branches are not. Pushes that arrive close together are scanned together. * **CVE monitoring.** Turn on **Re-scan on new CVE** for a project in **Code**, and its dependencies are checked hourly against newly published CVEs. See [Dependencies and CVE monitoring](#dependencies-and-cve-monitoring). * **Cloud findings traced to code.** When a cloud resource is misconfigured, Amnify looks for the infrastructure as code in your projects that defines it. * **White box penetration tests.** Choose GitLab projects as source repositories for a pentest application. Findings traced to code link to the file, lines and commit on GitLab. * **Fixes as merge requests.** A finding in a GitLab project, or a cloud finding whose resource is defined in one, offers **Create merge request**. See [Fixes as merge requests](#fixes-as-merge-requests). ## Fixes as merge requests **Create merge request** on a finding applies its fix on a new branch named `amnify/fix-` followed by a short id, pushes that branch as the service account, and opens a merge request from it into the project's default branch. The finding then shows the merge request's number, such as **Merge request !12 open**, and a link to review it in GitLab. * **One at a time.** While a merge request is being opened for a finding, or for any finding in the same cluster, Amnify does not start another, and it never opens a second merge request from a branch that already has one. * **Only from its own branch.** Amnify opens a merge request only from the branch the fix created, never from your default branch or another branch your project protects. * **Merged when you merge it.** When you merge the merge request in GitLab, the finding shows it as merged. Amnify hears about it from the project's webhook, and checks again every half hour in case a delivery was missed. * **Failures stay on the finding.** If the service account cannot reach the project, the project was deleted, or GitLab no longer accepts the token, the finding says so, and you can try again once it is fixed. A token GitLab stopped accepting is fixed with **Replace token**, as described in [When a source needs attention](#when-a-source-needs-attention). ## Dependencies and CVE monitoring A GitLab project is watched for CVEs the same way as any other repository: see [Dependencies and CVE disclosures](https://docs.amnify.ai/scanning/cve-disclosures.md). Amnify reads the project's dependencies from the manifest and lock files on its default branch, as the service account. That works on every GitLab tier: you do not need GitLab Ultimate, dependency scanning or a CI job, and nothing is added to your pipelines. The dependencies are read again on every push to the default branch, which reaches Amnify through the project's [webhook](#webhooks), at least once a day, and whenever you press **Check dependencies now** for the project in **Code**. A check you start runs in the background, and its results appear on the CVE Disclosure page within a minute or two. If Amnify cannot read a project, the CVE Disclosure page and the project's settings in **Code** say why, and the hourly check goes on matching the last dependencies it read. The usual reasons: | What you see | What to do | | - | - | | GitLab no longer accepts the access token | The source needs attention. [Replace the token](#when-a-source-needs-attention). | | GitLab refused Amnify access to the project | Check that the service account is still a Maintainer of the project. | | GitLab shows Amnify no project at that path | The project was deleted, or moved out of the group. See [When a project is no longer reachable](#when-a-project-is-no-longer-reachable). | | The project has no commits on its default branch yet | Push a first commit. The next read picks it up. | | The project is too large to list its dependencies | The project could not be read in the time allowed, or holds more dependency files than Amnify reads. Contact [support@amnify.ai](mailto:support@amnify.ai). | | Amnify could not read the project from GitLab | A temporary problem. Amnify tries again by itself. | ## Webhooks Amnify learns about pushes from a webhook on each selected project. It adds the webhook itself, as the service account, when you select the project, and removes it when you deselect the project or disconnect the source. You do not need to set anything up in GitLab. The webhook is named **Amnify** and sends push events, merge request events and comments. Amnify uses push events for scans and dependency reads, and merge request events to see when you merge a fix. Comments are subscribed ahead of merge request review, which is not available on GitLab yet, and are not read. Each webhook has its own **signing token**, so GitLab signs every delivery and Amnify accepts only deliveries signed for that project. The token itself never travels with a delivery, and a delivery more than five minutes old is refused, so a captured one cannot be replayed. The source on **Sources** shows how many webhooks are active and when Amnify last received a delivery. **Manage** opens each project's webhook, with a link to its page in GitLab. If a webhook is deleted in GitLab, or GitLab turns it off after failed deliveries, Amnify shows it as needing repair, and pushes to that project are not scanned until it is fixed. Choose **Repair** to put it back. If you would rather add the webhook yourself, owners and managers can use **Set up by hand**: 1. In the project's **Settings > Webhooks**, add a webhook with the URL Amnify shows, triggered by **Push events**, **Merge request events** and **Comments**. 2. Select **Generate signing token** and copy the token. GitLab shows it only once. 3. Paste the token into **Signing token** in Amnify and save. Once its deliveries arrive, the project shows as **Receiving**, and again as needing repair if a week passes with nothing from it. **Regenerate signing tokens**, for owners and managers, gives every webhook of the source a new signing token, and the old ones stop working at once. Amnify puts the new tokens on the webhooks it manages. A webhook it cannot update, such as one you added by hand, shows as needing repair until you generate a new token for it in GitLab and paste it into Amnify. ## When a source needs attention A GitLab source shows **Action needed** when Amnify can no longer use its token: someone revoked it, it expired before it could be replaced, or GitLab refused to replace it. Amnify stops using the source's projects until you act. To fix it, create a new access token for the same service account and choose **Replace token** on the source in Amnify. The new token must belong to the same group. ## When a project is no longer reachable Amnify stops using a selected project, and removes it from your selection, when the service account is no longer a Maintainer of it in the connected group. That happens when the account is removed from the project or its role is lowered, and also when the project is archived or moved out of the group. The source shows which projects were removed. Once the account can reach the project again, select it again in Amnify. Existing findings are kept. Renaming the group, or renaming or moving a project within it, changes nothing: Amnify follows groups and projects by their GitLab ids, not their names, and keeps their scans and findings. ## How access is scoped and revoked * **Scoped by membership.** Amnify sees the projects the service account is a Maintainer of, in the group you connected, and works only with the ones you select. * **Change the scope anytime.** Add or remove the account on a project in GitLab, or change the selection in Amnify. * **Disconnect anytime.** Disconnecting the source in Amnify removes its projects from Amnify, removes the webhooks Amnify added to them, and deletes the stored token. The service account and its token stay in GitLab: delete or revoke them there if you no longer need them. * **Revoke from GitLab.** Revoking the token or deleting the service account cuts off access immediately, whatever Amnify has stored. > [!WARNING] > > **What Amnify never does on GitLab** > > * **Never pushes to your default branch.** Changes only ever arrive as a merge request from a new branch. > * **Never merges its own merge requests.** You review and merge, and your branch protections and approval rules still apply. > * **Never touches projects the service account is not a member of**, and never asks for a role in your group. > * **Never asks for your own access token or password.** Access is a service account you create and can delete. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.