Eurobase Source Connections API

openapi: 3.2.0
info:
  title: Eurobase Source Connections API
  version: 0.2.0
  description: Eurobase deployment control-plane API.
servers:
- url: https://api.eurobase.dev
tags:
- name: Source Connections
paths:
  /source-connections:
    get:
      summary: List the repositories linked to a workspace
      description: GitLab and Forgejo/Gitea repositories linked to the workspace, for any active member; canManage says whether the caller is the workspace owner. Never returns a token or a webhook secret.
      parameters:
      - in: query
        name: organizationId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Linked repositories
          content:
            application/json:
              schema:
                type: object
                required:
                - connections
                - canManage
                properties:
                  connections:
                    type: array
                    items:
                      $ref: '#/components/schemas/SourceConnection'
                  canManage:
                    type: boolean
        '400':
          description: organizationId missing (organization-id-required)
        '404':
          description: Not a member of this workspace (workspace-not-found)
      tags:
      - Source Connections
      operationId: getSourceConnections
      x-operation-id-source: derived
    post:
      summary: Link a GitLab or Forgejo/Gitea repository to a workspace
      description: 'Workspace owner only. The token must be read-only (GitLab: read_repository and read_api, no write-capable scope; Forgejo/Gitea cannot report scopes, so create it with read:repository only). A token that reads more than this repository needs acknowledgeAccountScope. The answer reveals the webhook URL and secret to add in the repository settings; projects can bind it at once; the first verified push (a commit or the provider test delivery) makes it active.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/SourceConnectionTokenRequest'
              - type: object
                required:
                - organizationId
                - url
                properties:
                  organizationId:
                    type: string
                  url:
                    type: string
      responses:
        '201':
          description: Repository linked, waiting for its first push
          content:
            application/json:
              schema:
                type: object
                required:
                - connection
                - webhook
                properties:
                  connection:
                    $ref: '#/components/schemas/SourceConnection'
                  webhook:
                    $ref: '#/components/schemas/SourceConnectionWebhook'
        '400':
          description: organizationId missing (organization-id-required)
        '403':
          description: Only the workspace owner can link repositories (source-connection-owner-required)
        '404':
          description: The token cannot read this repository (source-repository-not-found)
        '409':
          description: Already linked (source-connection-exists) or the token reads more than this repository and acknowledgeAccountScope is not true (source-token-account-scope-ack-required)
        '422':
          description: Unsupported URL (source-url-unsupported), host (source-instance-unsupported) or unreachable host (source-instance-unreachable); token rejected (source-token-rejected), write-capable (source-token-write-scope) or missing a scope (source-token-scope-missing); empty repository (source-repository-empty)
        '429':
          description: Too many links or token replacements by this user this hour
        '503':
          description: The provider limited or failed the request (source-provider-rate-limited, source-provider-unavailable); retryable
      tags:
      - Source Connections
      operationId: postSourceConnections
      x-operation-id-source: derived
  /source-connections/detect:
    post:
      summary: Detect the host of a repository URL
      description: Parses an https repository URL and detects without credentials whether its host runs GitLab or Forgejo/Gitea.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
      responses:
        '200':
          description: Detected provider, origin and repository path
          content:
            application/json:
              schema:
                type: object
                required:
                - provider
                - origin
                - repoPath
                properties:
                  provider:
                    type: string
                    enum:
                    - gitlab
                    - forgejo
                  origin:
                    type: string
                  repoPath:
                    type: string
        '422':
          description: Unsupported URL (source-url-unsupported), host (source-instance-unsupported) or unreachable host (source-instance-unreachable)
        '429':
          description: Too many detections by this user this minute
      tags:
      - Source Connections
      operationId: postSourceConnectionsDetect
      x-operation-id-source: derived
  /source-connections/{connectionId}/webhook:
    get:
      summary: Reveal the webhook URL and secret of a linked repository
      description: Workspace owner only, to set the webhook up or set it up anew. Never cached.
      parameters:
      - in: path
        name: connectionId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Webhook URL and secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceConnectionWebhook'
        '403':
          description: Only the workspace owner can link repositories (source-connection-owner-required)
        '404':
          description: Repository not found (source-connection-not-found)
      tags:
      - Source Connections
      operationId: getSourceConnectionsByConnectionIdWebhook
      x-operation-id-source: derived
  /source-connections/{connectionId}/token:
    put:
      summary: Replace the token of a linked repository
      description: Workspace owner only. Same checks as linking; the token must read the same repository. The connection is active again when its webhook was verified, otherwise it waits for its first push.
      parameters:
      - in: path
        name: connectionId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceConnectionTokenRequest'
      responses:
        '200':
          description: Token replaced
          content:
            application/json:
              schema:
                type: object
                required:
                - connection
                properties:
                  connection:
                    $ref: '#/components/schemas/SourceConnection'
        '403':
          description: Only the workspace owner can link repositories (source-connection-owner-required)
        '404':
          description: Repository not found (source-connection-not-found, source-repository-not-found)
        '409':
          description: The token reads another repository (source-connection-repository-mismatch), it changed meanwhile (source-connection-token-changed) or acknowledgeAccountScope is required (source-token-account-scope-ack-required)
        '422':
          description: Token rejected (source-token-rejected), write-capable (source-token-write-scope) or missing a scope (source-token-scope-missing)
        '429':
          description: Too many links or token replacements by this user this hour
        '503':
          description: The provider limited or failed the request; retryable
      tags:
      - Source Connections
      operationId: putSourceConnectionsByConnectionIdToken
      x-operation-id-source: derived
  /source-connections/{connectionId}:
    delete:
      summary: Unlink a repository from the workspace
      description: Workspace owner only. Refused while a project deploys from it. The token and webhook secret are wiped.
      parameters:
      - in: path
        name: connectionId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Repository unlinked
          content:
            application/json:
              schema:
                type: object
                required:
                - connection
                properties:
                  connection:
                    type: object
        '403':
          description: Only the workspace owner can link repositories (source-connection-owner-required)
        '404':
          description: Repository not found (source-connection-not-found)
        '409':
          description: A project still deploys from this repository (source-connection-in-use)
      tags:
      - Source Connections
      operationId: deleteSourceConnectionsByConnectionId
      x-operation-id-source: derived
components:
  schemas:
    SourceConnection:
      type: object
      description: A GitLab or Forgejo/Gitea repository linked to a workspace (ADR 0120). Never carries the token or the webhook secret.
      required:
      - id
      - provider
      - origin
      - repoPath
      - defaultBranch
      - status
      - credentialScope
      - credentialExpiresAt
      - lastDeliveryAt
      - webhookVerifiedAt
      - linkedProjectCount
      properties:
        id:
          type: string
          pattern: ^srcconn_[0-9a-f]{32}$
        provider:
          type: string
          enum:
          - gitlab
          - forgejo
        origin:
          type: string
          description: https origin of the repository host
        repoPath:
          type: string
        defaultBranch:
          type: string
        status:
          type: string
          enum:
          - pending_webhook
          - active
          - credential_rejected
          description: pending_webhook until the first verified push arrives (projects can already bind it); credential_rejected once the provider refused the token.
        credentialScope:
          type: string
          enum:
          - repository
          - account
          description: 'repository: the token reads only this repository; account: it reads every repository its account can read.'
        credentialExpiresAt:
          type:
          - string
          - 'null'
          format: date-time
        lastDeliveryAt:
          type:
          - string
          - 'null'
          format: date-time
        webhookVerifiedAt:
          type:
          - string
          - 'null'
          format: date-time
        linkedProjectCount:
          type: integer
          minimum: 0
    SourceConnectionTokenRequest:
      type: object
      required:
      - token
      properties:
        token:
          type: string
          minLength: 1
          maxLength: 512
          description: 'Read-only repository token: GitLab read_repository and read_api, Forgejo/Gitea read:repository.'
        acknowledgeAccountScope:
          type: boolean
          description: Required as true when the token reads more than this repository.
    SourceConnectionWebhook:
      type: object
      required:
      - url
      - secret
      properties:
        url:
          type: string
          description: Webhook URL to add in the repository settings
        secret:
          type: string
          description: 'Webhook secret: GitLab secret token or signing token, Forgejo/Gitea secret'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    sessionCookie:
      type: apiKey
      in: cookie
      name: __Host-eurobase_session
    csrfHeader:
      type: apiKey
      in: header
      name: X-Eurobase-CSRF