SigSentry Documentation

Connects one or more repositories on a single platform to the current project. Credentials are stored encrypted and used only when running analyses on this project.

For GitHub Apps and OAuth on GitLab/Bitbucket, the recommended path is to start the connection from the dashboard — the browser flow handles authorization for you. Use this endpoint when you already have a personal access token or app password and want to script the connection.

Authentication

API key with config:write permission. Project-scoped or tenant-scoped (with X-Project-Id).

Endpoint

POST /v1/config/repos

Request body

Field	Type	Required	Notes
`platform`	`'github' \| 'gitlab' \| 'bitbucket'`	✓	The source platform
`credentials`	object	✓	Platform-specific auth payload — see Credentials shape below
`repositories`	`string[]` (≥ 1)	✓	Repos to attach. Format: `owner/repo` for GitHub, `group/project` (or `group/subgroup/project`) for GitLab, `workspace/repo-slug` for Bitbucket
`serviceMappings`	array	—	Service-to-repo path mappings; see Service mappings
`lookbackDays`	int 1–365	—	How far back to search PR/MR history. Default 30

Credentials shape

The credentials object varies by platform and auth method.

GitHub — Personal Access Token:

{
  "platform": "github",
  "credentials": {
    "token": "ghp_..."
  },
  "repositories": ["acme/checkout-api"]
}

For GitHub Enterprise Server, add a baseUrl, e.g. "baseUrl": "https://github.example.com/api/v3".

GitLab — Personal Access Token:

{
  "platform": "gitlab",
  "credentials": {
    "token": "glpat-..."
  },
  "repositories": ["acme/checkout-api"]
}

For self-hosted GitLab, add "baseUrl": "https://gitlab.company.com".

Bitbucket — App password:

{
  "platform": "bitbucket",
  "credentials": {
    "username": "your-bitbucket-username",
    "appPassword": "..."
  },
  "repositories": ["acme/checkout-api"]
}

For OAuth-issued credentials (GitHub App, GitLab OAuth, Bitbucket OAuth), start the flow from the dashboard rather than POSTing tokens directly — the browser flow handles authorization and token refresh for you.

Service mappings

{
  "serviceMappings": [
    {
      "serviceName": "checkout-api",
      "repo": "acme/checkout-api",
      "pathPrefix": "src/",
      "defaultBranch": "main"
    }
  ]
}

Field	Required	Notes
`serviceName`	✓	The service name as it appears in your logs
`repo`	✓	One of the repos in `repositories`
`pathPrefix`	✓	Subdirectory inside the repo. Use `""` for the repo root
`defaultBranch`	✓	Branch analyses should reason about, e.g. `main`

Full example body

{
  "platform": "github",
  "credentials": { "token": "ghp_..." },
  "repositories": ["acme/checkout-api", "acme/billing-worker"],
  "serviceMappings": [
    { "serviceName": "checkout-api", "repo": "acme/checkout-api", "pathPrefix": "src/", "defaultBranch": "main" },
    { "serviceName": "billing-worker", "repo": "acme/billing-worker", "pathPrefix": "", "defaultBranch": "main" }
  ],
  "lookbackDays": 30
}

Response

201 Created

{
  "success": true,
  "data": {
    "id": "rc_x1y2z3...",
    "platform": "github"
  }
}

Use the returned id with PUT, DELETE, or invalidate-cache.

Error responses

Status	`error.code`	When
400	`VALIDATION_ERROR`	A field failed validation (unknown platform, empty `repositories`, `lookbackDays` out of range, malformed `serviceMappings`)
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Key lacks `config:write`
403	`QUOTA_EXCEEDED`	Repo-per-project quota for your plan reached — see Code Repositories → Quotas

Example

curl -X POST https://api.sigsentry.com/v1/config/repos \
  -H "Authorization: Bearer ss_secret_..." \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "github",
    "credentials": { "token": "ghp_..." },
    "repositories": ["acme/checkout-api"],
    "lookbackDays": 30
  }'

Idempotency

POST /v1/config/repos honors the Idempotency-Key header — see Idempotency.

POST /v1/config/repos

On this page