GitHub: Create an issue

← Issues operations · Get started

Operation github.issues_create

Provider route: POST /repos/{owner}/{repo}/issues. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/github with npm, or alter-sdk-github with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { GitHubIntegration } from "@alter-ai/github";

async function execute(input: Parameters<GitHubIntegration["issues"]["issuesCreate"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new GitHubIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.issues.issuesCreate(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_github import GitHubIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = GitHubIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.issues.issues_create(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.owner	string	Required within parent
path.repo	string	Required within parent
body	object	Required within parent
body.assignees	array	Optional	Logins for Users to assign to this issue. NOTE: Only users with push access can set assignees for new issues. Assignees are silently dropped otherwise.
body.assignees[]	string	Each item
body.body	string	Optional	The contents of the issue.
body.issue_field_values	array	Optional	An array of issue field values to set on this issue. Each field value must include the field ID and the value to set. Issue fields are only available for organization-owned repositories with the feature enabled. Field values are silently dropped otherwise.
body.issue_field_values[]	object	Each item	Additional keys: not allowed
body.issue_field_values[].field_id	integer	Required within parent	The ID of the issue field to set
body.issue_field_values[].value	JSON	Required within parent	The value to set for the field. For multi-select fields, provide an array of option names.
body.issue_field_values[].value (oneOf 1)	string	Alternative
body.issue_field_values[].value (oneOf 2)	number	Alternative
body.issue_field_values[].value (oneOf 3)	array	Alternative
body.issue_field_values[].value (oneOf 3)[]	string	Each item
body.labels	array	Optional	Labels to associate with this issue. NOTE: Only users with push access can set labels for new issues. Labels are silently dropped otherwise.
body.labels[]	JSON	Each item
body.labels[] (oneOf 1)	string	Alternative
body.labels[] (oneOf 2)	object	Alternative
body.labels[] (oneOf 2).color	JSON	Optional
body.labels[] (oneOf 2).color (anyOf 1)	string	Alternative
body.labels[] (oneOf 2).color (anyOf 2)	null	Alternative
body.labels[] (oneOf 2).description	JSON	Optional
body.labels[] (oneOf 2).description (anyOf 1)	string	Alternative
body.labels[] (oneOf 2).description (anyOf 2)	null	Alternative
body.labels[] (oneOf 2).id	integer	Optional
body.labels[] (oneOf 2).name	string	Optional
body.milestone	JSON	Optional
body.milestone (anyOf 1)	JSON	Alternative
body.milestone (anyOf 1) (oneOf 1)	string	Alternative
body.milestone (anyOf 1) (oneOf 2)	integer	Alternative	The `number` of the milestone to associate this issue with. NOTE: Only users with push access can set the milestone for new issues. The milestone is silently dropped otherwise.
body.milestone (anyOf 2)	null	Alternative
body.parent_issue_id	integer	Optional	The id of the parent issue to add this issue to as a sub-issue. NOTE: Only users with triage access to both the parent issue’s repository and this repository can set the parent issue.
body.title	JSON	Required within parent	The title of the issue.
body.title (oneOf 1)	string	Alternative
body.title (oneOf 2)	integer	Alternative
body.type	JSON	Optional
body.type (anyOf 1)	string	Alternative	The name of the issue type to associate with this issue. NOTE: Only users with push access can set the type for new issues. The type is silently dropped otherwise.
body.type (anyOf 2)	null	Alternative

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Get an issue — response body

Referenced models: Get an issue — response body

Schemas

16 more schemas are linked from the tables above, on the schema pages.

Get an issue — response body

Field	Type	Presence	Description and constraints
$	object	Root	Issues are a great way to keep track of tasks, enhancements, and bugs for your projects.
active_lock_reason	JSON	Optional
active_lock_reason (anyOf 1)	string	Alternative
active_lock_reason (anyOf 2)	null	Alternative
assignees	array	Optional
assignees[]	Model	Each item	Expand List users — response body — item
author_association	string	Optional	How the author is associated with the repository. Known values: COLLABORATOR, CONTRIBUTOR, FIRST_TIMER, FIRST_TIME_CONTRIBUTOR, MANNEQUIN, MEMBER, NONE, OWNER
body	JSON	Optional
body (anyOf 1)	string	Alternative	Contents of the issue
body (anyOf 2)	null	Alternative
body_html	string	Optional
body_text	string	Optional
closed_at	JSON	Required within parent
closed_at (anyOf 1)	string	Alternative	Format: date-time
closed_at (anyOf 2)	null	Alternative
closed_by	Model	Optional	Expand Get an issue — response body — user
comments	JSON	Required within parent
comments (anyOf 1)	integer	Alternative
comments (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
comments_url	string	Required within parent	Format: uri
created_at	string	Required within parent	Format: date-time
draft	boolean	Optional
events_url	string	Required within parent	Format: uri
html_url	string	Required within parent	Format: uri
id	JSON	Required within parent
id (anyOf 1)	integer	Alternative	Format: int64
id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
issue_dependencies_summary	Model	Optional	Expand Get an issue — response body — issue dependencies summary
issue_field_values	array	Optional
issue_field_values[]	Model	Each item	Expand Add issue field values to an issue — response body — item
labels	array	Required within parent	Labels to associate with this issue; pass one or more label names to replace the set of labels on this issue; send an empty array to clear all labels from the issue; note that the labels are silently dropped for users without push access to the repository
labels[]	JSON	Each item
labels[] (anyOf 1)	string	Alternative
labels[] (anyOf 2)	Model	Alternative	Expand Get an issue — response body — labels item archived by, color, default, description, id, name, node id, url
labels_url	string	Required within parent
locked	boolean	Required within parent
milestone	Model	Required within parent	Expand Get an issue — response body — milestone
node_id	string	Required within parent
number	JSON	Required within parent
number (anyOf 1)	integer	Alternative	Number uniquely identifying the issue within its repository
number (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
parent_issue_url	JSON	Optional
parent_issue_url (anyOf 1)	string	Alternative	URL to get the parent issue of this issue, if it is a sub-issue Format: uri
parent_issue_url (anyOf 2)	null	Alternative
performed_via_github_app	Model	Optional	Expand Get an app — response body
pinned_comment	Model	Optional	Expand Get an issue — response body — pinned comment
pull_request	object	Optional
pull_request.diff_url	string	Required within parent	Format: uri
pull_request.html_url	string	Required within parent	Format: uri
pull_request.merged_at	string	Optional	Format: date-time
pull_request.patch_url	string	Required within parent	Format: uri
pull_request.url	string	Required within parent	Format: uri
reactions	Model	Optional	Expand Get an issue — response body — reactions
repository	Model	Optional	Expand List repositories for the authenticated user — response body — item
repository_url	string	Required within parent	Format: uri
state	string	Required within parent	State of the issue; either 'open' or 'closed'
state_reason	JSON	Optional
state_reason (anyOf 1)	string	Alternative	The reason for the current state Known values: completed, reopened, not_planned, duplicate
state_reason (anyOf 2)	null	Alternative
sub_issues_summary	Model	Optional	Expand Get an issue — response body — sub issues summary
timeline_url	string	Optional	Format: uri
title	string	Required within parent	Title of the issue
type	Model	Optional	Expand Create issue type for an organization — response body
updated_at	string	Required within parent	Format: date-time
url	string	Required within parent	URL for the issue Format: uri
user	Model	Required within parent	Expand Get an issue — response body — user

Referenced models: Get an app — response body, Get an issue — response body — issue dependencies summary, Add issue field values to an issue — response body — item, Create issue type for an organization — response body, Get an issue — response body — pinned comment, Get an issue — response body — milestone, Get an issue — response body — user, Get an issue — response body — reactions, List repositories for the authenticated user — response body — item, List users — response body — item, Get an issue — response body — sub issues summary, Get an issue — response body — labels item archived by, color, default, description, id, name, node id, url

Get an issue — response body — issue dependencies summary

Field	Type	Presence	Description and constraints
$	object	Root
blocked_by	JSON	Required within parent
blocked_by (anyOf 1)	integer	Alternative
blocked_by (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
blocking	JSON	Required within parent
blocking (anyOf 1)	integer	Alternative
blocking (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
total_blocked_by	JSON	Required within parent
total_blocked_by (anyOf 1)	integer	Alternative
total_blocked_by (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
total_blocking	JSON	Required within parent
total_blocking (anyOf 1)	integer	Alternative
total_blocking (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Get an issue — response body — pinned comment

Field	Type	Presence	Description and constraints
$	JSON	Root
$ (anyOf 1)	Model	Alternative	Expand Get an issue — response body — pinned comment author association, body, body html, body text, created at, html url, id, issue url, minimized, node id, performed via github app, pin, reactions, updated at, url, user
$ (anyOf 2)	null	Alternative

Referenced models: Get an issue — response body — pinned comment author association, body, body html, body text, created at, html url, id, issue url, minimized, node id, performed via github app, pin, reactions, updated at, url, user

Get an issue — response body — milestone

Field	Type	Presence	Description and constraints
$	JSON	Root
$ (anyOf 1)	Model	Alternative	Expand Get an issue — response body — milestone / state: open, closed
$ (anyOf 2)	null	Alternative

Referenced models: Get an issue — response body — milestone / state: open, closed

Policy, approvals and errors

SDK function policy ID: github.issues_create. Catalog operation: issues/create. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"X-GitHub-Api-Version": "2026-03-10", "User-Agent": "Alter", "Accept": "application/vnd.github+json"}

Official provider source