CILocal.git · cicontrol.openapi.yaml
CILocal.git / cicontrol.openapi.yaml
revision 0ab234aec37521ccfcd519461a55b9e607a696b1 · complete file
openapi: 3.1.0
info:
title: CI Control Plane CLI
version: 0.1.0
summary: REST abstraction over the cicontrol Swift CLI.
description: |
This specification documents the HTTP surface that wraps the `cicontrol` command line
interface. Each operation corresponds to an existing CLI subcommand and accepts the
same inputs. The control plane treats this OpenAPI document as the single source of
truth for the behaviours, inputs and outputs of the CLI.
servers:
- url: http://localhost:8080
description: Local automation server exposing cicontrol.
tags:
- name: Setup
description: Bootstrap and credential management routines.
- name: Status
description: Health checks and inventory reporting for the CI stack.
- name: Mirror
description: Git hosting and push mirror orchestration.
paths:
/cicontrol/setup:
post:
tags: [Setup]
summary: Bootstrap the local CI system.
description: |
Wraps `cicontrol setup`, ensuring the local Gitea instance, FountainStore
and other CI tooling are configured for use. Secrets are materialised via
Swift-SecretStore when possible. Use `nonInteractive` to require all values
to be provided explicitly.
operationId: cicontrol_setup
x-cli-command:
binary: cicontrol
subcommand: setup
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SetupRequest'
responses:
'200':
description: Setup completed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SetupResponse'
'400':
description: Invalid input was provided to the setup routine.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Setup failed because dependent tooling was unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/cicontrol/status:
post:
tags: [Status]
summary: Inspect local CI health, FountainStore metrics and mirrored GitHub repositories.
description: |
Wraps `cicontrol status`. When provided, the GitHub organisation is queried via
the `gh` CLI and FountainStore metrics are fetched using HTTP. Docker container
health is inspected using `docker ps` output.
operationId: cicontrol_status
x-cli-command:
binary: cicontrol
subcommand: status
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/StatusRequest'
responses:
'200':
description: Status checks completed.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'400':
description: Invalid request parameters (e.g. malformed metrics URL).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: One or more status checks failed unexpectedly.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/cicontrol/mirror:
post:
tags: [Mirror]
summary: Configure GitHub push mirrors for local repositories.
description: |
Wraps `cicontrol mirror`. Each repository stored in FountainStore with mirroring
enabled is processed. By default repositories are mirrored to `https://github.com/{org}`;
supply `storeURL` to query a remote FountainStore API or `storePath` for embedded access.
operationId: cicontrol_mirror
x-cli-command:
binary: cicontrol
subcommand: mirror
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MirrorRequest'
responses:
'200':
description: Mirror configuration completed. Individual repositories may still report failures.
content:
application/json:
schema:
$ref: '#/components/schemas/MirrorResponse'
'400':
description: Request rejected because inputs were invalid (e.g. both storePath and storeURL provided).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Conflicts encountered when attempting to configure push mirrors.
content:
application/json:
schema:
$ref: '#/components/schemas/MirrorResponse'
'500':
description: Mirroring failed due to unavailable secrets, FountainStore, or Gitea APIs.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
SetupRequest:
type: object
required:
- giteaURL
properties:
giteaURL:
type: string
format: uri
description: Base URL for the local Gitea instance.
examples:
- http://localhost:3000
jenkinsURL:
type: string
format: uri
description: Base URL for the Jenkins controller that the setup flow should configure.
default: http://localhost:8080
adminUser:
type: string
description: Username for the administrative Gitea account.
default: admin
jenkinsUser:
type: string
description: Username for the Jenkins administrator account.
default: admin
adminPassword:
type: string
nullable: true
description: >-
Password for the Gitea admin user. Omit to auto-generate a strong password unless `nonInteractive` is true.
jenkinsPassword:
type: string
nullable: true
description: Optional password for the Jenkins admin account when not using token-based authentication.
jenkinsAPIToken:
type: string
nullable: true
description: Optional pre-generated Jenkins API token to import instead of creating one during setup.
storePath:
type: string
nullable: true
description: Filesystem path containing the FountainStore data directory.
examples:
- "~/\.ci-control-plane/fountainstore"
nonInteractive:
type: boolean
default: false
description: >-
When true, setup fails unless all required inputs (including adminPassword) are supplied explicitly.
additionalProperties: false
SetupResponse:
type: object
required:
- status
- giteaURL
- adminUser
properties:
status:
type: string
enum: [completed]
description: Indicates the setup command completed without throwing.
giteaURL:
type: string
format: uri
description: Normalised Gitea base URL used for setup operations.
adminUser:
type: string
description: Administrator username ensured during setup.
generatedPassword:
type: boolean
description: True when the command generated a password on behalf of the caller.
auditLogEntries:
type: array
description: Audit log entries recorded while performing setup activities.
items:
$ref: '#/components/schemas/AuditLogEntry'
warnings:
type: array
items:
type: string
description: Human readable warnings emitted during setup.
additionalProperties: false
StatusRequest:
type: object
properties:
org:
type: string
nullable: true
description: GitHub organisation to query using the gh CLI.
example: Fountain-Coach
metricsURL:
type: string
nullable: true
format: uri
description: FountainStore metrics endpoint to fetch over HTTP.
example: http://localhost:8080/metrics
additionalProperties: false
StatusResponse:
type: object
required:
- dockerContainers
- repositories
properties:
metricsOutput:
type: string
nullable: true
description: Raw metrics payload returned from FountainStore, if queried.
dockerContainers:
type: array
description: Summary of running Docker containers detected via `docker ps`.
items:
$ref: '#/components/schemas/DockerContainerSummary'
repositories:
type: array
description: List of GitHub repositories retrieved for the requested organisation.
items:
$ref: '#/components/schemas/GitHubRepositorySummary'
warnings:
type: array
items:
type: string
description: Non-fatal warnings encountered during status checks.
additionalProperties: false
MirrorRequest:
type: object
required:
- org
properties:
org:
type: string
description: GitHub organisation that receives push mirrors.
example: Fountain-Coach
giteaURL:
type: string
format: uri
default: http://localhost:3000
description: Base URL for the source Gitea instance hosting local repositories.
storePath:
type: string
nullable: true
description: Local FountainStore data directory. Cannot be provided when `storeURL` is set.
storeURL:
type: string
nullable: true
format: uri
description: Remote FountainStore service endpoint queried over HTTP. Cannot be provided with `storePath`.
include:
type: array
items:
type: string
description: Glob patterns restricting which repositories to mirror.
exclude:
type: array
items:
type: string
description: Glob patterns used to omit repositories from mirroring.
dryRun:
type: boolean
default: false
description: When true, mirrors are evaluated but not created or updated.
allOf:
- type: object
- not:
required:
- storePath
- storeURL
additionalProperties: false
MirrorResponse:
type: object
required:
- org
- processedRepositories
properties:
org:
type: string
description: GitHub organisation target of the mirroring session.
dryRun:
type: boolean
description: Indicates whether the underlying CLI invocation ran with `--dry-run`.
processedRepositories:
type: array
description: Mirroring results for each FountainStore repository considered.
items:
$ref: '#/components/schemas/MirrorResult'
auditLogEntries:
type: array
items:
$ref: '#/components/schemas/AuditLogEntry'
description: Audit log entries recorded while configuring mirrors.
warnings:
type: array
items:
type: string
description: Non-fatal issues encountered (e.g. missing optional tooling).
additionalProperties: false
MirrorResult:
type: object
required:
- repository
- outcome
properties:
repository:
$ref: '#/components/schemas/RepositoryDocument'
outcome:
$ref: '#/components/schemas/MirrorOutcome'
auditLogId:
type: string
description: Identifier of the audit log entry associated with this repository.
error:
type: string
description: Detailed error message when the outcome indicates failure.
additionalProperties: false
DockerContainerSummary:
type: object
required:
- name
- status
- image
properties:
name:
type: string
description: Container name reported by Docker.
status:
type: string
description: Raw status string from `docker ps`.
image:
type: string
description: Container image reference.
unhealthy:
type: boolean
description: True when Docker indicates an unhealthy status for the container.
additionalProperties: false
GitHubRepositorySummary:
type: object
required:
- name
- visibility
properties:
name:
type: string
description: Repository name within the GitHub organisation.
visibility:
type: string
enum: [public, private, internal]
description: Visibility reported by the GitHub API.
additionalProperties: false
RepositoryDocument:
type: object
required:
- id
- owner
- name
properties:
id:
type: string
description: Stable identifier for the FountainStore record.
owner:
type: string
description: Repository owner within the local Gitea instance.
name:
type: string
description: Repository name within the owner namespace.
description:
type: string
nullable: true
description: Optional description synced from FountainStore.
mirror:
$ref: '#/components/schemas/RepositoryMirrorSettings'
additionalProperties: false
RepositoryMirrorSettings:
type: object
properties:
enabled:
type: boolean
description: Indicates whether mirroring is enabled for the repository.
githubRepositoryName:
type: string
description: Target repository name on GitHub. Defaults to the local repository name.
remoteURL:
type: string
format: uri
description: Explicit remote URL to mirror into. Overrides the default GitHub URL.
additionalProperties: false
MirrorOutcome:
type: object
required:
- action
- description
properties:
action:
type: string
enum:
- created
- updated
- unchanged
- dryRunCreate
- dryRunUpdate
- dryRunNoop
- failed
description: Result of attempting to configure the push mirror.
description:
type: string
description: Human readable explanation of the action taken.
additionalProperties: false
AuditLogEntry:
type: object
required:
- id
- timestamp
- action
- subject
- metadata
properties:
id:
type: string
format: uuid
description: Unique identifier assigned to the audit log entry.
timestamp:
type: string
format: date-time
description: Timestamp when the event occurred.
action:
type: string
description: Action identifier recorded in the audit log.
actor:
type: string
nullable: true
description: Principal performing the action (typically the USER environment variable).
subject:
type: string
description: Entity affected by the action.
metadata:
type: object
additionalProperties:
type: string
description: Additional contextual metadata stored alongside the event.
additionalProperties: false
ErrorResponse:
type: object
required:
- error
properties:
error:
type: string
description: Human readable error message summarising the failure.
details:
type: object
additionalProperties:
type: string
description: Additional structured fields describing the error context.
additionalProperties: false
/cli/repos/add:
post:
summary: Add a repository record to FountainStore for mirroring/management
operationId: addRepository
tags: [cli]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddRepositoryRequest'
responses:
'200':
description: Repository record created or updated
content:
application/json:
schema:
$ref: '#/components/schemas/AddRepositoryResponse'
'400': { description: Invalid request }
'500': { description: Failed to persist repository record }
AddRepositoryRequest:
type: object
required: [owner, name]
properties:
owner:
type: string
description: Owner/namespace for the repository in Gitea.
name:
type: string
description: Repository name in Gitea.
description:
type: string
nullable: true
mirrorEnabled:
type: boolean
default: true
description: Enable GitHub push mirroring for this repository.
githubRepositoryName:
type: string
nullable: true
description: GitHub repository name when different from the Gitea name.
remoteURL:
type: string
nullable: true
description: Optional override for the GitHub remote URL.
storePath:
type: string
nullable: true
description: Filesystem path for embedded FountainStore.
storeURL:
type: string
nullable: true
description: HTTP URL for remote FountainStore API.
additionalProperties: false
AddRepositoryResponse:
type: object
required: [status, id]
properties:
status:
type: string
enum: [completed]
id:
type: string
description: Identifier of the stored repository record (e.g., owner:name).
warnings:
type: array
items:
type: string