GitHub Issues¶

Use ubconnect github from-github to import issues from a GitHub repository into a Sphinx-Needs needs.json and ubconnect github validate-issue-refs to cross-check :issue: references on existing needs against the GitHub issue tracker.

Note

The github connector requires an active ubConnect license. See License configuration for activation instructions.

Authentication¶

The connector reads its personal access token from the GH_TOKEN environment variable, falling back to GITHUB_TOKEN. There is no TOML field for the token.

The token must be a GitHub Personal Access Token with the following scope:

repo — for private repositories.
public_repo — sufficient for public repositories only.

Fine-grained PATs work with the equivalent Issues: Read permission.

from-github¶

Imports issues into a Sphinx-Needs-compatible needs.json.

$ uv run ubconnect github from-github --config ubproject.toml

Configuration¶

[ubconnect.from_github_issues]
repo = "owner/name"
milestone = "1"
labels = ["enhancement"]
requirements_section_aliases = ["Acceptance Criteria"]
outdir = "_build"
id_prefix = "GH_"
timeout_seconds = 30

Configuration options:

Field	Type	Default	Description
`repo`	string	required	Repository in `owner/name` form.
`milestone`	string	`""`	Milestone filter. Accepts a milestone number, `*` (any), `none` (none), or a milestone title that is resolved to its number via `/repos/{repo}/milestones`.
`labels`	list[string]	`[]`	Issue labels to filter by (logical AND on the GitHub side).
`requirements_section_aliases`	list[string]	`["Acceptance Criteria"]`	Markdown headings (case-folded) that mark a section whose bullets become `comp_req` needs. When no matching heading exists in the issue body, the issue maps 1:1 to a single `feat` need.
`outdir`	path	directory of config file	Output directory for `needs.json`.
`id_prefix`	string	`"GH_"`	Prefix for emitted need ids (issue number is appended).
`timeout_seconds`	int	`30`	Per-request HTTP timeout for the GitHub API.

validate-issue-refs¶

Cross-checks :issue: extra fields on existing needs against the GitHub issue tracker. Reports issues that:

404 (do not exist or are inaccessible) as failures (exit code 1).
Are closed on GitHub while the referencing need is still open as warnings (exit code 0 by default; promoted to 1 with --strict).

$ uv run ubconnect github validate-issue-refs --config ubproject.toml
$ uv run ubconnect github validate-issue-refs --config ubproject.toml --strict

Configuration¶

[ubconnect.validate_github_issues]
repo = "owner/name"
needsjson_path = "_build/needs.json"
open_status_values = ["open", "in_progress"]
timeout_seconds = 30

Configuration options:

Field	Type	Default	Description
`repo`	string	required	Repository in `owner/name` form.
`needsjson_path`	path	required	Path to the `needs.json` file to validate.
`open_status_values`	list[string]	`["open", "in_progress"]`	Need `status` values considered “still open” when comparing against a closed GitHub issue.
`timeout_seconds`	int	`30`	Per-request HTTP timeout for the GitHub API.