Import an issue of the project’s GitHub repository into a bug
const url = 'https://beta-api.plune.ai/v1/bugs/github/import';const options = { method: 'POST', headers: { cookie: 'plune_session=<plune_session>', 'Content-Type': 'application/json' }, body: '{"ref":"https://github.com/acme/shop/issues/1"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://beta-api.plune.ai/v1/bugs/github/import \ --header 'Content-Type: application/json' \ --cookie plune_session=<plune_session> \ --data '{ "ref": "https://github.com/acme/shop/issues/1" }'The owner’s (ADR 0083 §2): ref is a link to an issue of the connected repository (https://github.com/{owner}/{repo}/issues/{n}) or its number (#12). Another repository or host is refused (400 github_other_repository) before GitHub is asked. The issue is read (GET /repos/{owner}/{repo}/issues/{n}) and the bug that mirrors it is made, source github, its state GitHub’s (open → new, closed → done: closed in Plune) - 201; or brought up to date - 200. One live bug per issue. Refused as Jira’s import is: 409 bugs_disabled, github_not_working, github_mirror_exists; 404 github_issue_unavailable; 424 github_token_rejected, github_rate_limited (with retryAfterSec from GitHub’s headers), github_unreachable. Session cookie only. Audited on the bug.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters ”Which of your projects to act in — an id from GET /v1/projects. Absent, your default project. A project you are not a member of answers 404, the same as one that does not exist. Ignored under a bearer token, which is bound to the project it was minted in.
Request Body required
Section titled “Request Body required ”object
A link to an issue of the connected repository, or #n.
Example
{ "ref": "https://github.com/acme/shop/issues/1"}Responses
Section titled “ Responses ”The bug that mirrors the issue, up to date
object
object
The bug’s name for people (BUG-12): the project’s own number, handed out in order, never reused and never changed.
Whose truth the row is. plune is a bug of the project’s own - a mirror the filter left and an owner adopted too (POST /v1/bugs/{id}/adopt), its Jira issue kept; jira mirrors an issue of the project’s Jira, made by POST /v1/bugs/jira/import (#1069): its title and description are Jira’s, brought up to date by each import, a PATCH of them or of state is 409 jira_field, and its streak never closes it - under after_n it tells «can be closed», as under manual (ADR 0057 §3).
The author’s user id, to be named from GET /v1/members; null when the account is gone.
The live cases linked to the bug.
The evidence rows the bug holds (#2549). At 10 it is full: POST /v1/bugs/{id}/evidence is 409 evidence_limit.
The copies of pictures the bug’s evidence holds (#2549), against the 30 a bug keeps: 30 - evidenceFileCount more can be copied. A person’s own files (POST /v1/bugs/{id}/files) are not counted.
«Passed X of N» (#1067, ADR 0057 §4). A linked case counts its green runs in a row while the bug is open - a mirror while Jira has not closed it (externalClosed, #2327): passed adds one, failed or broken resets, blocked, skipped and a muted result neither add nor reset; a run is one verdict, as the run itself counts the case - its latest result in each combination (a retry that passed is a pass), then the worst of the combinations; green counts once every combination of the run has a result, red at once (a failure in any combination); only a run newer than the one last counted and made after the case was linked counts, and with an environment in the rule only a run on it.
object
The smallest streak among the live linked cases that are not muted (#2163); 0 with none.
N of the project rule (bugs.close.n of the settings).
The bug is open (a mirror: externalClosed is not true, #2327), has a live case that is not muted, and every such case has N in a row - and nobody put it off for this series (POST /v1/bugs/{id}/wait, #2163). Under the rule after_n the bug then closes itself, unless flaky, a linked case is muted (isMuted of cases) or the bug mirrors a Jira issue (source jira, #1069), which it only tells.
A live linked case that is not muted is flaky: the streak is weak proof, and the rule after_n only tells, it does not close.
Closed by its streak (the rule after_n), not by a person (#1067). A person’s close or reopen sets it back to false.
Open again because a linked case failed after its streak closed it - the list’s badge of a regression (#2163). A person’s move clears it.
The key of the Jira issue the bug mirrors (ACME-123), as Jira last gave it (#1069). null on a bug of Plune’s own - as every external… field.
The issue in Jira: https://<site>/browse/<key>.
The name of the issue’s status in Jira at the last import.
The key of that status’s category, as Jira gives it: new, indeterminate, done or undefined.
externalStatusCategory is done: Jira counts the issue finished (ADR 0057 §3). The bug’s own state does not follow it; its streak does - a mirror Jira closed counts nothing, is not streak.canBeClosed, and a failure of its case tells bug.fails_again, as a bug of Plune’s closed by a person (#2327).
The name of the issue’s priority; null when it has none.
The name Jira shows for the assignee - never the e-mail; null when nobody is assigned.
The files of the issue as Jira names them, the first 100. Plune copies none (ADR 0072 §7).
object
Bytes, as Jira counts them.
Jira’s link to the file (content of its metadata) when it is on the site of the project’s connection, null otherwise. It opens in the person’s own Jira session: Plune does not fetch it.
When the issue last changed in Jira, as the last import read it.
When Plune last read the issue into the bug.
When the mirror was cut from its issue (ADR 0057 §11): its external… fields stay the last snapshot and no poll brings them up to date - but a left_filter mirror whose issue the filter brings again is attached again, and this is null once more. null on a mirror still attached and on a bug of Plune’s.
Why it was cut, with detachedAt. left_filter (#1070): the daily full pass of the project’s poll by filter no longer found the issue in the filter. The bug is not deleted; once a pass finds the issue in the filter again, the mirror is attached again (both null).
Where a mirror came from (#1070): filter - the project’s poll by filter brought it; link - a person imported it by its link (POST /v1/bugs/jira/import), and that claim stays. Only a filter mirror is ever marked left_filter. null on a bug of Plune’s and on a mirror from before the poll whose origin is not known.
Markdown, at most 16384 bytes; shown by the safe component. null - none.
Why the last move of state was made: manual, the words the person gave, or Plune’s own (#1067): automatically after N green runs in a row, regression after auto-close. null - never moved.
The live cases linked to the bug, by title.
object
Green runs of the case in a row, counted while the bug is open - a mirror while Jira has not closed the issue (#2327); from 0 again after a reopen, by a person or by Jira (#1067).
Muted (#1246): left out of «every case has N»; while it is linked the rule after_n tells «can be closed» and does not close (#2163).
The suite the case is in, for the path the card shows under its title (#2163); null - at the root.
The status of the latest result of the case, read as a linked case of a requirement reads it - a muted failure is muted (#2163); null - no result yet.
User ids of the people who are told about the bug: the author, and whoever pressed «watch».
Whether the caller is one of them. The one field of the card that depends on who asks.
The failed results the bug was made from or added to, oldest first (#1066, ADR 0057 §6).
object
The result, while it is there and its run is out of the Bin - a link that opens; null otherwise. The snapshot keeps the id.
Its run, on the same terms.
present; deleted_by_cleanup - the plan’s cleanup of old history removed it (#1049); deleted - any other road (the Bin, a deleted case). Kept when the result goes: it cannot be read back after.
The result as it was when the evidence was taken, cleaned of credentials as every reader cleans it: result (status, raw status, source, sub-status, outcome, expected status, muted, case version, duration, params, when), errorContext (at most 16384 bytes; a longer one is cut and ends with …[truncated N bytes], and errorContextTruncated is true), failure (headline, steps, place, CI link - not the artifacts), steps (a person’s marks), case (id, title, keys, flaky and muted then), run (id, title, environment, started), takenBy, takenAt.
object
The pictures named that were not copied, and why. The evidence is written all the same.
object
null when the id named no picture of the result.
limit - over 10 a call or 30 a bug; budget - the bug’s copies in Plune’s storage would take more than half of the file budget; storage - the project’s bucket did not make the copy; missing - not a picture of that result (gone, a text, or never one).
The bug’s copies of the pictures of its evidence, oldest first. Read by GET /v1/files/{id} (one in the project’s bucket by GET /v1/files/{id}/link), by anyone who reads the bug; never deleted alone (DELETE /v1/files/{id} is a 409 evidence_file), they go with the bug.
object
db: the bytes are GET /v1/files/{id}; bucket: a new object in a bucket, read by GET /v1/files/{id}/link — in the project’s bucket under a key of the bug’s, or (a built-in picture, #1428) in Plune’s own beside it.
A mirror marked verified in this series (#1071, Р319): when; null otherwise, and always on a bug of Plune’s.
What the write to Jira did for the last verification (#1071); null when none was asked.
object
The series verified: the event’s number, part of the comment’s marker.
userId of who marked it verified.
When the comment went to Jira.
The screenshots of the passing results attached.
The pictures of the passing results not attached: gone, over 2 MiB or over Jira’s upload limit, in a bucket (the project’s or Plune’s own) that could not be reached or read whole then, or past the 60 a comment carries.
The result files already attached to the issue for this verification: a try after a stop between two sends only the rest.
null: no transition in the table.
object
What the streak last did, while it is the last move of the state; null after a person’s move, or when the streak never moved it (#2163).
object
The run of the move; null once it is in the Bin or gone.
object
The environment of that run, as it was then.
The case that failed - a regression’s; null on a close, or once the case is in the Bin or gone.
object
true - a new bug; false - the live bug that mirrors the issue, brought up to date.
Example
{ "bug": { "id": "7b3e1d2c-0000-4000-8000-00000000e069", "key": "BUG-13", "number": 13, "source": "github", "title": "Checkout fails", "state": "open", "createdBy": "6f1c2b3a-0000-4000-8000-0000000000a2", "caseCount": 0, "commentCount": 0, "evidenceCount": 0, "evidenceFileCount": 0, "createdAt": "2026-09-16T09:12:04.151Z", "updatedAt": "2026-09-16T09:12:04.151Z", "streak": { "passed": 0, "n": 3, "canBeClosed": false, "flaky": false }, "autoClosed": false, "reopenedByRegression": false, "externalKey": "acme/shop#1", "externalUrl": "https://github.com/acme/shop/issues/1", "externalStatus": "open", "externalStatusCategory": "new", "externalClosed": false, "externalPriority": null, "externalAssignee": null, "externalAttachments": [], "externalUpdated": "2026-11-14T08:00:00.000Z", "externalSyncedAt": "2026-09-16T09:12:04.151Z", "detachedAt": null, "detachedReason": null, "jiraVia": "link", "projectId": "u-shop::default", "description": null, "stateReason": null, "closedAt": null, "closedBy": null, "cases": [], "watchers": [ "6f1c2b3a-0000-4000-8000-0000000000a2" ], "watching": true, "evidence": [], "files": [], "streakMove": null, "verifiedAt": null, "jiraWrite": null }, "created": false}A new bug
object
object
The bug’s name for people (BUG-12): the project’s own number, handed out in order, never reused and never changed.
Whose truth the row is. plune is a bug of the project’s own - a mirror the filter left and an owner adopted too (POST /v1/bugs/{id}/adopt), its Jira issue kept; jira mirrors an issue of the project’s Jira, made by POST /v1/bugs/jira/import (#1069): its title and description are Jira’s, brought up to date by each import, a PATCH of them or of state is 409 jira_field, and its streak never closes it - under after_n it tells «can be closed», as under manual (ADR 0057 §3).
The author’s user id, to be named from GET /v1/members; null when the account is gone.
The live cases linked to the bug.
The evidence rows the bug holds (#2549). At 10 it is full: POST /v1/bugs/{id}/evidence is 409 evidence_limit.
The copies of pictures the bug’s evidence holds (#2549), against the 30 a bug keeps: 30 - evidenceFileCount more can be copied. A person’s own files (POST /v1/bugs/{id}/files) are not counted.
«Passed X of N» (#1067, ADR 0057 §4). A linked case counts its green runs in a row while the bug is open - a mirror while Jira has not closed it (externalClosed, #2327): passed adds one, failed or broken resets, blocked, skipped and a muted result neither add nor reset; a run is one verdict, as the run itself counts the case - its latest result in each combination (a retry that passed is a pass), then the worst of the combinations; green counts once every combination of the run has a result, red at once (a failure in any combination); only a run newer than the one last counted and made after the case was linked counts, and with an environment in the rule only a run on it.
object
The smallest streak among the live linked cases that are not muted (#2163); 0 with none.
N of the project rule (bugs.close.n of the settings).
The bug is open (a mirror: externalClosed is not true, #2327), has a live case that is not muted, and every such case has N in a row - and nobody put it off for this series (POST /v1/bugs/{id}/wait, #2163). Under the rule after_n the bug then closes itself, unless flaky, a linked case is muted (isMuted of cases) or the bug mirrors a Jira issue (source jira, #1069), which it only tells.
A live linked case that is not muted is flaky: the streak is weak proof, and the rule after_n only tells, it does not close.
Closed by its streak (the rule after_n), not by a person (#1067). A person’s close or reopen sets it back to false.
Open again because a linked case failed after its streak closed it - the list’s badge of a regression (#2163). A person’s move clears it.
The key of the Jira issue the bug mirrors (ACME-123), as Jira last gave it (#1069). null on a bug of Plune’s own - as every external… field.
The issue in Jira: https://<site>/browse/<key>.
The name of the issue’s status in Jira at the last import.
The key of that status’s category, as Jira gives it: new, indeterminate, done or undefined.
externalStatusCategory is done: Jira counts the issue finished (ADR 0057 §3). The bug’s own state does not follow it; its streak does - a mirror Jira closed counts nothing, is not streak.canBeClosed, and a failure of its case tells bug.fails_again, as a bug of Plune’s closed by a person (#2327).
The name of the issue’s priority; null when it has none.
The name Jira shows for the assignee - never the e-mail; null when nobody is assigned.
The files of the issue as Jira names them, the first 100. Plune copies none (ADR 0072 §7).
object
Bytes, as Jira counts them.
Jira’s link to the file (content of its metadata) when it is on the site of the project’s connection, null otherwise. It opens in the person’s own Jira session: Plune does not fetch it.
When the issue last changed in Jira, as the last import read it.
When Plune last read the issue into the bug.
When the mirror was cut from its issue (ADR 0057 §11): its external… fields stay the last snapshot and no poll brings them up to date - but a left_filter mirror whose issue the filter brings again is attached again, and this is null once more. null on a mirror still attached and on a bug of Plune’s.
Why it was cut, with detachedAt. left_filter (#1070): the daily full pass of the project’s poll by filter no longer found the issue in the filter. The bug is not deleted; once a pass finds the issue in the filter again, the mirror is attached again (both null).
Where a mirror came from (#1070): filter - the project’s poll by filter brought it; link - a person imported it by its link (POST /v1/bugs/jira/import), and that claim stays. Only a filter mirror is ever marked left_filter. null on a bug of Plune’s and on a mirror from before the poll whose origin is not known.
Markdown, at most 16384 bytes; shown by the safe component. null - none.
Why the last move of state was made: manual, the words the person gave, or Plune’s own (#1067): automatically after N green runs in a row, regression after auto-close. null - never moved.
The live cases linked to the bug, by title.
object
Green runs of the case in a row, counted while the bug is open - a mirror while Jira has not closed the issue (#2327); from 0 again after a reopen, by a person or by Jira (#1067).
Muted (#1246): left out of «every case has N»; while it is linked the rule after_n tells «can be closed» and does not close (#2163).
The suite the case is in, for the path the card shows under its title (#2163); null - at the root.
The status of the latest result of the case, read as a linked case of a requirement reads it - a muted failure is muted (#2163); null - no result yet.
User ids of the people who are told about the bug: the author, and whoever pressed «watch».
Whether the caller is one of them. The one field of the card that depends on who asks.
The failed results the bug was made from or added to, oldest first (#1066, ADR 0057 §6).
object
The result, while it is there and its run is out of the Bin - a link that opens; null otherwise. The snapshot keeps the id.
Its run, on the same terms.
present; deleted_by_cleanup - the plan’s cleanup of old history removed it (#1049); deleted - any other road (the Bin, a deleted case). Kept when the result goes: it cannot be read back after.
The result as it was when the evidence was taken, cleaned of credentials as every reader cleans it: result (status, raw status, source, sub-status, outcome, expected status, muted, case version, duration, params, when), errorContext (at most 16384 bytes; a longer one is cut and ends with …[truncated N bytes], and errorContextTruncated is true), failure (headline, steps, place, CI link - not the artifacts), steps (a person’s marks), case (id, title, keys, flaky and muted then), run (id, title, environment, started), takenBy, takenAt.
object
The pictures named that were not copied, and why. The evidence is written all the same.
object
null when the id named no picture of the result.
limit - over 10 a call or 30 a bug; budget - the bug’s copies in Plune’s storage would take more than half of the file budget; storage - the project’s bucket did not make the copy; missing - not a picture of that result (gone, a text, or never one).
The bug’s copies of the pictures of its evidence, oldest first. Read by GET /v1/files/{id} (one in the project’s bucket by GET /v1/files/{id}/link), by anyone who reads the bug; never deleted alone (DELETE /v1/files/{id} is a 409 evidence_file), they go with the bug.
object
db: the bytes are GET /v1/files/{id}; bucket: a new object in a bucket, read by GET /v1/files/{id}/link — in the project’s bucket under a key of the bug’s, or (a built-in picture, #1428) in Plune’s own beside it.
A mirror marked verified in this series (#1071, Р319): when; null otherwise, and always on a bug of Plune’s.
What the write to Jira did for the last verification (#1071); null when none was asked.
object
The series verified: the event’s number, part of the comment’s marker.
userId of who marked it verified.
When the comment went to Jira.
The screenshots of the passing results attached.
The pictures of the passing results not attached: gone, over 2 MiB or over Jira’s upload limit, in a bucket (the project’s or Plune’s own) that could not be reached or read whole then, or past the 60 a comment carries.
The result files already attached to the issue for this verification: a try after a stop between two sends only the rest.
null: no transition in the table.
object
What the streak last did, while it is the last move of the state; null after a person’s move, or when the streak never moved it (#2163).
object
The run of the move; null once it is in the Bin or gone.
object
The environment of that run, as it was then.
The case that failed - a regression’s; null on a close, or once the case is in the Bin or gone.
object
true - a new bug; false - the live bug that mirrors the issue, brought up to date.
Example
{ "bug": { "id": "7b3e1d2c-0000-4000-8000-00000000e069", "key": "BUG-13", "number": 13, "source": "github", "title": "Checkout fails", "state": "open", "createdBy": "6f1c2b3a-0000-4000-8000-0000000000a2", "caseCount": 0, "commentCount": 0, "evidenceCount": 0, "evidenceFileCount": 0, "createdAt": "2026-09-16T09:12:04.151Z", "updatedAt": "2026-09-16T09:12:04.151Z", "streak": { "passed": 0, "n": 3, "canBeClosed": false, "flaky": false }, "autoClosed": false, "reopenedByRegression": false, "externalKey": "acme/shop#1", "externalUrl": "https://github.com/acme/shop/issues/1", "externalStatus": "open", "externalStatusCategory": "new", "externalClosed": false, "externalPriority": null, "externalAssignee": null, "externalAttachments": [], "externalUpdated": "2026-11-14T08:00:00.000Z", "externalSyncedAt": "2026-09-16T09:12:04.151Z", "detachedAt": null, "detachedReason": null, "jiraVia": "link", "projectId": "u-shop::default", "description": null, "stateReason": null, "closedAt": null, "closedBy": null, "cases": [], "watchers": [ "6f1c2b3a-0000-4000-8000-0000000000a2" ], "watching": true, "evidence": [], "files": [], "streakMove": null, "verifiedAt": null, "jiraWrite": null }, "created": true}Invalid body, or github_other_repository / github_no_issue; GitHub was not asked
object
Example generated
{ "error": "example"}No / invalid session — a CLI token is refused here
object
Example
{ "error": "sign in required"}Not the project’s owner; or (with TIER_LIMITS_ENFORCE=true) a tier without the issue_trackers permission, with feature and tier
object
Example
{ "error": "project owner only"}github_issue_unavailable: no such issue, moved to another repository, or a pull request
object
Example generated
{ "error": "example"}bugs_disabled, github_not_working (with state), or github_mirror_exists
object
Example generated
{ "error": "example"}github_token_rejected (the connection becomes rejected), github_rate_limited (retryAfterSec), github_unreachable
object
Example generated
{ "error": "example"}Two refusals share this status, and what to do about them is opposite. Rate-limited — the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442, #2092): Retry-After carries the seconds until the window rolls over, and waiting that long is the way out. Quota reached — a ceiling on what the project holds (runs in the last 24 hours, test cases, items waiting in the review queue, rules in force in the project’s memory): { error, quota }. A retry straight away frees nothing, so do not loop on it; the message says what makes room — deleting cases, working the queue down, an operator raising the limit — and the run quota, a rolling 24 hours, frees its oldest runs as they age out. Tell the two apart by the body: a 429 whose body has a quota object is a quota, one without it is a throttle. quota carries kind, limit, used, remaining and resetsAt: the figures behind the sentence, and for the run quota the instant its oldest run ages out (#1258). Retry-After is sent on a quota only where there is such an instant (the run quota: the whole seconds, at least 1, until resetsAt); the case, review-queue and project quotas free only by an action, have resetsAt: null, and send no Retry-After. GET /v1/quotas reads the same figures without a refusal.
object
The body of a 429 that is a quota and not a throttle: the sentence, and the figures behind it.
object
What was reached and the way out.
object
The ceiling. A write that would take used past it is refused with 429.
What the project holds now, counted by the same query that refuses a write.
limit - used, never below 0.
When the oldest counted run ages out of the rolling 24 hours and a slot frees on its own. null for the two quotas only an action frees (delete cases, decide queue items), and for a run quota with no runs in the window.
Examples
A throttle: no `quota`; wait `Retry-After`
{ "error": "rate limit exceeded — slow down"}A quota (#2458): the MCP server ceiling; `resetsAt` is null, nothing frees it by waiting
{ "error": "MCP server quota reached — at most 50 servers per project, and a server cannot be removed yet. Ask an operator to raise the limit.", "quota": { "kind": "mcpServersPerProject", "limit": 50, "used": 50, "remaining": 0, "resetsAt": null }}Headers
Section titled “Headers ”Seconds until the window rolls over on a throttle; on a quota, until quota.resetsAt — sent only for the run quota, which has one
The server has no INTEGRATIONS_ENCRYPTION_KEY; GitHub was not asked
object
Example generated
{ "error": "example"}