Repositories
Add the GitHub and GitLab repositories the agent reads, choose the key each one uses, and give each token the right permissions.
The agent reads your code to work out what went wrong. Code lists the GitHub and GitLab repositories it may read for this platform.
While it investigates, the agent only reads. It never pushes, and never changes anything. If code fixes are switched on and someone approves a fix, Cerberius Agents opens a pull request (GitHub) or merge request (GitLab) for your team to review. It is merged only if an approver asks for it in the chat.
The label at the top of the page says how it stands:
- Add a repository: there are none yet.
- … without a key: that many repositories have no key, so the agent may not be able to read them.
- … repositories: every repository has a key.
Before you start: a key#
Each repository is read with a GitHub or GitLab key from your organisation's key library. Add the key first, under Organisation › Keys. See Keys.
The permissions the key needs depend on what you want the agent to do.
GitHub#
Use a fine-grained personal access token. Under Repository access, choose Only select repositories and pick the repositories you'll add here.
| What you want | Repository permissions |
|---|---|
| Read the code (investigations) | Contents: Read-only. GitHub adds Metadata: Read-only by itself. |
| Also open pull requests for approved fixes | Contents: Read and write and Pull requests: Read and write |
| Also see your build pipelines (optional) | Add Actions: Read-only. The agent can then tell you whether a build passed or failed, and why. |
Organisation repositories
If the repositories belong to a GitHub organisation, the organisation may need to approve fine-grained tokens before they work. An organisation owner does this under the organisation's Settings › Personal access tokens.
GitLab#
Use a project access token or group access token, or a personal access token.
| What you want | Scopes | Role (project or group tokens) |
|---|---|---|
| Read the code (investigations) | read_repository and read_api | Reporter |
| Also open merge requests for approved fixes | api | Developer |
The agent downloads the code with read_repository. Check access asks GitLab's API about
the project, and the agent reads your CI pipelines' results, both with read_api (or api).
For your own GitLab server, set GitLab server on the key under Organisation › Keys.
Add a repository#
- 1
Go to Settings › Code.
- 2
Click Add repository. With no repositories yet, the button is in the middle of the page. If your organisation has no GitHub or GitLab key yet, the page asks you to add one first, and the button there is Add a GitHub or GitLab key. It opens Organisation › Keys.
- 3
The Add a repository box first asks where it is. Click GitHub or GitLab. The form then shows your choice at the top, with a Change link.
- 4
Type the repository's name.
- 5
Choose Key it reads with. Only keys for that provider are listed.
- 6
Describe it in What it is.
- 7
Click Add repository.
- 8
On the new row, click ⋯ and then Check access.
| Field | What it does |
|---|---|
| GitHub or GitLab (at the top) | Where the repository is: GitHub (github.com) or GitLab (gitlab.com or your own server). You chose it first. To choose again, click Change. Choosing the other one clears the key, because keys belong to one provider. |
| GitHub repository | The repository as owner/name, for example acme/shop-api. |
| GitLab project | The project as group/name, with any subgroups in between, for example acme/backend/shop-api. |
| Key it reads with | The GitHub or GitLab key from your key library, or None chosen. If there is no key for that provider yet, the box says so and links to Organisation › Keys. |
| What it is | A short description that helps the agent know where to look, for example Go API: orders, payments, invoices. |
Each repository can be added once per platform. Adding it again shows an error.
With your own runner
When the agent runs on your own runner, each repository's key is kept by you, not chosen from your key library. The Add repository box asks How its key is kept: Scrambled for your runner (you type it here, and your browser scrambles it so only your runner can unscramble it) or In your store (you put it on your runner's side and give us only its name). Your runner also opens the pull requests for fixes with it. To change the choice later, open the repository's Edit. See Two ways to keep your keys.
The table#
Each repository is one row.
| Column | What it shows |
|---|---|
| Repository | The name, then GitHub or GitLab and its description (No description yet if it has none). |
| Key | The name of the key it reads with, or None chosen. |
| Fixes | Allowed means the agent may propose code fixes in this repository. A person approves each one. Off keeps it read-only. New repositories start with fixes allowed. Whether the agent proposes fixes at all is set under Allowing changes. |
| Status | Readable, Can't read, No key or Not checked. See below. |
Check access#
Click ⋯ on a row, then Check access. Cerberius Agents asks GitHub or GitLab whether the key can read the repository. The result shows in the Status column:
- Readable, with whether the repository is private or public, and its default branch. The first successful check fills in the repository's default branch, which the agent reads.
- Can't read, with the reason:
- GitHub rejected the token. The token is expired or mistyped. Replace it under Organisation › Keys.
- Not found. The name is wrong, or the token can't see this repository. Check the name, and that the token includes this repository.
- GitHub refused access. The token is missing a permission.
- GitHub's rate limit was hit. Try again later.
- Choose a GitLab key for this repository first. Click ⋯, then Edit…, and choose a key.
- No key: no key is chosen, or the chosen key was removed from the library. The agent can't read a private repository without one.
- Not checked: nobody has checked it on this page yet. The default branch shows under it once it is known.
Run Check access again after you change a key or its permissions.
Change or remove a repository#
- Click ⋯, then Edit…. In the box that opens, change What it is, the key, or the Fixes allowed switch, then click Save.
- Click ⋯, then Remove, and confirm. The agent stops reading it. Tickets already investigated keep their history.
Write good descriptions
One clear line per repository saves the agent time and money. Say what it is and what lives in it: React dashboard for merchants: orders list, refunds screen, settings. Explain how the repositories fit together under About your system in Agent settings.
Code fixes#
When code changes are switched on, the agent can propose a fix in its analysis. If an approver
approves it, the agent edits one repository. Cerberius Agents then opens the pull or merge
request with the repository's key, never with anything the agent holds. Files that control
your build pipeline, such as .github or .gitlab-ci.yml, are never changed.
- Switch code changes on under Allowing changes.
- Keep Fixes allowed switched on for the repositories the agent may fix. Switch it off to keep a repository read-only, for example a shared library or your infrastructure repository.
- Give the key write permissions (see the tables above).
- See Approving a fix for what the approver sees.