Connect GitLab

A GitLab connection lets Faustine read the projects it analyzes on GitLab.com. You create it in the Connect your code step when you create a Web Agent or create an API. The connection acts as the GitLab user who authorized it, and other agents and APIs in the workspace can reuse it.

What Faustine asks for

Faustine connects through OAuth and requests two scopes.

Scope	Used for
`api`	Listing your projects, branches and folders, reading files for the Advanced editor, and creating the push webhook that automatic updates need.
`read_repository`	Cloning the repository over HTTPS for analysis.

Faustine reads code and creates that one webhook. It does not push to your repositories.

Faustine stores the refresh token GitLab issues, encrypted, and exchanges it for a short-lived access token each time it needs to read.

To connect:

In the Connect your code step, select GitLab.
Select Connect GitLab. The browser goes to GitLab.
On GitLab, sign in as a user who can read the projects you want analyzed, and authorize Faustine.

GitLab sends you back to the wizard with the new connection selected. It appears under GitLab connections as OAuth with the user's name.

Pick a repository and branch

With a connection selected:

In Repository, select a project from the list. Projects inside subgroups are listed with their full path, such as group/subgroup/project. To type the path instead, select Enter owner/repo manually.
In Branch, select a branch. Faustine preselects the project's default branch. An empty branch also means the default branch.
For a monorepo, set the folder Faustine analyzes. The field is Frontend path for a Web Agent and API path for an API. Leave it empty for the repository root.

Automatic updates

When you turn on automatic updates for an agent, Faustine creates a push webhook on the GitLab project. See Keep the agent up to date.

Disconnect

To delete a connection, open the Connect your code step of a new Web Agent or a new API, select the provider, and select the delete button on the connection's row. A connection that a Web Agent or an API uses cannot be deleted until you connect them to another source. Faustine also removes the webhooks it created on your repositories.

You can also revoke the Faustine application in your GitLab user settings, under the applications you have authorized. Analyses of that connection's repositories then fail until you connect again.

Troubleshooting

Symptom	Cause	Fix
A project is not in the list	The GitLab user who authorized Faustine cannot read it.	Connect again as a user with access to the project.
The agent shows `Your GitLab connection predates auto-update and can't create the push webhook`	The connection was authorized before Faustine requested the `api` scope.	Select Re-connect and authorize again.
`Couldn't load repositories`	The authorization was revoked on GitLab.	Connect again.

Next steps

Connect your code: the rest of the step for a Web Agent.
Keep the agent up to date: update the agent on every push.
Upload a ZIP instead of a repository: analyze code without a connection.