Add --related-to flags to gh issue create / gh issue edit for the "Relates to" relationship #14467

Describe the feature or problem you’d like to solve

As of v2.101.0, gh covers almost every relationship in the issue sidebar: --parent / --add-sub-issue / --remove-sub-issue for sub-issues, --blocked-by / --blocking and --add-blocked-by / --remove-blocked-by / --add-blocking / --remove-blocking for dependencies, plus parent, blockedBy, blocking in gh issue view --json. That came from #10298, #11757 and the design in #13120.

The one relationship left out is "Relates to" — the non-blocking link in the same Relationships panel. There is no flag on gh issue create or gh issue edit, and no field in gh issue view --json, so the only way to record it is to open the issue in a browser and click through the UI.

That is a real gap for scripted and agentic workflows (see #12522): a script can now open an issue and wire up every blocking dependency and every sub-issue in the same command, but if two issues are merely related — a decision issue and the issue that implements it, a bug and the follow-up that hardens it — it has to stop and ask a human to finish the job by hand. In practice the link often just gets written as a mention in the body instead, where it does not show up in the sidebar and is not filterable.

Proposed solution

Mirror the flags that already exist for dependencies:

• gh issue create --related-to <numbers or URLs>
• gh issue edit --add-related-to <numbers or URLs> and --remove-related-to <numbers or URLs>
• relatedTo as a gh issue view --json field, and the relationship shown in the TTY view next to blockedBy / blocking

Naming and cross-repo URL handling would follow whatever --blocked-by / --blocking already do, so there is nothing new to learn.

Additional context

This is very likely blocked on the API, and I'm filing it so it's tracked rather than because it can be picked up today. Probing the public API today (2026-09-17), "Relates to" looks UI-only:

• REST: the issue dependencies endpoints expose only blocked_by and blocking; GET /repos/{owner}/{repo}/issues/{n}/related and .../relationships both 404.
• GraphQL: the Issue type has blockedBy, blocking, parent, subIssues and subIssuesSummary, but no related-issues field; the only relationship mutations in the schema are addSubIssue, removeSubIssue and reprioritizeSubIssue.

So this probably has to wait for GitHub to expose the relationship — the feature has been in public preview since August 2026. If that's the case, this issue can serve as the place to track it so it isn't forgotten once the API lands, since the CLI side is already shaped by the work done for #11757.