Issues

Calls

const open = await forge.issues.list("owner", "repo", { state: "open", perPage: 30 });
const found = await forge.issues.search("owner", "repo", "hydration mismatch", { state: "all" });
const one = await forge.issues.get("owner", "repo", 42);
const comments = await forge.issues.listComments("owner", "repo", 42, { perPage: 50 });
const comment = await forge.issues.getComment("owner", "repo", 42, comments.items[0]!.id);
const posted = await forge.issues.createComment("owner", "repo", 42, { body: "Fixed in #43." });
const reactions = await forge.issues.listReactions("owner", "repo", 42);

const created = await forge.issues.create("owner", "repo", {
  title: "Broken link on the deploy page",
  body: "The Cloudflare link 404s.",
  labels: ["docs"],
  assignees: ["someone"],
});

const closed = await forge.issues.update("owner", "repo", 42, {
  state: "closed",
  removeLabels: ["needs-triage"],
});

ListOptions is cursor, perPage and state, and state is open, closed or all.

The shape

interface Issue {
  id: string;
  number: number; // GitLab iid, not the global id
  title: string;
  body: string;
  state: "open" | "closed";
  labels: string[];
  author: { login: string };
  assignees: { login: string }[];
  createdAt: string;
  updatedAt: string;
  url: string;
}

GitHub's /issues endpoint returns pull requests too, which is a trap the first time. They are filtered out here by the missing pull_request key, so issues.list on GitHub is issues only.

Search

search keeps the platform's own syntax. GitHub qualifiers like label:bug is:open work on GitHub. GitLab and Gitea treat the whole string as text, so label:bug there searches for the literal string. The result is a SearchPageResult, a PageResult plus incomplete, true when the platform admits the answer is partial.

Leave out state and the search covers open and closed items on every platform. Gitea on its own answers with open ones only, so forges asks it for all of them.

An empty query is a ForgesError with status 400 before any request goes out.

Search across repositories

Open bugs anywhere in an organization used to mean a loop. One call per repository, until somebody gives up. searchGlobal asks once.

const bugs = await forge.issues.searchGlobal("", {
  owner: "agntn",
  state: "open",
  labels: ["bug"],
});

Each hit is an Issue plus repository, so you know where to go next. Pull requests never show up, not even on GitHub, where they share the search route.

The options come from pull request search: author, owner, repo, sort, order, cursor and perPage. Issues add two. state is open, closed or all, and leaving it out means all. labels is a list, and an issue has to carry every label on it. Still need a query? Not with an owner, an author or a label. Any one of them is enough. "Every open issue in this org" is a fine question all by itself.

GitHub and GitLab match every label natively. Gitea is the odd one. Its search route takes two labels as either one, so forges drops the rows missing a label and sets incomplete. totalCount goes missing there too, because Gitea counted the wrong thing. Worse, Gitea forgets a label name it doesn't know and returns everything, so a typo looked like a perfect match. Not anymore. When the rows prove the filter was dropped, you get an empty page. Forgejo does exactly the same, and gets the same treatment.

A label with a comma or a double quote is a 400 before anything goes out. Gitea and GitLab split the list on commas.

forges_issues_search_global puts the same call in MCP, Pi and OMP, without the bodies.

Comments

listComments reads the discussion oldest first. On GitHub and Gitea issues and pull requests share the endpoint, both index pull requests as issues. On GitLab the notes are asked for with an explicit ascending sort, and two kinds are dropped: system notes about label and state churn, and inline diff notes, which belong to review threads. So a short GitLab page that still carries nextCursor is normal, keep paging. Gitea sends the whole discussion at once and the page you asked for is cut locally.

createComment adds one to the end of that discussion and returns it as the platform stored it. A blank body is a ForgesError with status 400 before anything goes out. Calling it twice posts two comments, there is nothing to deduplicate on.

interface Comment {
  id: string;
  body: string;
  author: { login: string };
  url: string;
  createdAt: string;
  updatedAt: string;
}

Reactions

Sometimes the whole reply is a thumbs up. listReactions reads those too, oldest first.

const onIssue = await forge.issues.listReactions("owner", "repo", 42);
const onComment = await forge.issues.listReactions("owner", "repo", 42, { commentId: "3001" });

interface Reaction {
  content: string; // "+1", "-1", "laugh", "confused", "heart", "hooray", "rocket" or "eyes"
  user: { login: string };
  createdAt: string;
}

Names follow GitHub everywhere. Where did the thumbs up go on GitLab? It's thumbsup there, and smile is GitHub's laugh. forges translates the four that differ. An emoji GitHub can't react with keeps its own name, so GitLab's fire stays fire. No guessing.

Give it a pull request number and you get a NotFoundError. GitLab says the same, and so do GitHub and Gitea, because forges reads the issue next to its reactions.

commentId takes an id from listComments. GitHub and Gitea find a comment by id alone, ignoring the issue. So forges reads the comment too. A comment from another issue is a NotFoundError, same as getComment. GitLab puts the issue in the path anyway.

Changing one after it's filed

update works like the pull request one. It takes only what changes: title, body, state ("closed" closes, "open" reopens), and addAssignees, removeAssignees, addLabels, removeLabels. What you leave out stays, so fixing one number in the body keeps the labels and assignees where they were. The result is the issue after the write.

An update that changes nothing, a blank title, or the same login or label in both an add and a remove list is a ForgesError with status 400 before anything goes out.

GitHub and Gitea serve pull requests on the issue route too, so both read the number first and answer NotFoundError when it's a pull request, before anything is written. After that GitHub patches title, body and state, then adds and removes assignees and labels one route at a time. GitLab sends one PUT and reads the issue first only for an assignee change, because assignees go out as the whole list. Gitea also sends assignees as the whole list, and changes labels by id. Several requests are not one transaction, so read the issue again before you retry a failed one.

GitHub's state_reason (completed, not_planned) is left out. GitLab and Gitea have nothing like it.

Assignees

assignees on create takes logins. GitLab Free accepts one. Pass two and you get a 400 before the request leaves, instead of a confusing answer from GitLab.