GAIA

Appearance

Create a ticket ​

You'll learn the four ways to create a ticket, what each one gives you, and which to reach for.

A ticket needs a title, a Markdown description, a workflow (gaia_feature, gaia_bug or gaia_chore), a project, and usually a work:* label. Everything else — identifier, branch name, base branch, state — the control plane fills in. Three of the paths below leave the ticket in qualification; an import enters at the state its type label implies.

In the cockpit: the new-ticket popup ​

In gaia ui, press n. The popup opens on the project you are in and offers the fields above, plus the conductor that should pick the ticket up — preselected to this checkout's own conductor when you started gaia ui inside a connected repository.

Two ways out of the popup:

  • Create directly (Ctrl+D) writes the ticket as you typed it, into qualification. The engine config gaia conductor init generates does not serve that state, so the ticket waits there for a human, for the create agent, or for a conductor whose states include qualification.
  • Create with agent (Ctrl+S) starts a ticket-create agent session instead: it interviews you, drafts description and acceptance criteria, creates the ticket, publishes the qualification handoff and routes it to spec or diagnose — where the conductor set on it claims it. The session lives on the project's Ticket-Agents tab and can be hidden and re-attached.

Create directly when you will qualify the ticket yourself or your conductor serves qualification; hand it to the agent when you want it worked without further ado. Details on the popup's keys: Using gaia ui.

In Claude Code: the /gaia skill ​

Teams that use Claude Code install the GAIA plugin from GAIA's own marketplace and create tickets from any conversation with /gaia:

/plugin marketplace add https://git.key-tec.de/keytec/gaia.git
/plugin install gaia@gaia

(The HTTPS URL clones without credentials; git@git.key-tec.de:keytec/gaia.git works too if you prefer SSH and have a key on the host.)

The create-ticket skill collects title, project, workflow, description, acceptance criteria, priority and relations, creates the ticket, publishes its qualification handoff and routes it — so a ticket created this way arrives already qualified and never waits in qualification for a conductor.

This is the path the GAIA team uses for its own tickets, and the one to prefer when the ticket comes out of a discussion you are already having with an agent.

Import an external issue ​

The control plane imports an issue from a connected tracker into a canonical GAIA ticket, keeping the source URL as the ticket's origin. The import is one JSON:API action:

sh
curl -X POST "$BASE_URL/jsonapi/gaia_ticket/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data":{"attributes":{"url":"https://git.example.com/group/repo/-/issues/42"}}}'

It answers 201 with the new ticket, or 200 when the issue was imported before and the ticket was updated instead. The caller needs the import gaia tickets permission, and the control plane needs a connector for that tracker (its base URL and an API token, configured by an administrator). Re-importing is safe: source identity is deterministic, so the same issue never becomes two tickets. From then on GAIA mirrors the ticket's state back to the issue as a label — GitLab: import and origin labels.

With gaia dropsh ​

For scripts, or when you want full control over the fields, write the JSON:API envelope to a file and create it through the shell. Dry-run first — the dry run validates the envelope against the schema without writing:

json
{
  "data": {
    "type": "gaia_ticket--gaia_ticket",
    "attributes": {
      "workflow": "gaia_feature",
      "title": "Show the run count on the project row",
      "description": { "value": "## Context\n\n…", "format": "gaia_rich" },
      "priority": 2
    },
    "relationships": {
      "project_id": { "data": { "type": "gaia_project--gaia_project", "id": "<project uuid>" } },
      "labels": { "data": [{ "type": "gaia_term--gaia_labels", "id": "<work:code uuid>" }] }
    }
  }
}
sh
gaia dropsh --auth-profile pm schema gaia_ticket/gaia_ticket --for create   # the fields
gaia dropsh --auth-profile pm create gaia_ticket --bundle gaia_ticket --data @ticket.json --dry-run
gaia dropsh --auth-profile pm create gaia_ticket --bundle gaia_ticket --data @ticket.json

Use the pm profile — creating tickets is project-manager work. Leave out identifier, state, branch and author: the server owns them. Write the description as Markdown in the gaia_rich format; HTML is accepted and then renders empty. The uuids of projects and labels come from gaia dropsh search gaia_project --bundle gaia_project and gaia dropsh search gaia_term --bundle gaia_labels.

Which path?

Cockpit popup for a ticket you can type in a minute. /gaia when the ticket grows out of a conversation. Import when the work already exists as an issue somewhere else. dropsh for scripts and bulk creation.

Next ​