> For the complete documentation index, see [llms.txt](https://docs.kira.thiennguyen.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kira.thiennguyen.dev/extension-development/manifest-and-bundle.md). # Manifest & Bundle Format ## The `.kext` bundle A `.kext` is a **zip** containing `manifest.json` at the root plus the action source files: ``` trigger.kext (zip) ├── manifest.json ├── icon.svg # optional └── actions/ ├── trigger.go └── report.go ``` **Limits:** bundle ≤ 5 MB (compressed), ≤ 2 MB per file, ≤ 200 files. Paths must be relative and in-tree (no `..`, no absolute paths). Build one with `zip`: ```sh cd my-extension/ # contains manifest.json + actions/ zip -r ../my-extension.kext manifest.json actions ``` ## The manifest ```json { "id": "trigger", "name": "Trigger", "description": "Fire deploy webhooks.", "version": "1", "minKiraVersion": "1.1.2", "icon": "icon.svg", "account": "111122223333", "role": "AdminRole", "region": "ap-southeast-2", "config": { "webhookUrl": "https://example.com/deploy", "retry": { "max": 3 } }, "actions": [ { "id": "staging", "label": "Staging", "entry": "actions/trigger.go", "contextMode": "custom", "account": "444455556666", "role": "psc-admin", "region": "us-east-1", "config": { "secretKey": "/svc/stg/key" } }, { "id": "report", "label": "Report", "entry": "actions/report.go", "contextMode": "none" } ] } ``` ### Top-level fields | Field | Required | Notes | | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | ✓ | Stable id, `[A-Za-z0-9._-]+`. Identifies the install on disk. | | `name` | ✓ | Display name. | | `description` | | Shown under the name. | | `version` | | The extension's own version (free text), shown as a pill. | | `minKiraVersion` | | Minimum Kira version, e.g. `"1.1.2"`. On older Kira the actions are **disabled** with a red `Kira ≥ X` badge and won't run. Dev builds satisfy any requirement. | | `icon` | | Path inside the bundle to a logo (`png`/`jpg`/`svg`/`webp`/`gif`, ≤ 512 KB). Square images look best; falls back to a default glyph. | | `account` / `role` / `region` | | **Extension-level** default account context (see [Account context](#account-context-contextmode)). | | `config` | | Free-form JSON (flat or nested) the scripts read (see [Config](#config)). | | `actions` | ✓ | At least one. | ### Action fields | Field | Required | Notes | | ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `id` | ✓ | Unique within the extension, `[A-Za-z0-9._-]+`. | | `label` | ✓ | Button text. | | `entry` | ✓ | Path to the `.go` file inside the bundle. Several actions may share one file. | | `icon` | | Path inside the bundle to a button glyph (same formats/limit as above). Replaces the default play glyph on this button. | | `tooltip` | | Hover text for the button. Overrides the default account-context hint. | | `hideTooltip` | | `true` suppresses the button's resting tooltip entirely. Transient messages (incompatible / running) still show. | | `contextMode` | | `inherit` (default) \| `custom` \| `none`. See below. | | `account` / `role` / `region` | | Used only when `contextMode` is `custom`. | | `config` | | Per-action config; its keys override the extension-level `config`. | ## Account context (`contextMode`) Some actions touch AWS (resolve a secret, call an API in an account); others don't. Each action declares how it gets its account/role/region: | Mode | Behaviour | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `inherit` (default) | Use the **extension-level** `account`/`role`/`region`. If those are empty, Kira **prompts** the user on run (with a "Save for next run" option). | | `custom` | Use the action's **own** `account`/`role`/`region`. (Setting just `account` with no mode is treated as `custom`.) | | `none` | The action needs **no account** — never prompts, shows no account UI. For scripts that don't call `k.Secret` / AWS. | Inside a script, `k.Account()` returns the resolved `(id, role, region)`, and `k.Secret(...)` resolves against it. Users can override an action's account later via the **Configure** (gear) dialog. ## Config `config` is free-form JSON, set at the **extension level** (shared) and/or **per action** (overrides). Merge order: extension-level keys first, then the action's keys on top (action wins). Read it from a script: ```go url := k.Config("webhookUrl") // string (objects/arrays come back as JSON text) v, ok := k.ConfigValue("retry") // raw decoded value for nested access if ok { retry := v.(map[string]any) max := int(retry["max"].(float64)) // numbers decode as float64 } // or unmarshal the whole merged config into a struct: var cfg struct { WebhookURL string `json:"webhookUrl"` Retry struct{ Max int `json:"max"` } `json:"retry"` } _ = k.ConfigInto(&cfg) ``` See [The kira SDK](/extension-development/sdk-reference.md) for the full set of config and runtime methods. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kira.thiennguyen.dev/extension-development/manifest-and-bundle.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.