Eurobase GitHub API

openapi: 3.2.0
info:
  title: Eurobase GitHub API
  version: 0.2.0
  description: Eurobase deployment control-plane API.
servers:
- url: https://api.eurobase.dev
tags:
- name: Github
paths:
  /github/connect-url:
    get:
      summary: Get next GitHub connect URL
      description: Returns from DB-backed account/install snapshot truth. This endpoint must not refresh live GitHub installations or repositories on the click path.
      parameters:
      - in: query
        name: returnTo
        required: false
        schema:
          type: string
          format: uri
        description: Optional loopback or configured web-app base URL to restore after the GitHub callback.
      - in: query
        name: returnPath
        required: false
        schema:
          type: string
        description: Optional app-relative GitHub return route. Only /app/github with a project deployments next path is accepted.
      responses:
        '200':
          description: Connect URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GitHubConnectResponse'
        '409':
          description: GitHub connect blocked by operator-side control-plane configuration
      tags:
      - Github
      operationId: getGithubConnectUrl
      x-operation-id-source: derived
  /github/access-target/{token}:
    get:
      summary: Resolve an opaque GitHub access target
      description: Validates a short-lived server-stored access-target token and redirects to the corresponding GitHub App installation settings page. Expired, replayed, or stale-version tokens redirect back to in-app GitHub review.
      parameters:
      - in: path
        name: token
        required: true
        schema:
          type: string
          pattern: ^hat_[A-Za-z0-9_-]+$
      responses:
        '302':
          description: Redirects to GitHub installation settings or in-app review recovery
      tags:
      - Github
      operationId: getGithubAccessTargetByToken
      x-operation-id-source: derived
  /github/access-target/installation/{target}:
    get:
      summary: Resolve an opaque GitHub installation access target
      description: Validates the session and an API-owned browser installation id from the saved DB snapshot, then redirects to the matching GitHub App installation settings page. Invalid or stale targets redirect back to in-app GitHub review.
      parameters:
      - in: path
        name: target
        required: true
        schema:
          type: string
          pattern: ^github-installation:[0-9a-f]{16}$
      responses:
        '302':
          description: Redirects to GitHub installation settings or in-app review recovery
      tags:
      - Github
      operationId: getGithubAccessTargetInstallationByTarget
      x-operation-id-source: derived
  /github/refresh:
    post:
      summary: Refresh GitHub repository visibility
      description: Explicit rate-limited provider refresh. The API claims a per-user refresh lease, performs bounded provider reads, and commits only if the DB snapshot version has not changed while the provider read was in flight.
      responses:
        '200':
          description: Refreshed GitHub snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GitHubReposResponse'
        '409':
          description: GitHub refresh already in progress
      tags:
      - Github
      operationId: postGithubRefresh
      x-operation-id-source: derived
  /github/disconnect:
    post:
      summary: Remove user-owned GitHub provider access and clear cached visibility
      responses:
        '200':
          description: Final revoked GitHub snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GitHubReposResponse'
        '502':
          description: GitHub provider access could not be removed
      tags:
      - Github
      operationId: postGithubDisconnect
      x-operation-id-source: derived
  /github/oauth/start:
    get:
      summary: Start GitHub OAuth flow
      responses:
        '302':
          description: Redirects to GitHub
      tags:
      - Github
      operationId: getGithubOauthStart
      x-operation-id-source: derived
  /github/oauth/callback:
    get:
      summary: GitHub OAuth callback
      description: Completes GitHub OAuth, persists verified account truth, and may continue directly into GitHub App installation when the next safe action is unambiguous. An identity already linked to another Eurobase user remains unchanged and redirects with github-account-linked-to-another-user, regardless of OAuth status or token validity. A user already linked to a different immutable GitHub identity remains unchanged and redirects with github-account-mismatch.
      responses:
        '302':
          description: Redirect to GitHub App installation, callback success, or a bounded callback error state
      tags:
      - Github
      operationId: getGithubOauthCallback
      x-operation-id-source: derived
  /github/install/start:
    get:
      summary: Start GitHub App installation flow
      responses:
        '302':
          description: Redirects to GitHub
      tags:
      - Github
      operationId: getGithubInstallStart
      x-operation-id-source: derived
  /github/callback:
    get:
      summary: GitHub App callback
      responses:
        '200':
          description: Callback HTML
      tags:
      - Github
      operationId: getGithubCallback
      x-operation-id-source: derived
  /github/install/callback:
    get:
      summary: GitHub App installation callback
      description: Completes GitHub App installation callback and returns control to the web shell with DB-backed installation and repository truth.
      responses:
        '200':
          description: Callback HTML
      tags:
      - Github
      operationId: getGithubInstallCallback
      x-operation-id-source: derived
  /github/repos:
    get:
      summary: List cached installation repos and snapshot metadata
      description: Reads the stored GitHub account/install/repository snapshot only. The cached repo set is the selected/allowed repo snapshot persisted by callbacks and webhooks, and normal navigation must not trigger live GitHub sync. Repository rows are a bounded browser view model and do not expose clone URLs or installation ids.
      parameters:
      - name: q
        in: query
        schema:
          type: string
        description: Case-insensitive repository name filter applied to the cached snapshot.
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 50
        description: Maximum repository rows returned from the cached snapshot.
      responses:
        '200':
          description: Repo list snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GitHubReposResponse'
      tags:
      - Github
      operationId: getGithubRepos
      x-operation-id-source: derived
  /github/stream:
    get:
      summary: Stream GitHub snapshot invalidation events
      description: Authenticated server-sent events stream for DB-backed GitHub snapshot version changes. The stream only signals snapshot invalidation; clients must refetch /github/repos for actual data.
      responses:
        '200':
          description: SSE stream
      tags:
      - Github
      operationId: getGithubStream
      x-operation-id-source: derived
  /github/webhook:
    post:
      summary: GitHub webhook receiver
      description: 'Receives GitHub App webhook deliveries after signature verification. Delivery idempotency is DB-owned: completed duplicates return safe accepted responses, in-flight duplicates return a bounded retryable conflict, and handler failures leave the delivery retryable. Push events also persist per-project commit intent so API maintenance can retry deploy enqueue without relying on GitHub redelivery.'
      parameters:
      - in: header
        name: x-github-event
        required: true
        schema:
          type: string
      - in: header
        name: x-github-delivery
        required: true
        schema:
          type: string
      - in: header
        name: x-hub-signature-256
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Webhook accepted or completed duplicate safely replayed
        '400':
          description: Required webhook headers or JSON payload are invalid
        '401':
          description: GitHub webhook signature verification failed
        '409':
          description: Same delivery is already processing and should be retried later
        '503':
          description: Handler failed after delivery claim; delivery remains retryable
      tags:
      - Github
      operationId: postGithubWebhook
      x-operation-id-source: derived
components:
  schemas:
    GitHubConnectResponse:
      type: object
      required:
      - url
      - nextAction
      properties:
        url:
          type: string
        state:
          type: string
        nextAction:
          type: string
          enum:
          - oauth
          - install
          - manage
          - review
    GitHubReposResponse:
      type: object
      required:
      - githubAccount
      - installations
      - repos
      - accountStatus
      - installationCount
      - repoCount
      - sync
      - snapshotVersion
      - hasSavedAccess
      - projectCreateAvailable
      - recommendedAction
      - recoveryAction
      - navStatus
      - ready
      properties:
        githubAccount:
          $ref: '#/components/schemas/GitHubAccount'
        installations:
          type: array
          items:
            $ref: '#/components/schemas/GitHubInstallation'
        repos:
          type: array
          description: Browser-safe repository rows after applying the bounded q and limit projection.
          items:
            $ref: '#/components/schemas/GitHubRepo'
        accountStatus:
          type: string
          enum:
          - none
          - unknown
          - connected
          - revoked
        accountStatusReason:
          type:
          - string
          - 'null'
        accountVerifiedAt:
          type:
          - string
          - 'null'
          format: date-time
        sync:
          $ref: '#/components/schemas/GitHubSyncState'
        installationCount:
          type: integer
        repoCount:
          type: integer
          minimum: 0
          description: Sum of installation repository counts before q and limit are applied; it can exceed the returned or persisted repository rows when the snapshot is bounded or truncated. A missing stored installation count is normalized to 0 while ready remains false and recoveryAction remains refresh.
        snapshotVersion:
          type: integer
        snapshotUpdatedAt:
          type:
          - string
          - 'null'
          format: date-time
        hasSavedAccess:
          type: boolean
        projectCreateAvailable:
          type: boolean
        recommendedAction:
          type: string
          enum:
          - none
          - oauth
          - refresh
          - install
          - manage
          - review
          - disabled
        recoveryAction:
          $ref: '#/components/schemas/GitHubConnectAction'
        repositoryAccessAction:
          oneOf:
          - $ref: '#/components/schemas/GitHubConnectAction'
          - type: 'null'
        navStatus:
          type: object
          required:
          - tone
          - label
          properties:
            tone:
              type: string
              enum:
              - neutral
              - healthy
              - warning
              - danger
            label:
              type: string
        ready:
          type: boolean
    GitHubInstallation:
      type: object
      required:
      - id
      - repoCount
      properties:
        id:
          type: string
        accountLogin:
          type:
          - string
          - 'null'
        repoCount:
          type: integer
          minimum: 0
          description: Selected or allowed repository count recorded for this installation. A missing stored count is serialized as 0 only while the top-level snapshot remains not ready with refresh recovery; it is not proven empty inventory.
        repositoryAccessAction:
          oneOf:
          - $ref: '#/components/schemas/GitHubConnectAction'
          - type: 'null'
        syncStatus:
          type: string
          enum:
          - ok
          - empty
          - error
          - stale
        syncError:
          oneOf:
          - $ref: '#/components/schemas/GitHubSyncError'
          - type: 'null'
    GitHubSyncError:
      type: object
      required:
      - code
      - scope
      - actor
      - recoveryAction
      - message
      properties:
        code:
          type: string
        scope:
          type: string
          enum:
          - installations
          - repositories
        actor:
          type: string
          enum:
          - user
          - operator
          - unknown
        recoveryAction:
          type: string
          enum:
          - reconnect-oauth
          - install-app
          - open-installation-access
          - retry-refresh
          - operator-fix
        message:
          type: string
    GitHubSyncState:
      type: object
      required:
      - status
      - errors
      properties:
        status:
          type: string
          enum:
          - ok
          - partial
          - stale
        message:
          type:
          - string
          - 'null'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/GitHubSyncError'
        primaryError:
          oneOf:
          - $ref: '#/components/schemas/GitHubSyncError'
          - type: 'null'
    GitHubConnectAction:
      type: object
      required:
      - kind
      - label
      properties:
        kind:
          type: string
          enum:
          - none
          - oauth
          - refresh
          - install
          - manage
          - review
          - disabled
        label:
          type: string
        href:
          type:
          - string
          - 'null'
        disabled:
          type: boolean
        reason:
          type:
          - string
          - 'null'
    GitHubAccount:
      type:
      - object
      - 'null'
      required:
      - login
      properties:
        login:
          type: string
        name:
          type:
          - string
          - 'null'
        avatarUrl:
          type:
          - string
          - 'null'
        oauthStatus:
          type:
          - string
          - 'null'
          enum:
          - connected
          - revoked
          - unknown
          - null
        oauthStatusReason:
          type:
          - string
          - 'null'
        oauthVerifiedAt:
          type:
          - string
          - 'null'
          format: date-time
        snapshotVersion:
          type: integer
        createdAt:
          type:
          - string
          - 'null'
          format: date-time
        updatedAt:
          type:
          - string
          - 'null'
          format: date-time
    GitHubRepo:
      type: object
      required:
      - id
      - name
      - fullName
      - private
      - defaultBranch
      properties:
        id:
          type: string
        name:
          type: string
        fullName:
          type: string
        private:
          type: boolean
        defaultBranch:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    sessionCookie:
      type: apiKey
      in: cookie
      name: __Host-eurobase_session
    csrfHeader:
      type: apiKey
      in: header
      name: X-Eurobase-CSRF