Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions kits/registry.json
Original file line number Diff line number Diff line change
Expand Up @@ -251,6 +251,12 @@
"description": "Typed Git operations for Beddel workflows",
"category": "tools"
},
{
"name": "tools-github-kit",
"version": "0.1.0",
"description": "Typed GitHub pull request operations through the gh CLI",
"category": "tools"
},
{
"name": "tools-http-kit",
"version": "0.1.0",
Expand Down
58 changes: 58 additions & 0 deletions kits/tools-github-kit/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# tools-github-kit

Typed async GitHub pull request operations through the machine's existing `gh`
login. The kit runs explicit `gh` argv in the supplied repository and never
stores or receives credentials.

## Tools

| Tool | Purpose |
|------|---------|
| `github_pr_create_or_reuse` | Create one open pull request or reuse the sole matching request |
| `github_pr_checks_wait` | Poll the pull request check rollup until it passes, fails, or times out |
| `github_pr_merge` | Merge one open, checked pull request with a pinned head SHA |

`github_pr_create_or_reuse` accepts a branch, base branch, story key, spec
path, Change id, and revision. It invokes `gh pr list` and, when needed,
`gh pr create --head ... --base ... --title ... --body ...`, then lists again.
The generated body contains only these references:

```text
Story: <story_key>
Spec: <spec_path>
Change: <change_id>
Revision: <revision>
```

`github_pr_checks_wait` invokes `gh pr view <number> --json
number,state,headRefOid,statusCheckRollup`. A configured check is every entry
in that rollup. Completed `SUCCESS`, `NEUTRAL`, and `SKIPPED` CheckRuns and
`SUCCESS` StatusContexts pass. Pending entries wait; all other conclusions or
states fail. An empty rollup passes only after `grace` seconds.

`github_pr_merge` first views the requested number, refuses failed or pending
checks, runs `gh pr merge <number> --<merge|squash|rebase> --match-head-commit
<head_sha>`, and verifies the resulting `MERGED` state. Results contain
structured number, URL/branch/base, check, or merge keys as appropriate.

## Errors

The kit raises `GitHubToolError`, with one of these codes:

`GITHUB_ARGUMENT_REFUSED`, `GITHUB_CLI_MISSING`, `GITHUB_CLI_FAILED`,
`GITHUB_CLI_TIMEOUT`, `GITHUB_OUTPUT_INVALID`, `GITHUB_PR_CONFLICT`,
`GITHUB_PR_AMBIGUOUS`, `GITHUB_CHECKS_PENDING`, `GITHUB_CHECKS_FAILED`,
`GITHUB_PR_NOT_OPEN`, `GITHUB_PR_MISMATCH`, and `GITHUB_MERGE_INCOMPLETE`.

## Prerequisites and testing

The machine must have `gh` installed and authenticated through its existing
`gh auth` configuration. Python 3.12+ and the Beddel SDK are required.

```bash
cd repo/kits/tools-github-kit
pytest -q
```

Tests place a fake `gh` first on `PATH`; they do not access a network or a real
repository host.
34 changes: 34 additions & 0 deletions kits/tools-github-kit/kit.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
name: tools-github-kit
version: 0.1.0
description: Typed GitHub pull request operations through the gh CLI
author: Beddel Team
tools:
- name: github_pr_create_or_reuse
target: beddel_tools_github.tools:github_pr_create_or_reuse
description: Create or reuse one open GitHub pull request
category: github
- name: github_pr_checks_wait
target: beddel_tools_github.tools:github_pr_checks_wait
description: Wait for configured GitHub pull request checks
category: github
- name: github_pr_merge
target: beddel_tools_github.tools:github_pr_merge
description: Merge one checked GitHub pull request
category: github
targets:
python:
status: implemented
module: beddel_tools_github
dependencies: []
tools:
- name: github_pr_create_or_reuse
target: beddel_tools_github.tools:github_pr_create_or_reuse
- name: github_pr_checks_wait
target: beddel_tools_github.tools:github_pr_checks_wait
- name: github_pr_merge
target: beddel_tools_github.tools:github_pr_merge
typescript:
status: unavailable
unavailable_reason: >
The tools drive the local gh executable with the machine's existing login
and have no TypeScript target.
2 changes: 2 additions & 0 deletions kits/tools-github-kit/pytest.ini
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
[pytest]
asyncio_mode = auto
17 changes: 17 additions & 0 deletions kits/tools-github-kit/python/beddel_tools_github/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
"""Typed async GitHub pull request operations."""

from beddel_tools_github.tools import (
GitHubCLI,
GitHubToolError,
github_pr_checks_wait,
github_pr_create_or_reuse,
github_pr_merge,
)

__all__ = [
"GitHubCLI",
"GitHubToolError",
"github_pr_checks_wait",
"github_pr_create_or_reuse",
"github_pr_merge",
]
Empty file.
Loading
Loading