Skip to main content

​
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.
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

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.
  • 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

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.

​
Dependencies and CVE monitoring

A GitLab project is watched for CVEs the same way as any other repository: see Dependencies and CVE disclosures. 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, 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:

​
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.
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.