CI/CD Integrations API¶

The CI/CD Integrations API connects Farm to external CI/CD platforms (ArgoCD, CircleCI, Jenkins, Travis CI), manages per-organization credentials, and receives webhook events from each platform.

Base Paths¶

Prerequisites¶

Connect each platform by creating an IntegrationCredential record for your organization before using the platform-specific endpoints. All platform API calls use the stored credential — no environment variables required.

Integration Credentials¶

Endpoints¶

Credential Types¶

Create Credential¶

POST /api/v1/integrations/credentials
Content-Type: application/json
Authorization: Bearer <token>

{
  "type": "argocd",
  "name": "Production ArgoCD",
  "value": {
    "url": "https://argocd.example.com",
    "token": "eyJhbGciOi..."
  }
}

The value object is encrypted with AES-256-GCM before storage. The key is derived from JWT_SECRET. Decrypted values are never returned in API responses.

Response (201)¶

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "argocd",
  "name": "Production ArgoCD",
  "orgId": null,
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z"
}

ArgoCD¶

Endpoints¶

List Applications¶

GET /api/v1/argocd/applications
Authorization: Bearer <token>

Returns an empty array when no ArgoCD credential is configured.

Response (200)¶

[
  {
    "metadata": { "name": "my-service", "namespace": "argocd" },
    "spec": {
      "source": { "repoURL": "https://github.com/org/my-service", "targetRevision": "main" },
      "destination": { "server": "https://kubernetes.default.svc", "namespace": "production" }
    },
    "status": {
      "health": { "status": "Healthy" },
      "sync": { "status": "Synced" },
      "operationState": { "finishedAt": "2025-01-01T00:00:00.000Z" }
    }
  }
]

Health Status Values¶

Sync Status Values¶

Component Integration¶

Set the argocdApp field on a Catalog component to link it to an ArgoCD Application name. The CI/CD tab on the component detail page will then show the real-time health and sync status.

PATCH /api/v1/catalog/components/:id
Content-Type: application/json
Authorization: Bearer <token>

{ "argocdApp": "my-service" }

CircleCI¶

Endpoints¶

List Pipelines¶

GET /api/v1/circleci/pipelines?vcsUrl=https://github.com/org/repo
Authorization: Bearer <token>

Trigger Pipeline¶

POST /api/v1/circleci/pipelines/gh%2Forg%2Frepo/trigger
Authorization: Bearer <token>

The :slug is URL-encoded in the form gh/org/repo (GitHub) or bb/org/repo (Bitbucket).

Jenkins¶

Endpoints¶

List Jobs¶

Returns all Jenkins jobs with their last build result.

GET /api/v1/jenkins/jobs
Authorization: Bearer <token>

Response (200)¶

[
  {
    "name": "my-service-build",
    "url": "https://jenkins.example.com/job/my-service-build/",
    "color": "blue",
    "lastBuild": {
      "number": 42,
      "result": "SUCCESS",
      "timestamp": 1735689600000,
      "duration": 120000
    }
  }
]

Build Result Values¶

Travis CI¶

Endpoints¶

List Builds¶

GET /api/v1/travisci/builds?repoSlug=org%2Frepo
Authorization: Bearer <token>

Build State Values¶

Webhook Receivers¶

Farm registers inbound webhook endpoints for each CI/CD platform. When a build completes or changes status, the platform sends a POST to Farm, which emits a ci.build.updated WebSocket event to all connected frontend clients.

All webhook endpoints return 200 OK immediately. Processing is asynchronous via EventEmitter2.

CircleCI Webhook Setup¶

In CircleCI project settings, add a webhook pointing to https://your-farm-instance.com/api/v1/webhooks/circleci. Farm verifies the request using the HMAC-SHA256 circleci-signature header.

Jenkins Webhook Setup¶

Install the Generic Webhook Trigger plugin in Jenkins. Configure it to POST to https://your-farm-instance.com/api/v1/webhooks/jenkins.

Travis CI Webhook Setup¶

In your .travis.yml, add:

notifications:
  webhooks:
    urls:
      - https://your-farm-instance.com/api/v1/webhooks/travisci
    on_success: always
    on_failure: always

Pipeline Build Stage¶

Farm pipelines support an OCI image build stage type that runs docker, buildah, or podman on the Farm API server.

Stage Configuration¶

{
  "name": "Build Docker Image",
  "type": "build",
  "config": {
    "engine": "docker",
    "dockerfile": "Dockerfile",
    "context": ".",
    "tag": "my-org/my-service:{{version}}-{{commitSha}}",
    "push": true,
    "registry": "registry.example.com"
  }
}

Config Fields¶

Tag Templates¶

The build engine binary must be available in the Farm API server's PATH. The stage fails gracefully with a descriptive error message when the engine is not found.