Feature Request: Public API to Link a Pull Request to an Issue (Development Sidebar)

[Alex-ley-scrub]

Select Topic Area

Product Feedback

Body

Feature Request: Public API to Link a Pull Request to an Issue (Development Sidebar)

What's missing?

There is currently no public API (REST or GraphQL) to programmatically create the "Development" sidebar link between a pull request and an issue — the same link that can be created manually via the UI.

Why is this a problem?

The existing workarounds all break down in real-world workflows:

Workaround	Why it fails
Closing keywords (Fixes #123)	Only works when PR targets the default branch — ignored for develop, release/*, etc.
"Create branch from issue"	Must be done upfront, generates ugly long names, people forget, and you can't move an existing PR to that branch
Change PR head branch	Impossible — head branch is permanently fixed once the PR is opened
Multiple issues on one PR	No way to link several issues to one PR without keywords + default branch
Comments / #123 mentions	Not a real "Development" link — doesn't integrate with Projects, Insights, or automation
Manual UI linking	Works, but not automatable — useless for bots, Actions, or large teams

What's needed?

A public API that lets you directly link any PR to any issue, just like the UI does:

• Works regardless of target/base branch
• Can be done retroactively (after PR and branch already exist)
• Allows linking multiple issues ↔ multiple PRs
• Decouples linking from auto-closing semantics

Example GraphQL:

GraphQL

mutation {
  linkPullRequestToIssue(input: {
    pullRequestId: "PR_NODE_ID"
    issueId: "ISSUE_NODE_ID"
  }) {
    issue { id }
    pullRequest { id }
  }
}

Example REST:

Code

POST /repos/:owner/:repo/issues/:issue_number/linked_pull_requests
{ "pull_request_number": 456 }

Who needs this?

• Teams using any branching strategy beyond single-branch (GitFlow, release branches, environment branches)
• GitHub Actions / bots that want to maintain traceability
• Orgs with PRs that address multiple issues, or issues resolved across multiple PRs
• Anyone trying to keep Projects and issue history accurate

Prior discussions (fragmented)

This has been requested for years across many threads, but the pain is scattered:

• #148020 — Connect PRs to Issues (non-default branch)
• #112224 — Support closing issues by merging PRs to non-main branches
• #4194 — Link PRs to issues across repositories
• #23476 — Prevent issues from being closed by merging linked PRs
• #17308 — Same as above (duplicate)
• #66741 — Closing a PR should not close linked issues
• #184673 — [Feature Request] GraphQL API to retroactively link merged PRs to closed issues in Projects V2
• #155339 — GraphQL: Missing mutations for linking existing branch and pull request

They're all asking for the same thing: decouple the "Development" link from branch targeting and closing semantics, and expose it via API.

[github-actions[bot]]

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

• Your input will be carefully reviewed and cataloged by members of our product teams. 
  • Due to the high volume of submissions, we may not always be able to provide individual responses.
  • Rest assured, your feedback will help chart our course for product improvements.
• Other users may engage with your post, sharing their own perspectives or experiences. 
• GitHub staff may reach out for further clarification or insight. 
  • We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

• Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
• Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

• Upvote and comment on other user feedback Discussions that resonate with you.
• Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐

[xmo-odoo]

Manual UI linking Works, but not automatable — useless for bots, Actions, or large teams

This is only hinted at in a comment of #112224 but manual linking actually has the exact same issue as closing keywords, it only works if the PR targets a default branch, as you can see in this example:

• the repository has a default branch thisisatest
• the repository has the non-default branches branch2 and branch3
• the repository has an issue xmo-odoo/testrepo#4
• branch 3 was updated to change the content of the readme file
• from this Update README.md xmo-odoo/testrepo#5 was created targeting branch 2
• an issue xmo-odoo/testrepo#4 was linked onto Update README.md xmo-odoo/testrepo#5 via the UI
• Update README.md xmo-odoo/testrepo#5 was merged
• an issue xmo-odoo/testrepo#4 is still open

Even though xmo-odoo/testrepo#4 says that the PR will close it, and xmo-odoo/testrepo#5 says that it "may" close the issue.

[galamdring]

There are two separate issues here, and I think you addressed one of them, but not the other.

• Auto close only works when the target is the default branch - Maybe this should be configurable, or the branches that should be considered for closing the issue need to be added to the list of default branches

• Github Projects/Issues do not expose a way for a PR to be linked as the development for the issue, except in 2 cases

  • Manually attaching the PR via the UI
  • Targetting the default branch to trigger "closing" tag referencing

Without a way for the PR to be linked to the issue via an API endpoint, automation that targets github projects and uses PR stacking becomes minimally functional. Even when the automation adds a comment with the PRs that resolve the issue, navigation from Projects becomes multiple clicks, instead of one. When I move through my stack workflow, the descendant PRs will be shifted to target main, but that requires that I have fully resolved all issues in the previous one enough that it can be merged, which really defeats the entire purpose of stacked PRs.

Using Jira and other boards, a reference to an issue is a reference to an issue, it doesn't matter what branch it targets. This is the expected behavior for this type of product.

Workflow: use gh to make graphql api call to mutate the Linked Pull Request field

gh api graphql -f query='
mutation {
  updateProjectV2ItemFieldValue(input: {
    projectId: "PVT_kwHOACDmtc4BSN-c"
    itemId: "PVTI_lAHOACDmtc4BSN-czgn2Spo"
    fieldId: "PVTF_lAHOACDmtc4BSN-czg_0UHc"
    value: { number: 22 }
  }) {
    projectV2Item { id }
  }
}'

Expected Response:

{
  "data": {
    "updateProjectV2ItemFieldValue": {
      "projectV2Item": {
        "id": "PVTI_lAHOACDmtc4BSN-czgn2Spo"
      }
    }
  }
}

Expected Outcome:
PR now shows as linked in the project iteration board ui

Actual Response:

{
  "data": {
    "updateProjectV2ItemFieldValue": null
  },
  "errors": [
    {
      "type": "VALIDATION",
      "path": [
        "updateProjectV2ItemFieldValue"
      ],
      "locations": [
        {
          "line": 3,
          "column": 3
        }
      ],
      "message": "The field of type linked_pull_requests is currently not supported."
    }
  ]
}

Actual Outcome:
PR is not linked in UI of project iteration board.

[ElijahLynn]

Thank you for posting this, I really want this functionality in gh too. I link issues and PRs to each other in the development section all the time. And I would much rather have gh do it than have to do it in the UI.

[thomaswitt]

+1 for this. We also automatize an agent which automatically works on issues and opens pull requests - and we want to be able to link PRs and branches to it after the issue has been created. It works in the UI, so it also should work in the API.

[JM-DL]

+1 Please

[EdwardO90]

What he said

[aayadiCelonis]

+1

[essamm10]

+1

[EdwardO90]

+2

[EdwardO90]

+1 to the gods

[jay1466]

I support this request. The missing API becomes a real limitation once you start automating development workflows.

For teams using GitHub Actions or custom tooling, the "Development" relationship should be metadata that can be managed independently of branch strategy or issue-closing behavior. Today, we can automate labels, assignees, projects, milestones, and comments—but not one of the most useful relationships between an issue and its implementation.

An API like this would enable:

• Automation that links PRs created by bots or internal tools.
• Support for GitFlow, release branches, and stacked PR workflows without relying on closing keywords.
• Multiple PRs linked to a single issue (or vice versa) while preserving traceability.
• Consistent navigation from Issues and Projects regardless of the repository's branching model.

Keeping "linking" separate from "closing" would make the feature much more flexible and align it with how many engineering teams actually work.

[aangsync]

+1