Connecting repositories · Roko Platform Docs

Roko Platform works on code in the repositories you link to a project. Agents clone them, push branches and open pull requests, and the platform follows those pull requests to know when an implementation is done. This page shows how to connect a code host and link repositories.

Background

The platform supports three code hosts: GitHub, Azure DevOps and GitLab. Each needs a credential before you can link a repository on it:

Host	Credential	Scope
GitHub	A GitHub App, or a personal access token	One connection per client. Every project under the client uses it.
Azure DevOps	A personal access token per organization	Per project
GitLab	An instance address and an access token per top-level group	Per project. A self-managed instance works.

The platform encrypts every token before it stores it and never shows it again.

CredentialCode host

GitHub, Azure DevOps or GitLab.

ProjectLinked repository

The platform checks that it can read it.

Agents clone itAn agent run clones the repository, pushes a branch and opens a pull request.

Pull requests syncThe platform syncs linked pull requests every minute. Webhooks make it faster.

Implementations finishWhen every linked pull request is merged, the implementation is complete.

DORA analyticsPull requests and deployments feed the delivery metrics.

The GitHub connection belongs to the client. Azure DevOps and GitLab credentials belong to the project. One repository can be linked to several projects.

What the platform does with a repository

Use	What happens
Access check	The platform reads the repository through the host's API before it links it.
Agent runs	An agent lists the project's repositories with `list_repositories`, clones them and opens pull requests. The platform authenticates the agent's workspace, so the agent needs no token of its own. On GitHub, the token an agent gets covers only the project's repositories.
Pull request sync	The platform syncs the pull requests linked to change requests every minute. Webhooks deliver changes sooner. When every pull request linked to an implementation is merged, the implementation is complete.
Linking pull requests	A change request can link pull requests only from the project's repositories.
Analytics	The DORA metrics on the Analytics page read pull requests and deployments per repository.
Pull request commands	On GitHub, a comment such as `/roko help` on a pull request runs a platform command. This needs the webhook.

The working model is not stored in a repository. Every linked repository is a code repository.

Connect GitHub

Open the Code settings
Open the project's Settings page from the top bar, then select the Code tab. The GitHub tab is selected by default.
Choose the authentication method
Under GitHub authentication, in Repository access, choose one:
- GitHub App, the recommended method. Enter the App ID or client ID and the Private key. The Installation ID is optional, because the platform can discover it.
- Personal access token. A personal access token cannot be narrowed for reviewer agents, so use a GitHub App when reviewer runs need read-only access.
Save
Select Save repository access. The section shows Configured.
Add the webhook
Under Webhooks, copy the Webhook URL and add it as a webhook in GitHub. Select Generate one to create a secret, copy it and enter it in GitHub. The platform shows a generated secret only once. The webhook gives the platform pull request changes and /roko commands right away. It does not grant repository access.

Connect Azure DevOps or GitLab

Open the host's tab
On the project's Settings → Code page, select Azure DevOps or GitLab.
Enter the credential
Enter the Organization: the Azure DevOps organization, or the GitLab top-level group, as it appears in the repository URL.
- For Azure DevOps, enter a Personal access token with Code (read & write) and Service Hooks (manage).
- For GitLab, enter the GitLab instance URL and an Access token with the api and write_repository scopes.
Connect and test
Select Connect. Then select Test on the credential's row to confirm the host accepts the token.

Link a repository

Enter the repository
In the repositories section of the same tab, fill in Link a repository:
- GitHub: owner/name, or the repository's URL.
- Azure DevOps: the full repository URL.
- GitLab: the full project URL.
```
owner/name
https://dev.azure.com/organization/project/_git/repository
https://gitlab.com/group/subgroup/project
```
Link it
Select Link. The platform confirms it can read the repository, then adds it to the list with its default branch.
Check the sync
The row shows Synced and a time once the first sync runs. No live events means the webhook is missing, and the platform falls back to the one-minute sync. Last sync failed shows the host's error.

To unlink a repository, select the trash icon on its row, then Unlink. The platform refuses while pull requests from the repository are still linked to change requests.

Set the agent's git identity

Every commit an agent makes for the project carries this name and email. It applies on every code host. In Agent git identity on the Code tab, enter the Name and Email, then select Save identity. Until you set it, agents commit as the platform default.

Best practices

Use a GitHub App on GitHub. An app can give reviewer agents read-only access, and its tokens are scoped to the project's repositories.
Add the webhook. Without it, pull request state and /roko commands wait for the next sync.
Link only the repositories the project changes. Every agent run sees every linked repository, and a change request can link pull requests from any of them.
Give the agent identity a recognizable name. Reviewers can then tell agent commits from human commits in the history.
Give tokens the least scope that works. Use the scopes listed above, and one token per organization or group.