jira_create
Create a JIRA issue from explicit fields or a JFM document, resolving custom fields to satisfy project requirements and avoid HTTP 400 errors. Supports dry-run validation.
Instructions
Create a new JIRA issue, from explicit fields or from a full JFM document (frontmatter + body, e.g. the output of jira_read). With a document, project/summary/issue_type, labels and custom fields come from the frontmatter (project is derived from key: when no project: is set) and the body becomes the description — enabling the read → edit → create round-trip. Explicit project/summary/issue_type override frontmatter and a warning is returned when they do. Without a document, custom_fields is an optional map of field name or canonical id (e.g. {"Story Points": 8} or {"Planned / Unplanned Work": "Unplanned"}) to value, resolved against the create screen and shaped for the API — use it to satisfy fields a project requires at create time (otherwise JIRA returns HTTP 400). The document/description bodies each also accept a filesystem-path form (document_path/description_path) the server reads from disk — prefer it when the body is already on disk, to avoid emitting a large body inline. Set dry_run: true first when uncertain about required fields or formatting — validates and resolves the input and returns the request that would be sent (method, path, body) without creating the issue (mirrors the CLI's omni-dev atlassian jira create --dry-run). Returns the new issue key and self URL as YAML. Creates a single issue; to create several issues at once (and optionally link them, e.g. epic decomposition) use jira_bulk_create.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | When true, validate and return the would-be request (method, path, body) without creating the issue. Defaults to `false`. | |
| project | No | Project key (e.g., `PROJ`). Required unless `document` carries a `project:` (or a `key:` it can be derived from). Overrides frontmatter. | |
| summary | No | Issue summary / title. Required unless `document` carries one. Overrides frontmatter. | |
| document | No | Full JFM document (YAML frontmatter + markdown body), e.g. the output of `jira_read` with the frontmatter edited. When provided, `project`, `summary`, `issue_type`, labels and custom fields are taken from the frontmatter (the project derives from `key:` when no `project:` is set) and the body becomes the description — so the read → edit → create round-trip works without re-specifying fields. The `project`/`summary`/ `issue_type` parameters below still override their frontmatter counterparts (a warning is returned when they do); passing `description` or `custom_fields` together with `document` is an error (put custom fields in the document's `custom_fields:` frontmatter). See resource `omni-dev://specs/jfm`. | |
| issue_type | No | Issue type (defaults to `Task`). Overrides frontmatter. | |
| description | No | Optional description in JFM markdown — see resource `omni-dev://specs/jfm` for syntax. JFM is GitHub-style markdown, NOT JIRA wiki markup (use `##` not `h2.`, triple-backtick fences not `{code}`, backtick inline code not `{{...}}`). Rejected when `document` is provided (the document body is the description). | |
| custom_fields | No | Custom fields to set at create time, as a map of field name *or* canonical id (e.g. `"Story Points"` or `"customfield_10016"`) to its value. Names are resolved against the project/issue-type create screen (`createmeta`), so pass the name back from a `400` "`<Field> is required`" error directly. Values are natural JSON: a string or number for scalar/number/date fields, a string for select/option fields (sent as `{"value": ...}`), an array of strings for multi-selects and labels, an issue key string for issue-link fields such as `Parent` (sent as `{"key": ...}`). Use this for fields a project requires at create time — without them JIRA rejects the create with HTTP 400. To change fields after creation use `jira_edit`. | |
| document_path | No | Filesystem path the server reads the JFM `document` from, instead of `document`. Prefer this when the document is already on disk — it avoids re-emitting the whole document inline. Mutually exclusive with `document`. | |
| description_path | No | Filesystem path the server reads the description from, instead of `description`. Prefer this when the description is already on disk — it avoids re-emitting a large body inline. Mutually exclusive with `description` (and, like `description`, rejected when `document`/`document_path` is given). |