fountainai-deployer.git · openapi.yaml

fountainai-deployer.git / openapi.yaml

revision 63242a5a783b686519f1a204450e19ddcad5a226 · complete file

openapi: 3.1.0
info:
  title: FountainAI Deployment Service
  version: "0.1.0"
  description: >
    The FountainAI Deployment Service acts as a centralized deployment controller for the FountainAI ecosystem.
    It enables trusted deployment of containerized services, automated registry updates, workflow re-triggering,
    and `swarm-stack.yml` synchronization logic — fully separate from Swarm Orchestrator responsibilities.

servers:
  - url: http://localhost:8015
    description: Local development

tags:
  - name: deploy
    description: Workflows and GHCR image publication
  - name: stack
    description: swarm-stack.yml access and editing

paths:
  /deploy/push-workflow:
    post:
      summary: Push deployment workflow to all FountainAI repos
      description: >
        Fetches all repositories under the `Fountain-Coach` organization and ensures each contains an up-to-date
        `.github/workflows/deploy.yml` with the correct cross-platform build logic.
      operationId: pushDeploymentWorkflow
      tags: [deploy]
      responses:
        "200":
          description: Workflows updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeploymentResult"
        "500":
          description: Internal error during repository processing

  /deploy/service:
    post:
      summary: Trigger deployment of a single service
      description: >
        Triggers the GitHub Actions workflow for the given service repository to rebuild and push its Docker image to GHCR.
      operationId: triggerServiceDeployment
      tags: [deploy]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeploymentRequest"
      responses:
        "200":
          description: Deployment triggered
        "400":
          description: Invalid service or repo
        "500":
          description: GitHub API or authentication error

  /stack/status:
    get:
      summary: Retrieve current state of swarm-stack.yml
      description: >
        Returns the canonical `swarm-stack.yml` content as managed by this service — used as a ground truth source of
        configuration for Swarm Orchestrator validation or human inspection.
      operationId: getSwarmStackFile
      tags: [stack]
      responses:
        "200":
          description: The current swarm stack file
          content:
            text/plain:
              schema:
                type: string

  /stack/validate:
    post:
      summary: Validate swarm-stack.yml against known GHCR packages
      description: >
        Validates the current `swarm-stack.yml` against what packages exist in GHCR under the `fountain-coach` org,
        checking for consistency between declared images and real deployments.
      operationId: validateSwarmStack
      tags: [stack]
      responses:
        "200":
          description: Validation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StackValidationResult"

  /stack/update-image:
    post:
      summary: Update image version in swarm-stack.yml
      description: >
        Allows bumping the version or digest of a declared image in the central `swarm-stack.yml`, typically after successful
        rebuilds or test verifications.
      operationId: updateImageVersion
      tags: [stack]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImageUpdateRequest"
      responses:
        "200":
          description: Image updated
        "400":
          description: Invalid input
        "500":
          description: Failed to apply changes

components:
  securitySchemes:
    GitHubToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        GitHub token used to access organization repos and trigger workflows. Must be scoped with `repo` and `workflow`.

  schemas:
    DeploymentRequest:
      type: object
      required:
        - repository
        - branch
      properties:
        repository:
          type: string
          example: fountainai-bootstrap-service
        branch:
          type: string
          example: main

    DeploymentResult:
      type: object
      properties:
        updated:
          type: array
          items:
            type: string
          example: [ "clientgen-service", "baseline-awareness-service" ]
        skipped:
          type: array
          items:
            type: string
          example: [ "fountain-manifesto" ]

    StackValidationResult:
      type: object
      properties:
        valid:
          type: boolean
        missing_images:
          type: array
          items:
            type: string
        extra_images:
          type: array
          items:
            type: string

    ImageUpdateRequest:
      type: object
      required:
        - service
        - new_tag
      properties:
        service:
          type: string
          example: baseline-awareness-service
        new_tag:
          type: string
          example: sha256:abcdef123456...

security:
  - GitHubToken: []