Can I use Semaphore CI as a CLI?

Yes. KosmoKrator exposes a Semaphore CI CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Semaphore CI through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Semaphore CI tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Semaphore CI credentials stored?

Semaphore CI credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Semaphore CI MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

Semaphore CI Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Semaphore CI KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.semaphore_ci.*. Use lua_read_doc("integrations.semaphore-ci") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Semaphore CI workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.semaphore_ci.run_workflow({}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("semaphore-ci"))' --json
kosmo integrations:lua --eval 'print(docs.read("semaphore-ci.run_workflow"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local semaphore_ci = app.integrations.semaphore_ci
local result = semaphore_ci.run_workflow({})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.semaphore_ci, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.semaphore_ci.default.* or app.integrations.semaphore_ci.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Semaphore CI, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Semaphore CI

Semaphore CI tools are available under app.integrations["semaphore-ci"].

Use this integration to manage Semaphore API v1alpha resources: workflows, pipelines, promotions, tasks, jobs, self-hosted agents, deployment targets, artifacts, and artifact retention policies. Requests use Authorization: Token <api_token> and User-Agent: SemaphoreCI v2.0 Client.

Base URL

Configure the organization URL, for example:

https://acme.semaphoreci.com

The integration appends /api/v1alpha automatically when it is not already present.

Workflows And Pipelines

Run a workflow:

local run = app.integrations["semaphore-ci"].semaphore_ci_run_workflow({
  payload = {
    project_id = "project-uuid",
    reference = "refs/heads/main",
    pipeline_file = ".semaphore/semaphore.yml",
    parameters = {
      DEPLOY_ENV = "staging"
    }
  }
})

List pipelines:

local pipelines = app.integrations["semaphore-ci"].semaphore_ci_list_pipelines({
  project_id = "project-uuid",
  branch_name = "main"
})

Stop a pipeline:

app.integrations["semaphore-ci"].semaphore_ci_stop_pipeline({
  pipeline_id = "pipeline-uuid"
})

Jobs And Logs

local job = app.integrations["semaphore-ci"].semaphore_ci_get_job({
  job_id = "job-uuid"
})

local logs = app.integrations["semaphore-ci"].semaphore_ci_get_job_logs({
  job_id = "job-uuid",
  artifact_job_logs = true
})

artifact_job_logs=true can redirect to a signed artifact URL when artifact logs are available upstream.

Deployment Targets

Create a deployment target with the required project query and target payload:

local target = app.integrations["semaphore-ci"].semaphore_ci_create_deployment_target({
  project_id = "project-uuid",
  payload = {
    name = "staging",
    project_id = "project-uuid",
    unique_token = "idempotency-uuid",
    description = "Staging deployment target"
  }
})

Delete uses a required unique_token query parameter:

app.integrations["semaphore-ci"].semaphore_ci_delete_deployment_target({
  target_id = "target-uuid",
  unique_token = "idempotency-uuid"
})

Artifacts

List artifacts by scope:

local artifacts = app.integrations["semaphore-ci"].semaphore_ci_list_artifacts({
  scope = "jobs",
  scope_id = "job-uuid",
  path = "agent"
})

Artifact paths must be relative. Semaphore rejects absolute paths, traversal segments, and backslashes.

Raw API Helpers

Use raw helpers for newer or long-tail API v1alpha endpoints:

local result = app.integrations["semaphore-ci"].semaphore_ci_api_get({
  path = "/pipelines",
  query = { project_id = "project-uuid" }
})

Raw paths must be relative. /api/v1alpha/pipelines and /pipelines are both accepted; full external URLs are rejected.

Response Shape

JSON responses are returned as Semaphore provides them. Empty successful responses return { success = true }. Plain text responses return { value = "..." }.

Safety

Examples use fake UUIDs and project names.
Tool access depends on the permissions granted to the Semaphore API token.
Deployment target files and environment variables may contain secrets; avoid sending sensitive values into logs.
Prefer named tools for destructive operations because they document required ids and idempotency tokens.

Raw agent markdown

# Semaphore CI

Semaphore CI tools are available under `app.integrations["semaphore-ci"]`.

Use this integration to manage Semaphore API v1alpha resources: workflows, pipelines, promotions, tasks, jobs, self-hosted agents, deployment targets, artifacts, and artifact retention policies. Requests use `Authorization: Token <api_token>` and `User-Agent: SemaphoreCI v2.0 Client`.

## Base URL

Configure the organization URL, for example:

```text
https://acme.semaphoreci.com
```

The integration appends `/api/v1alpha` automatically when it is not already present.

## Workflows And Pipelines

Run a workflow:

```lua
local run = app.integrations["semaphore-ci"].semaphore_ci_run_workflow({
  payload = {
    project_id = "project-uuid",
    reference = "refs/heads/main",
    pipeline_file = ".semaphore/semaphore.yml",
    parameters = {
      DEPLOY_ENV = "staging"
    }
  }
})
```

List pipelines:

```lua
local pipelines = app.integrations["semaphore-ci"].semaphore_ci_list_pipelines({
  project_id = "project-uuid",
  branch_name = "main"
})
```

Stop a pipeline:

```lua
app.integrations["semaphore-ci"].semaphore_ci_stop_pipeline({
  pipeline_id = "pipeline-uuid"
})
```

## Jobs And Logs

```lua
local job = app.integrations["semaphore-ci"].semaphore_ci_get_job({
  job_id = "job-uuid"
})

local logs = app.integrations["semaphore-ci"].semaphore_ci_get_job_logs({
  job_id = "job-uuid",
  artifact_job_logs = true
})
```

`artifact_job_logs=true` can redirect to a signed artifact URL when artifact logs are available upstream.

## Deployment Targets

Create a deployment target with the required project query and target payload:

```lua
local target = app.integrations["semaphore-ci"].semaphore_ci_create_deployment_target({
  project_id = "project-uuid",
  payload = {
    name = "staging",
    project_id = "project-uuid",
    unique_token = "idempotency-uuid",
    description = "Staging deployment target"
  }
})
```

Delete uses a required `unique_token` query parameter:

```lua
app.integrations["semaphore-ci"].semaphore_ci_delete_deployment_target({
  target_id = "target-uuid",
  unique_token = "idempotency-uuid"
})
```

## Artifacts

List artifacts by scope:

```lua
local artifacts = app.integrations["semaphore-ci"].semaphore_ci_list_artifacts({
  scope = "jobs",
  scope_id = "job-uuid",
  path = "agent"
})
```

Artifact paths must be relative. Semaphore rejects absolute paths, traversal segments, and backslashes.

## Raw API Helpers

Use raw helpers for newer or long-tail API v1alpha endpoints:

```lua
local result = app.integrations["semaphore-ci"].semaphore_ci_api_get({
  path = "/pipelines",
  query = { project_id = "project-uuid" }
})
```

Raw paths must be relative. `/api/v1alpha/pipelines` and `/pipelines` are both accepted; full external URLs are rejected.

## Response Shape

JSON responses are returned as Semaphore provides them. Empty successful responses return `{ success = true }`. Plain text responses return `{ value = "..." }`.

## Safety

- Examples use fake UUIDs and project names.
- Tool access depends on the permissions granted to the Semaphore API token.
- Deployment target files and environment variables may contain secrets; avoid sending sensitive values into logs.
- Prefer named tools for destructive operations because they document required ids and idempotency tokens.

Metadata-derived Lua example

local result = app.integrations.semaphore_ci.run_workflow({})
print(result)

Functions

run_workflow Write

Run a workflow for a project and reference.

Lua path: app.integrations.semaphore_ci.run_workflow
Full name: semaphore-ci.semaphore_ci_run_workflow

Parameter	Type	Required	Description
No parameters.

get_workflow Read

Get one workflow by id.

Lua path: app.integrations.semaphore_ci.get_workflow
Full name: semaphore-ci.semaphore_ci_get_workflow

Parameter	Type	Required	Description
No parameters.

list_workflows Read

List workflows for a project.

Lua path: app.integrations.semaphore_ci.list_workflows
Full name: semaphore-ci.semaphore_ci_list_workflows

Parameter	Type	Required	Description
No parameters.

rerun_workflow Write

Rerun a workflow with an idempotency token.

Lua path: app.integrations.semaphore_ci.rerun_workflow
Full name: semaphore-ci.semaphore_ci_rerun_workflow

Parameter	Type	Required	Description
No parameters.

stop_workflow Write

Stop a workflow.

Lua path: app.integrations.semaphore_ci.stop_workflow
Full name: semaphore-ci.semaphore_ci_stop_workflow

Parameter	Type	Required	Description
No parameters.

get_pipeline Read

Get one pipeline by id.

Lua path: app.integrations.semaphore_ci.get_pipeline
Full name: semaphore-ci.semaphore_ci_get_pipeline

Parameter	Type	Required	Description
No parameters.

list_pipelines Read

List pipelines by project or workflow id.

Lua path: app.integrations.semaphore_ci.list_pipelines
Full name: semaphore-ci.semaphore_ci_list_pipelines

Parameter	Type	Required	Description
No parameters.

stop_pipeline Write

Stop a pipeline.

Lua path: app.integrations.semaphore_ci.stop_pipeline
Full name: semaphore-ci.semaphore_ci_stop_pipeline

Parameter	Type	Required	Description
No parameters.

partial_rebuild_pipeline Write

Rebuild failed pipeline blocks.

Lua path: app.integrations.semaphore_ci.partial_rebuild_pipeline
Full name: semaphore-ci.semaphore_ci_partial_rebuild_pipeline

Parameter	Type	Required	Description
No parameters.

validate_yaml Write

Validate Semaphore pipeline YAML.

Lua path: app.integrations.semaphore_ci.validate_yaml
Full name: semaphore-ci.semaphore_ci_validate_yaml

Parameter	Type	Required	Description
No parameters.

list_promotions Read

List promotions for a pipeline.

Lua path: app.integrations.semaphore_ci.list_promotions
Full name: semaphore-ci.semaphore_ci_list_promotions

Parameter	Type	Required	Description
No parameters.

trigger_promotion Write

Trigger a pipeline promotion.

Lua path: app.integrations.semaphore_ci.trigger_promotion
Full name: semaphore-ci.semaphore_ci_trigger_promotion

Parameter	Type	Required	Description
No parameters.

trigger_task Write

Run a Semaphore task immediately.

Lua path: app.integrations.semaphore_ci.trigger_task
Full name: semaphore-ci.semaphore_ci_trigger_task

Parameter	Type	Required	Description
No parameters.

get_job Read

Get one job by id.

Lua path: app.integrations.semaphore_ci.get_job
Full name: semaphore-ci.semaphore_ci_get_job

Parameter	Type	Required	Description
No parameters.

stop_job Write

Stop one job by id.

Lua path: app.integrations.semaphore_ci.stop_job
Full name: semaphore-ci.semaphore_ci_stop_job

Parameter	Type	Required	Description
No parameters.

get_job_logs Read

Get job logs.

Lua path: app.integrations.semaphore_ci.get_job_logs
Full name: semaphore-ci.semaphore_ci_get_job_logs

Parameter	Type	Required	Description
No parameters.

list_agent_types Read

List self-hosted agent types.

Lua path: app.integrations.semaphore_ci.list_agent_types
Full name: semaphore-ci.semaphore_ci_list_agent_types

Parameter	Type	Required	Description
No parameters.

create_agent_type Write

Create a self-hosted agent type.

Lua path: app.integrations.semaphore_ci.create_agent_type
Full name: semaphore-ci.semaphore_ci_create_agent_type

Parameter	Type	Required	Description
No parameters.

update_agent_type Write

Update a self-hosted agent type.

Lua path: app.integrations.semaphore_ci.update_agent_type
Full name: semaphore-ci.semaphore_ci_update_agent_type

Parameter	Type	Required	Description
No parameters.

get_agent_type Read

Get a self-hosted agent type.

Lua path: app.integrations.semaphore_ci.get_agent_type
Full name: semaphore-ci.semaphore_ci_get_agent_type

Parameter	Type	Required	Description
No parameters.

delete_agent_type Write

Delete a self-hosted agent type.

Lua path: app.integrations.semaphore_ci.delete_agent_type
Full name: semaphore-ci.semaphore_ci_delete_agent_type

Parameter	Type	Required	Description
No parameters.

disable_agent_type_agents Write

Disable agents for an agent type.

Lua path: app.integrations.semaphore_ci.disable_agent_type_agents
Full name: semaphore-ci.semaphore_ci_disable_agent_type_agents

Parameter	Type	Required	Description
No parameters.

list_agents Read

List self-hosted agents.

Lua path: app.integrations.semaphore_ci.list_agents
Full name: semaphore-ci.semaphore_ci_list_agents

Parameter	Type	Required	Description
No parameters.

get_agent Read

Get one self-hosted agent.

Lua path: app.integrations.semaphore_ci.get_agent
Full name: semaphore-ci.semaphore_ci_get_agent

Parameter	Type	Required	Description
No parameters.

list_deployment_targets Read

List deployment targets for a project.

Lua path: app.integrations.semaphore_ci.list_deployment_targets
Full name: semaphore-ci.semaphore_ci_list_deployment_targets

Parameter	Type	Required	Description
No parameters.

get_deployment_target Read

Get one deployment target.

Lua path: app.integrations.semaphore_ci.get_deployment_target
Full name: semaphore-ci.semaphore_ci_get_deployment_target

Parameter	Type	Required	Description
No parameters.

create_deployment_target Write

Create a deployment target.

Lua path: app.integrations.semaphore_ci.create_deployment_target
Full name: semaphore-ci.semaphore_ci_create_deployment_target

Parameter	Type	Required	Description
No parameters.

update_deployment_target Write

Update a deployment target.

Lua path: app.integrations.semaphore_ci.update_deployment_target
Full name: semaphore-ci.semaphore_ci_update_deployment_target

Parameter	Type	Required	Description
No parameters.

delete_deployment_target Write

Delete a deployment target.

Lua path: app.integrations.semaphore_ci.delete_deployment_target
Full name: semaphore-ci.semaphore_ci_delete_deployment_target

Parameter	Type	Required	Description
No parameters.

deactivate_deployment_target Write

Deactivate a deployment target.

Lua path: app.integrations.semaphore_ci.deactivate_deployment_target
Full name: semaphore-ci.semaphore_ci_deactivate_deployment_target

Parameter	Type	Required	Description
No parameters.

activate_deployment_target Write

Activate a deployment target.

Lua path: app.integrations.semaphore_ci.activate_deployment_target
Full name: semaphore-ci.semaphore_ci_activate_deployment_target

Parameter	Type	Required	Description
No parameters.

get_deployment_history Read

Retrieve deployment history.

Lua path: app.integrations.semaphore_ci.get_deployment_history
Full name: semaphore-ci.semaphore_ci_get_deployment_history

Parameter	Type	Required	Description
No parameters.

list_artifacts Read

List artifacts by scope.

Lua path: app.integrations.semaphore_ci.list_artifacts
Full name: semaphore-ci.semaphore_ci_list_artifacts

Parameter	Type	Required	Description
No parameters.

get_artifact_signed_url Read

Get a signed artifact URL.

Lua path: app.integrations.semaphore_ci.get_artifact_signed_url
Full name: semaphore-ci.semaphore_ci_get_artifact_signed_url

Parameter	Type	Required	Description
No parameters.

configure_artifact_retention Write

Configure artifact retention policies.

Lua path: app.integrations.semaphore_ci.configure_artifact_retention
Full name: semaphore-ci.semaphore_ci_configure_artifact_retention_policy

Parameter	Type	Required	Description
No parameters.

get_artifact_retention Read

Get artifact retention policy.

Lua path: app.integrations.semaphore_ci.get_artifact_retention
Full name: semaphore-ci.semaphore_ci_get_artifact_retention_policy

Parameter	Type	Required	Description
No parameters.

api_get Read

Call a safe relative Semaphore GET path.

Lua path: app.integrations.semaphore_ci.api_get
Full name: semaphore-ci.semaphore_ci_api_get

Parameter	Type	Required	Description
No parameters.

api_post Write

Call a safe relative Semaphore POST path.

Lua path: app.integrations.semaphore_ci.api_post
Full name: semaphore-ci.semaphore_ci_api_post

Parameter	Type	Required	Description
No parameters.

api_patch Write

Call a safe relative Semaphore PATCH path.

Lua path: app.integrations.semaphore_ci.api_patch
Full name: semaphore-ci.semaphore_ci_api_patch

Parameter	Type	Required	Description
No parameters.

api_delete Write

Call a safe relative Semaphore DELETE path.

Lua path: app.integrations.semaphore_ci.api_delete
Full name: semaphore-ci.semaphore_ci_api_delete

Parameter	Type	Required	Description
No parameters.