Reference

Workflow API Partly available

A workflow is a Lua script. The script receives two values: ctx, the only way it can act in GitMaster, and input, which holds data only. Each call on ctx runs one GitMaster command, the same kind of command the window and the MCP server run, and each call is recorded in the run journal. For the file layout and how a run starts, see Writing workflows. For the triggers and the rules of each phase, see Triggers and phases.

The module#

A workflow file returns a table with meta and execute:

local M = {}

M.meta = {
  name = "branch-from-ticket",
  description = "Create a branch from a ticket key",
  trigger = { on = "manual" },
  concurrency = "queue",
  inputs = { ticket = { type = "string", prompt = "Ticket key" } },
}

function M.execute(ctx, input)
  local r = ctx.exec({ "ticket-branch-name", input.inputs.ticket }, { timeout = "30s" })
  if ctx.approve("Create branch " .. r.text .. "?") then
    ctx.branch.create({ name = r.text, checkout = true })
  end
end

return M

M.meta#

GitMaster reads M.meta when it loads the file, in a sandbox without ctx. It uses the table to list the workflow and its triggers. No script logic runs at that point.

input#

Effect levels#

Every call has an effect level. The level tells you what the call can change.

Calls#

Calls with named arguments take one table, with the names shown in the Arguments column, such as ctx.branch.create({ name = "fix/login", checkout = true }). The calls ctx.notify, ctx.approve, ctx.exec and ctx.wait take their arguments positionally, as shown.

A dash (—) in the Result column means the call returns no fields that scripts rely on.

Outcomes are the values a call can end with, as listed in the action catalog. A value other than done raises an error unless the call runs inside ctx.try. The section Outcomes and errors below gives the rules.

Interaction#

The catalog declares one wait event: restack.resumed. It is used after a restack conflict, so that the run can continue once the conflict is resolved. The wait ends with resumed when you choose Continue restack after resolving the conflict, and with aborted when you cancel that resolution. Both carry branch, the branch that conflicted, and commit, the commit that was replayed. Waits exist only while the app is open.

Process#

ctx.exec runs a program directly, never through a shell:

• argv is a list. Each element is one argument. A value placed in an element stays one argument, even when it contains spaces or flags, so repository content cannot add options or commands.
• stdin carries large text. Send a diff as stdin, not inside argv.
• timeout accepts a positive whole number followed by s, m or h, such as "30s", "2m" or "1h". The default is 30s. When the time runs out, the program is killed and the call ends with timeout.
• text is the standard output with the spaces at both ends removed. exit_code is the exit status of the program.
• A non-zero exit ends the call with failed. The standard error of the program is shown.
• With format = "json", the standard output must be JSON. The parsed value is in the result.
• Output from a program is untrusted. A propose action, such as ctx.commit.suggest_message, takes it only as a suggestion, and you decide. After any ctx.exec in a run, every later apply action asks you for approval and shows the resolved arguments.

local r = ctx.exec({ "llm-cli", "-p", "Write a conventional commit message for this diff. Reply with the message only." },
                   { stdin = input.repo.staged_diff, timeout = "60s" })

Staging and commits#

Branches#

Remote#

Stacks#

Restack#

A plan's plan_id is tied to the commits of the branches when the plan was made. If a branch has moved since then, ctx.restack.apply ends with stale. A restack conflict ends ctx.restack.apply with conflict. The branches that do not conflict are moved first, as in the window: only the conflicting branch and the branches under it wait. A plan that moves some branches and refuses others ends with done; the refused branches stay where they are, with their reasons in the plan. ctx.restack.apply has no interrupted outcome, because restack has its own recovery steps.

Reparent#

A reparent moves everything or nothing. If any branch of the plan conflicts or is refused, ctx.reparent.apply ends with failed and no branch moves. If a branch has moved since the plan, it also ends with failed. Undoing it with Undo restack also puts the old parent back.

Verdicts#

A verdict is data recorded by an agent. Its text is untrusted. Use value, stale and the severities to decide, and do not run text from a verdict. See Reviewers and gates.

Helpers#

These calls do not act on the repository, so they have no effect level or outcome.

Outcomes and errors#

• A call that ends with an outcome other than done raises an error. The run stops there. An outcome such as conflict or stale never passes silently.
• ctx.try(fn) returns the outcome instead of raising. Use it when the script handles the outcome itself:

local plan = ctx.restack.plan({ root = input.trigger.branch })
local r = ctx.try(function() return ctx.restack.apply({ plan_id = plan.plan_id }) end)
if r.outcome == "conflict" then
  local w = ctx.wait("restack.resumed", { timeout = "24h" })
  if w.outcome ~= "resumed" then return ctx.fail("conflict not resolved") end
elseif r.outcome ~= "done" then
  return ctx.fail("restack " .. r.outcome)
end

• An applying action that was in progress when the app stopped, and has no recorded result, ends with interrupted. It never runs again.
• A call to a name that is not in ctx fails with the list of valid names at that level, so the caller can correct the name from the message.
• Every call is written to the run journal, with its sequence number, function, resolved arguments, result, outcome and duration. Approval decisions belong to GitMaster. The script does not decide them.

Return value by phase#

What M.execute returns depends on the trigger.

Sandbox#

The script runs in a Lua virtual machine that is part of the app.

• These libraries are removed: io, os, debug and package. These functions are removed: require, load, loadstring, loadfile, dofile, print, warn, collectgarbage, getfenv, setfenv and newproxy. So is string.dump.
• The sources of nondeterminism are removed as well: math.random and math.randomseed, and the clock of os. Use ctx.now() and ctx.random() instead. Both are recorded in the journal.
• The global environment is read-only and is created new for each run. One run cannot change what the next run sees.
• The script has no authority of its own. Everything it does passes through ctx.
• The sandbox protects GitMaster and your repository from the logic of the script. It does not protect you from a program that the script launches. ctx.exec runs programs that you choose, and the approval rules apply to the calls that follow it. See Approvals and security.

Cancelling a run stops the script. A call that is waiting, such as ctx.approve, ctx.wait or ctx.exec, ends at once, and cancelling ctx.exec kills the program it started.

Waits and their timeouts are kept in memory. Closing the app ends a run in progress, and the next start shows that run as interrupted.

Budgets#

Each run has budgets for:

• instructions executed,
• total elapsed time,
• memory,
• string size,
• call depth,
• the number of ctx calls.

A run that exceeds a budget ends as failed, with the reason.