> ## Documentation Index > Fetch the complete documentation index at: https://benchgen.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Connect a git repository > Store a repository and an access token that may write to it, so benchmark versions can be recorded there. The token is checked against the git host before anything is stored, so a 201 means it really works: a token that can read but not write is refused with that reason, and so is one the host rejects. It is then held as ciphertext and is never returned by any endpoint but `use`. Connecting a repository you already have replaces its credential rather than adding a second entry. On GitHub use a fine-grained personal access token limited to that one repository with Contents read and write; on GitLab a project access token with the `api` scope. Requires the `repo:write` scope. Stores a repository and an access token that may write to it, so benchmark versions can be recorded there and private repositories become readable. The token is checked against the git host **before** anything is stored, so a `201` means the credential really works rather than that it was written down. A `400` says which of the three things went wrong: the host rejected it, it can read but not write, or it is a BenchGen `bgn_` token pasted in by mistake. ```bash theme={null} curl -X POST "https://api.benchgen.com/api/git-connections/" \ -H "Authorization: Bearer $BENCHGEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"repo": "https://github.com/acme/benchmarks", "token": "github_pat_..."}' ``` ## Which token to create The narrow token is no harder to make and decides what a leak costs you. > **GitHub** > > A **fine-grained personal access token**, under Developer settings. Limit it > to the one repository, give it **Contents: read and write**, and set an > expiry. A classic token with the whole `repo` scope also works, and reaches > every repository you can see, which is the reason not to use one. > **GitLab** > > A **project access token** on that project, with the `api` scope and at > least the Developer role. A personal access token works too and, again, > reaches everything you can see. ## What happens to the token It is encrypted before it is stored, with a key held in the environment rather than in the database, so a database dump on its own does not reveal it. After that it is returned by exactly one endpoint, [read back a stored credential](/docs/api-reference/endpoint/use-git-connection.md), which needs the separate `repo:use` scope. Listing connections shows only a hint such as `ghp_...1122`. > [!WARNING] > > A token you paste into a chat message stays in that conversation's history, > wherever it is stored, no matter what the platform does with it afterwards. > If you connected a repository by chatting with the BenchGen AI agent, create a > replacement token, connect again, and revoke the first one. ## Reconnecting Connecting a repository you already have **replaces** its credential instead of adding a second entry, so there is never a question about which token is current. That is how you rotate one: connect again with the new token, then revoke the old one on the git host. ## Related > **[Read back a credential](/docs/api-reference/endpoint/use-git-connection.md)** > > The one endpoint that returns it, and why it is separate. > **[Check a credential](/docs/api-reference/endpoint/check-git-connection.md)** > > Whether it still works, before you rely on it. > **[Create from a repository](/docs/api-reference/endpoint/create-benchmark-repo.md)** > > Build a benchmark from a folder, now including a private one. > **[Version a benchmark](/docs/skills/version-a-benchmark.md)** > > What the agent does with a connected repository. ## OpenAPI ````yaml POST /api/git-connections/ openapi: 3.0.3 info: title: BenchGen Platform API version: 1.0.0 description: >- One API for the whole BenchGen platform: model catalogue and serving, fine-tuning and benchmarks, datasets (knowledge), and billing. ## Authentication Every request uses the same credential: a platform API token sent as `Authorization: Bearer bgn_...`. Create tokens in the web app under Profile Settings > Platform API tokens (the secret is shown exactly once), or via `POST /api/tokens/` with an interactive session. Revoking a token disables it platform-wide within 60 seconds. ## Scopes A token carries scopes chosen at creation; a request outside the token's scopes gets `403` with an explanatory message. | scope | grants | |---|---| | `models:read` | read model catalogues, job status, logs, GPU info | | `models:write` | deploy, train, merge, stop models and jobs | | `benchmark:read` | read benchmark runs and results | | `benchmark:run` | launch benchmark runs | | `benchmark:create` | create benchmarks in your account (drafts, Excel, bundles, specs); counts toward the creation limit | | `benchmark:manage` | edit and delete benchmarks you own or collaborate on | | `benchmark:publish` | publish and unpublish benchmarks you own or collaborate on | | `knowledge:read` | read your datasets and fine-tuning data | | `knowledge:write` | create, edit and delete datasets and fine-tuning data | | `billing:read` | read your balance and usage | | `agents:chat` | chat with your own agents through the API | | `agents:manage` | manage your agents, knowledge bases and channels | | `admin` | everything the account can do (staff accounts only) | ## For agents This document plus `/api/llms.txt` are the machine-readable entry points. Responses are JSON. Errors use conventional status codes; the body carries `error` or `message`. Knowledge endpoints return `[{"data": [...], "meta": {...}}]`. The complete auto-generated schema of every endpoint (including internal ones) lives at `/api/public-docs.json` (Swagger 2.0); this document is the curated, stable, supported surface. contact: url: https://benchgen.com servers: - url: https://api.benchgen.com security: - platformToken: [] tags: - name: auth description: Token introspection for services and integrations - name: tokens description: Manage your platform API tokens - name: models description: Model catalogue and serving - name: finetune description: Fine-tuning jobs, inference deployments, GPUs - name: knowledge description: Datasets and fine-tuning data (knowledge API) - name: billing description: Balance and usage - name: agents description: Chat with your agents (OpenAI-compatible facade) - name: benchmark description: Public benchmark (competition) listings. paths: /api/git-connections/: post: tags: - git summary: Connect a git repository description: >- Store a repository and an access token that may write to it, so benchmark versions can be recorded there. The token is checked against the git host before anything is stored, so a 201 means it really works: a token that can read but not write is refused with that reason, and so is one the host rejects. It is then held as ciphertext and is never returned by any endpoint but `use`. Connecting a repository you already have replaces its credential rather than adding a second entry. On GitHub use a fine-grained personal access token limited to that one repository with Contents read and write; on GitLab a project access token with the `api` scope. Requires the `repo:write` scope. requestBody: required: true content: application/json: schema: type: object properties: repo: type: string example: https://github.com/acme/benchmarks description: >- The repository address. A browse URL works too, and its branch is read from it. token: type: string format: password description: >- An access token that may write to that repository. Stored encrypted, never returned here. branch: type: string example: main description: Defaults to the branch in the URL, else main. name: type: string description: A label for your own use. required: - repo - token responses: '201': description: Connected, and the credential was checked. content: application/json: schema: type: object properties: valid: type: boolean connection: type: object properties: id: type: integer name: type: string repo: type: string example: https://github.com/acme/benchmarks host: type: string example: github.com branch: type: string example: main token_hint: type: string example: ghp_...1122 description: >- Enough to tell two credentials apart. Never the credential. is_default: type: boolean created_at: type: string format: date-time last_used_at: type: string format: date-time nullable: true last_checked_at: type: string format: date-time nullable: true last_error: type: string security: - PlatformToken: [] components: securitySchemes: platformToken: type: http scheme: bearer bearerFormat: bgn_ opaque token description: >- Platform API token created under Profile Settings > Platform API tokens. Scopes are fixed at creation. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.