KosmoKrator

productivity

Buildkite Lua API for KosmoKrator Agents

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

Lua Namespace

Agents call this integration through app.integrations.buildkite.*. Use lua_read_doc("integrations.buildkite") 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 Buildkite workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.buildkite.get_current_user({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("buildkite"))' --json
kosmo integrations:lua --eval 'print(docs.read("buildkite.get_current_user"))' --json

Workflow file

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

workflow.lua 
local buildkite = app.integrations.buildkite
local result = buildkite.get_current_user({})

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.buildkite, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.buildkite.default.* or app.integrations.buildkite.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Buildkite, 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.

Buildkite

Buildkite tools are available under app.integrations.buildkite.

Use this integration to inspect organizations, pipelines, builds, and job diagnostics, or to trigger and manage builds from agent workflows. Buildkite REST API calls use a bearer access token and the API v2 base URL.

Common Workflow

local orgs = app.integrations.buildkite.list_organizations({ per_page = 20 })
local pipelines = app.integrations.buildkite.list_pipelines({
  organization = "acme-inc",
  per_page = 20,
})

local builds = app.integrations.buildkite.list_builds({
  organization = "acme-inc",
  pipeline = "deploy",
  branch = "main",
  state = "failed",
})

Trigger a Build

local build = app.integrations.buildkite.create_build({
  organization = "acme-inc",
  pipeline = "deploy",
  payload = {
    commit = "HEAD",
    branch = "main",
    message = "Deploy from agent",
    env = {
      DEPLOY_TARGET = "staging",
    },
  },
})

Buildkite rebuild, cancel, and retry operations require the build number, not the build UUID.

app.integrations.buildkite.retry_failed_jobs({
  organization = "acme-inc",
  pipeline = "deploy",
  number = 42,
  payload = { states = "failed,soft_failed" },
})

Job Diagnostics

local log = app.integrations.buildkite.get_job_log({
  organization = "acme-inc",
  pipeline = "deploy",
  number = 42,
  job_id = "b63254c0-3271-4a98-8270-7cfbd6c2f14e",
})

Raw Helpers

Raw helpers accept only relative API paths. Absolute URLs and parent-directory traversal are rejected.

local user = app.integrations.buildkite.api_get({
  path = "/user",
})

Notes

  • The integration sends Authorization: Bearer <token>.
  • Tool access depends on the scopes granted to the configured Buildkite token.
  • Responses are normalized only for transport errors. Buildkite JSON payloads are otherwise returned as provided by the API.
Raw agent markdown 
# Buildkite

Buildkite tools are available under `app.integrations.buildkite`.

Use this integration to inspect organizations, pipelines, builds, and job diagnostics, or to trigger and manage builds from agent workflows. Buildkite REST API calls use a bearer access token and the API v2 base URL.

## Common Workflow

```lua
local orgs = app.integrations.buildkite.list_organizations({ per_page = 20 })
local pipelines = app.integrations.buildkite.list_pipelines({
  organization = "acme-inc",
  per_page = 20,
})

local builds = app.integrations.buildkite.list_builds({
  organization = "acme-inc",
  pipeline = "deploy",
  branch = "main",
  state = "failed",
})
```

## Trigger a Build

```lua
local build = app.integrations.buildkite.create_build({
  organization = "acme-inc",
  pipeline = "deploy",
  payload = {
    commit = "HEAD",
    branch = "main",
    message = "Deploy from agent",
    env = {
      DEPLOY_TARGET = "staging",
    },
  },
})
```

Buildkite rebuild, cancel, and retry operations require the build number, not the build UUID.

```lua
app.integrations.buildkite.retry_failed_jobs({
  organization = "acme-inc",
  pipeline = "deploy",
  number = 42,
  payload = { states = "failed,soft_failed" },
})
```

## Job Diagnostics

```lua
local log = app.integrations.buildkite.get_job_log({
  organization = "acme-inc",
  pipeline = "deploy",
  number = 42,
  job_id = "b63254c0-3271-4a98-8270-7cfbd6c2f14e",
})
```

## Raw Helpers

Raw helpers accept only relative API paths. Absolute URLs and parent-directory traversal are rejected.

```lua
local user = app.integrations.buildkite.api_get({
  path = "/user",
})
```

## Notes

- The integration sends `Authorization: Bearer <token>`.
- Tool access depends on the scopes granted to the configured Buildkite token.
- Responses are normalized only for transport errors. Buildkite JSON payloads are otherwise returned as provided by the API.
Metadata-derived Lua example 
local result = app.integrations.buildkite.get_current_user({})
print(result)

Functions

get_current_user Read

Get authenticated Buildkite user details.

Lua path
app.integrations.buildkite.get_current_user
Full name
buildkite.buildkite_get_current_user
ParameterTypeRequiredDescription
No parameters.
list_organizations Read

List organizations accessible to the token.

Lua path
app.integrations.buildkite.list_organizations
Full name
buildkite.buildkite_list_organizations
ParameterTypeRequiredDescription
No parameters.
get_organization Read

Get one organization by slug.

Lua path
app.integrations.buildkite.get_organization
Full name
buildkite.buildkite_get_organization
ParameterTypeRequiredDescription
No parameters.
list_pipelines Read

List pipelines in an organization.

Lua path
app.integrations.buildkite.list_pipelines
Full name
buildkite.buildkite_list_pipelines
ParameterTypeRequiredDescription
No parameters.
get_pipeline Read

Get one pipeline by slug.

Lua path
app.integrations.buildkite.get_pipeline
Full name
buildkite.buildkite_get_pipeline
ParameterTypeRequiredDescription
No parameters.
create_pipeline Write

Create a Buildkite pipeline.

Lua path
app.integrations.buildkite.create_pipeline
Full name
buildkite.buildkite_create_pipeline
ParameterTypeRequiredDescription
No parameters.
update_pipeline Write

Update a Buildkite pipeline.

Lua path
app.integrations.buildkite.update_pipeline
Full name
buildkite.buildkite_update_pipeline
ParameterTypeRequiredDescription
No parameters.
archive_pipeline Write

Archive a pipeline.

Lua path
app.integrations.buildkite.archive_pipeline
Full name
buildkite.buildkite_archive_pipeline
ParameterTypeRequiredDescription
No parameters.
unarchive_pipeline Write

Unarchive a pipeline.

Lua path
app.integrations.buildkite.unarchive_pipeline
Full name
buildkite.buildkite_unarchive_pipeline
ParameterTypeRequiredDescription
No parameters.
list Read

List builds for a pipeline.

Lua path
app.integrations.buildkite.list
Full name
buildkite.buildkite_list_builds
ParameterTypeRequiredDescription
No parameters.
get Read

Get one build by number.

Lua path
app.integrations.buildkite.get
Full name
buildkite.buildkite_get_build
ParameterTypeRequiredDescription
No parameters.
create Write

Trigger a new build.

Lua path
app.integrations.buildkite.create
Full name
buildkite.buildkite_create_build
ParameterTypeRequiredDescription
No parameters.
cancel Write

Cancel a build.

Lua path
app.integrations.buildkite.cancel
Full name
buildkite.buildkite_cancel_build
ParameterTypeRequiredDescription
No parameters.
rebuild Write

Rebuild a build by number.

Lua path
app.integrations.buildkite.rebuild
Full name
buildkite.buildkite_rebuild_build
ParameterTypeRequiredDescription
No parameters.
retry_failed_jobs Write

Retry failed jobs for a build.

Lua path
app.integrations.buildkite.retry_failed_jobs
Full name
buildkite.buildkite_retry_failed_jobs
ParameterTypeRequiredDescription
No parameters.
get_job_log Read

Get log output for a build job.

Lua path
app.integrations.buildkite.get_job_log
Full name
buildkite.buildkite_get_job_log
ParameterTypeRequiredDescription
No parameters.
get_job_environment Read

Get environment variables for a build job.

Lua path
app.integrations.buildkite.get_job_environment
Full name
buildkite.buildkite_get_job_environment
ParameterTypeRequiredDescription
No parameters.
api_get Read

Call a safe relative Buildkite GET path.

Lua path
app.integrations.buildkite.api_get
Full name
buildkite.buildkite_api_get
ParameterTypeRequiredDescription
No parameters.
api_post Write

Call a safe relative Buildkite POST path.

Lua path
app.integrations.buildkite.api_post
Full name
buildkite.buildkite_api_post
ParameterTypeRequiredDescription
No parameters.
api_put Write

Call a safe relative Buildkite PUT path.

Lua path
app.integrations.buildkite.api_put
Full name
buildkite.buildkite_api_put
ParameterTypeRequiredDescription
No parameters.
api_patch Write

Call a safe relative Buildkite PATCH path.

Lua path
app.integrations.buildkite.api_patch
Full name
buildkite.buildkite_api_patch
ParameterTypeRequiredDescription
No parameters.
api_delete Write

Call a safe relative Buildkite DELETE path.

Lua path
app.integrations.buildkite.api_delete
Full name
buildkite.buildkite_api_delete
ParameterTypeRequiredDescription
No parameters.