Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
GitHub (githubAction)
| Field | Value |
|---|---|
| Category | vcs (palette group vcs; class group = ("vcs", "tool")) |
| Backend handler | server/nodes/github/github_action.py (GitHubActionNode, on ActionNode); env + cwd helpers in _service.py; installer _install.py; login WS handlers _handlers.py |
| Tests | server/tests/test_github_plugin.py |
| Skill (if any) | server/skills/github/github-skill/SKILL.md (allowed-tools: "github") |
| Dual-purpose tool | yes - tool name github |
Purpose
Clone repositories, open / list / merge pull requests, create / list issues,
and run any other gh command, through a project-local pinned GitHub CLI.
List operations request --json so results land as parsed data; gh
authenticates from its own credential store (populated by gh auth login,
from the modal or a terminal) - the node performs no pre-flight and injects
no token.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Declared, but hideInputHandle is auto-set (usable_as_tool = True, class does not declare hide_input_handle) |
Parameters
extra="ignore" on the model.
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
operation |
repo_clone | pr_create | pr_list | pr_merge | issue_create | issue_list | custom |
pr_list |
no | - | Operation dispatch key |
repo |
string | "" |
no | pr_create, pr_list, pr_merge, issue_create, issue_list |
--repo OWNER/REPO when non-blank; otherwise gh infers from the cwd's git remote |
path |
string | "" |
no | repo_clone, pr_create, pr_merge, custom |
Working directory: absolute or relative to the workflow workspace |
clone_repo |
string | "" |
yes* | operation=repo_clone |
OWNER/REPO or full URL |
clone_dir |
string | "" |
no | operation=repo_clone |
Optional target directory positional |
title |
string | "" |
yes* (unless fill) |
pr_create, issue_create |
--title |
body |
string | "" |
no | pr_create, issue_create |
--body; passed even when empty |
base |
string | "" |
no | operation=pr_create |
--base |
head |
string | "" |
no | operation=pr_create |
--head |
draft |
bool | false |
no | operation=pr_create |
--draft |
fill |
bool | false |
no | operation=pr_create |
--fill instead of --title / --body |
state |
open | closed | merged | all |
open |
no | pr_list, issue_list |
--state; merged is coerced to all for issues |
limit |
int (1..100) | 30 |
no | pr_list, issue_list |
--limit |
pr |
string | "" |
yes* | operation=pr_merge |
PR number, URL or branch positional |
merge_method |
squash | merge | rebase |
squash |
no | operation=pr_merge |
Emitted as --squash / --merge / --rebase |
delete_branch |
bool | false |
no | operation=pr_merge |
--delete-branch |
labels |
string | "" |
no | operation=issue_create |
Comma-separated; each becomes a --label |
command |
string | "" |
yes* | operation=custom |
Everything after gh , shlex.split |
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | GitHubActionOutput; hideOutputHandle auto-set |
output-tool |
- | Auto-appended for usable_as_tool |
Output payload (TypeScript shape)
Keys omitted when empty; extra="allow".
{
operation: string;
success: true;
url?: string; // pr_create / issue_create: stdout starting with "http"; custom: single-line stdout starting with "http"
result?: unknown; // parsed JSON stdout (pr_list / issue_list --json, gh api via custom)
stdout?: string; // text stdout when nothing parsed
stderr_tail?: string; // last 2000 chars of stderr
}
pr_list JSON fields: number,title,state,url,author,headRefName,baseRefName,createdAt.
issue_list JSON fields: number,title,state,url,author,labels,createdAt.
Logic Flow
flowchart TD
A[Validate params] --> B{operation}
B -- repo_clone --> RC[require clone_repo; cwd REQUIRED path or workspace; repo clone repo dir?] --> R600[_run timeout 600s]
B -- pr_create --> PC{fill}
PC -- yes --> PF[pr create --repo? --fill]
PC -- no --> PT[require title; --title T --body B]
PF --> PO[--base? --head? --draft?; cwd path or workspace] --> R
PT --> PO
B -- pr_list --> PL[pr list --repo? --state S --limit N --json fields; cwd workspace if any] --> R
B -- pr_merge --> PM[require pr; pr merge pr --repo? --method --delete-branch?; cwd] --> R
B -- issue_create --> IC[require title; issue create --repo? --title --body --label...; cwd workspace if any] --> R
B -- issue_list --> IL[issue list --state S or all --limit N --json fields] --> R
B -- custom --> CU[require command; shlex.split; cwd path or workspace] --> R600
R --> X
R600 --> X
X{ensure_gh_cli -> run_cli_command env=gh_env}
X -- install raised --> RT[RuntimeError gh CLI install failed]
X -- exit != 0 or timeout --> ERR[NodeUserError gh argv0 failed: stderr tail]
X -- ok --> S[_shape: url? result or stdout, stderr_tail] --> OUT[Return envelope]
Decision Logic
- Validation (
NodeUserError): blankclone_repo; blanktitlewhenfillis false (pr_create) or always (issue_create); blankpr; blankcommand. - Working directory (
_cwd->resolve_repo_path):repo_clonepassesrequired=True, so without apathand without a workspace it raisesNodeUserError.pr_create,pr_merge,customusepathor the workspace (orNonewhen neither exists).pr_list,issue_create,issue_listalways call_cwd(ctx, ""): the workspace when present, elseNone. A relativepathwithout a workspace, or a non-directory, raisesNodeUserError. --repois appended only whenrepois non-blank.--bodyis always passed on the non-fillpr_createpath and onissue_create, even whenbodyis empty.- No auth pre-flight: gh's own "To get started with GitHub CLI, please run: gh auth login" surfaces via the failure wrap.
- Timeouts: 120 s default; 600 s for
repo_cloneandcustom. - Error paths: install failure ->
RuntimeError(generic branch, traceback); non-zero exit / timeout ->NodeUserErrorwith the last 2000 chars of stderr. urlextraction:pr_create/issue_createaccept multi-line stdout as long as it starts withhttp;customrequires a single line.
Side Effects
- Subprocess: one
ghprocess per op from<DATA_DIR>/packages/gh/<asset>.unzip|.untar/gh_<V>_<os>_<arch>/bin/gh(gh.exeon Windows). Env = server env plusGH_PROMPT_DISABLED=1,NO_COLOR=1,GH_NO_UPDATE_NOTIFIER=1,GH_PAGER=cat. AmbientGH_TOKEN/GITHUB_TOKENare honoured for ops (gh's own precedence) and stripped only bylogin_envin the WS handlers. - Install: first use downloads the pinned
gh2.96.0release archive from GitHub releases viapooch.retrieve(no hash) in a worker thread under a lock andchmod +xes the binary on POSIX. The systemghis never consulted; gh's config / credential store is user-level, so a terminal login is visible to the pinned binary. - File I/O:
repo_clonewrites a checkout into the cwd;custommay write depending on the command. - Cost metadata: every op declares
cost={"service": "github", "action": "<operation>", "count": 1}. - Broadcasts / DB writes: none beyond the standard node status.
External Dependencies
- Credentials:
GitHubCredential(id = "github",auth = "custom",resolve()returns{}) - a marker only. The session is gh's own credential store; the modal badge is the syntheticcli-managedmarker OAuth row written bygithub_loginaftergh auth statussucceeds, which also runsgh auth setup-gitbest-effort. - Services: GitHub API via gh; GitHub releases for the install.
- Python packages:
pooch,pydantic;services.events.run_cli_command. - Environment variables:
GH_TOKEN,GITHUB_TOKEN(ambient, honoured for ops), the four automation vars above.
Edge cases & known limits
annotations = {"destructive": False, ...}althoughpr_mergeandcustomcan mutate repositories.issue_listsilently mapsstate=mergedtoall(gh rejectsmergedfor issues).ui_hints = {"outputMode": "terminal"}.customruns any gh subcommand includingauth logout; it usesgh_env, so ambient tokens remain in place.repo_cloneinto a workspace that already holds the directory fails with gh's own error, surfaced asNodeUserError.
Related
- Skills using this as a tool: github-skill
- Siblings:
cloudflareAction,gcloudAction,vercelAction - Architecture docs: GitHub Service