Pipelines

​

Concepts

• Pipeline — versioned definition that lives next to a project. It can be stored inline or backed by a Git repository through a pipeline.yaml file.
• Stage — an ordered group of jobs. A pipeline may declare multiple stages or use the jobs shorthand, in which case Arcentra wraps the jobs in a default stage.
• Job — a unit of work scheduled to a single agent. Jobs declare the steps to run and any conditions or matrix expansion.
• Step — the atomic action. A step is either a builtin (such as shell) or a plugin invocation through uses + action + args.
• PipelineRun / JobRun / StepRun — runtime objects with their own state, status, logs, artifacts, and timing.
• Trigger — manual, cron, or event (webhook). Triggers can be combined with approval gates.

​

Statuses

​

Pipeline definition

namespace: demo.pipeline
version: v1
stages:
  - name: build
    jobs:
      - name: build-go
        steps:
          - name: checkout
            uses: actions/git-checkout@v1
            args:
              ref: ${{ trigger.ref }}
          - name: compile
            uses: actions/go-build@v1
            args:
              go_version: "1.25"

namespace: demo.pipeline
version: v1
jobs:
  - name: build
    steps:
      - name: compile
        uses: actions/go-build@v1
        args:
          go_version: "1.25"

​

HTTP API

​

Authentication

Authorization: Bearer <token>

​

Response envelope

{
  "code": 0,
  "msg": "success",
  "detail": {},
  "timestamp": 1730000000
}

{
  "code": 0,
  "msg": "success",
  "timestamp": 1730000000
}

{
  "code": 400,
  "errMsg": "xxx",
  "path": "/api/v1/pipelines/...",
  "timestamp": 1730000000
}

​

Endpoints

​

Pipeline management

• POST /api/v1/pipelines
• PUT /api/v1/pipelines/:pipelineId
• GET /api/v1/pipelines/:pipelineId
• GET /api/v1/pipelines
• DELETE /api/v1/pipelines/:pipelineId

​

Definition

• GET /api/v1/pipelines/:pipelineId/spec
• POST /api/v1/pipelines/:pipelineId/spec/validate
• POST /api/v1/pipelines/:pipelineId/spec/save

​

Run control

• POST /api/v1/pipelines/:pipelineId/trigger
• GET /api/v1/pipelines/:pipelineId/runs
• GET /api/v1/pipelines/runs/:runId
• POST /api/v1/pipelines/:pipelineId/runs/:runId/stop
• POST /api/v1/pipelines/:pipelineId/runs/:runId/pause
• POST /api/v1/pipelines/:pipelineId/runs/:runId/resume

​

Common request shapes

​

Create pipeline

{
  "projectId": "proj_xxx",
  "name": "build-main",
  "description": "main branch build",
  "repoUrl": "https://github.com/org/repo.git",
  "defaultBranch": "main",
  "pipelineFilePath": ".arcentra/pipeline.yaml",
  "saveMode": "pr",
  "prTargetBranch": "main",
  "metadata": { "owner": "devops" },
  "createdBy": "user_xxx"
}

​

Validate definition

{
  "spec": {
    "namespace": "demo.pipeline",
    "version": "v1",
    "jobs": [
      {
        "name": "build",
        "steps": [
          {
            "name": "compile",
            "uses": "actions/go-build@v1",
            "args": { "go_version": "1.25" }
          }
        ]
      }
    ]
  },
  "format": "yaml"
}

​

Save definition

{
  "spec": { /* same shape as validate */ },
  "format": "yaml",
  "expectedHeadCommitSha": "abc123",
  "commitMessage": "update pipeline",
  "requestId": "req-20260302-001",
  "editor": "user_xxx"
}

​

Trigger pipeline

{
  "variables": { "env": "prod" },
  "triggeredBy": "user_xxx",
  "requestId": "trigger-001"
}

​

Pause / resume / stop

{
  "reason": "manual operation",
  "operator": "user_xxx"
}

​

Enumerations

• saveMode: direct, pr
• format: json, yaml, yml
• Pipeline status: pending, running, success, failed, cancelled, paused

​

Realtime updates

• A WebSocket gateway at GET /api/v1/ws for log and status subscriptions.
• gRPC streaming services (stream.v1) for server-to-server integrations.