Connect GitLab
Keel reads one gitlab.com group, or one user namespace, once a day and runs six checks:
| Check | What passes |
|---|---|
| Two-factor authentication is enforced | A group requires two-factor authentication for all members. For a user namespace, the owner has it on and no one else is a project member. |
| Default branches accept changes only through merge requests | Each project’s default branch is protected, Allowed to push and merge is No one, and force push is off. |
| Merge requests require approval | Each project has an approval rule that requires at least one approval. Needs GitLab Premium or Ultimate. |
| No merge requests merged without approval | Every merge request merged into a checked branch in the last 90 days has at least one approval. |
| Secret detection runs in CI | Each project’s CI configuration includes GitLab secret detection. |
| Dependency scanning runs in CI | Each project’s CI configuration includes GitLab dependency scanning. Needs GitLab Ultimate. |
On a tier that does not offer a check, the check shows Unsupported rather than failing.
Keel checks up to 50 projects, most recently active first. With more, a check that would pass shows Warn until you name the projects to check.
Time: about 5 minutes.
Before you start
Section titled “Before you start”- In GitLab: you are an Owner of the group, or it is your own user namespace.
- In Keel: you are an owner or admin of the workspace.
Create the access token
Section titled “Create the access token”- Sign in to gitlab.com.
- Open Personal access tokens. This link fills in the name, description and scope. Without it: select your avatar, then Edit profile > Access > Personal access tokens.
- If a Generate token dropdown list is shown, select Legacy token.
- Token name:
keel-evidence. - Token description:
Keel evidence connector read-only. - Expiration date: up to 365 days from today. Blank also means 365 days. Set a reminder to rotate it.
- Scopes: select only read_api.
- Select Generate token, then copy the token. GitLab shows it only once.
On Premium or Ultimate you can use a group access token instead: in the group, select Settings > Access tokens, generate a token with the Owner role and only the read_api scope.
Connect it in Keel
Section titled “Connect it in Keel”- In Keel, open Integrations, find the GitLab card and click Connect.
- Under Credentials, fill in:
- Group or user path: the path after
gitlab.com/, for exampleacmeoracme/platform. - Access token: the token you copied.
- Projects to check (optional): paths relative to the group, separated by commas, as
projectorproject:branch. Leave blank to check every active project.
- Group or user path: the path after
- Click Save connection.
Evidence connector connected. Its credential is stored encrypted. means it worked.
See the first findings
Section titled “See the first findings”Open the Findings tab and click Collect now, or wait for the next daily run.
Fix a failing check
Section titled “Fix a failing check”| Check | Where to change it in GitLab |
|---|---|
| Two-factor authentication (group) | Group > Settings > General > Permissions and group features > Enforce two-factor authentication |
| Two-factor authentication (user) | Avatar > Edit profile > Account > Enable two-factor authentication |
| Default branches | Project > Settings > Repository > Protected branches: set Allowed to push and merge to No one and turn off Allowed to force push |
| Approval rules | Project > Settings > Merge requests > Merge request approvals > Add approval rule |
| Secret detection | Add - template: Jobs/Secret-Detection.gitlab-ci.yml under include: in .gitlab-ci.yml |
| Dependency scanning | Add - template: Jobs/Dependency-Scanning.gitlab-ci.yml under include: in .gitlab-ci.yml |
Troubleshooting
Section titled “Troubleshooting”| What you see | What to do |
|---|---|
| Check the connection details and try again. | The path has a typo, the token lacks read_api, or the token’s account is not a member of the group. For a user namespace, create the token from that account. |
| That source is already connected to another Keel workspace, so it was not connected here. | One GitLab group or user namespace can be connected to one Keel workspace. Disconnect it there first. |
| GitLab rejected the token. | The token expired or was revoked. Create a new one and reconnect. |
Rotate or remove access
Section titled “Rotate or remove access”- Rotate: create a new token, disconnect and reconnect in Keel, then revoke the old token on the Access tokens page.
- Remove: click Disconnect in Keel, then revoke the token in GitLab.