Gluecron

Grab an exclusive lease on a PR, issue, branch or file path in a repository you can write, for one of your agent sessions. Pass owner+repo with a bare key (PR/issue number, branch name, path), or target_id '<repository id>:<key>'. Returns lease null when another agent holds an active lease.

Return AI spend rollups. Scope by one of: user_id (self), repo {owner,repo}, or agent_session_id. Defaults to caller's user spend.

Commit a patch to a branch without sending whole files — the way to change a few lines of a large file. `patch` is a unified diff as `git diff` prints it (one commit, `message` required) OR `git format-patch` mbox output (each patch becomes its own commit with the patch's own message and author, like `git am`; `message` is ignored). Applied server-side with `git apply --cached` against the branch head (created from `base_branch` if missing); blank context lines a transport stripped to empty lines, or trimmed off the end of the patch, are restored first (git still checks them against the file). `expected_head_sha` makes it compare-and-swap (all zeros = branch must not exist yet). Meets the same branch protection, rulesets and secret scan as a git push, and fires CI/webhooks like one. Patch limit 2 MiB. Requires 'repo' scope. Returns {branch, commit_sha, parent_sha, files_changed, files, commits, created} (+ blank_context_lines_restored / trimmed_blank_context_lines_restored when a repair was needed).

Approve a pull request: records an 'approved' review by the caller — the same review the web form and POST /api/v2/repos/:owner/:repo/pulls/:number/reviews write, so it counts toward branch protection's required approvals and clears the caller's own earlier request for changes. The PR must be open; its author cannot approve it. Requires write access and 'repo' scope. To request changes use gluecron_request_changes. Returns {reviewId, number, state, url}.

Assign (or, with remove: true, unassign) users on an issue or pull request. Real assignees since 2026-10-12 — up to 10 per thread, only users who can read the repository; the old `assignee:<username>` labels were migrated. Pass `assignee` (one username) or `assignees` (array). `type` is 'issue' (default) or 'pull_request'. Requires 'repo' scope and write access. Returns {assigned, skipped:[{username, reason}], removed, assignees}.

Apply a set of file writes + deletes as a single atomic commit on a branch (creates the branch if it doesn't exist). The killer agent tool: blob/tree/commit/ref-update sequence. Each change is `{path, content?, content_base64?, deleted?}`. Meets the same branch protection, rulesets and secret scan as a git push, and fires CI/webhooks like one. Requires 'repo' scope.

Site admins only (needs an 'admin'-scoped token). Backup and restore-drill health: whether the newest backup set is verified on an offsite target and how old it is, whether offsite copies are immutable (Object Lock), when a restore drill last passed, whether the backup worker is running, plus targets (host/bucket, never keys), schedule and recent runs. A stale, failed, local-only or never-drilled backup reads RED. Pass start: 'backup' or 'drill' to queue one for the worker (picked up within 15 minutes; audit-logged). Returns {health, reasons, targets, problems, schedule, runs, started?}.

Cancel a queued/running workflow run. Requires 'repo' scope.

Send another message to an existing repo chat. Returns the assistant's reply. If the AI service does not answer this fails with a JSON-RPC error carrying {chat_id, ai_error} rather than returning apology copy as a reply.

Start a new chat with a repo: creates a chat row, sends the first user message, streams + persists the assistant reply. Returns {chat_id, reply}. If the AI service does not answer this fails with a JSON-RPC error carrying {chat_id, ai_error} — it never returns apology copy as a reply. Requires authentication.

Where CI runs and why: mode (external | in-process), declaration (external | in-process | auto) and its source (CI_EXECUTOR on the box, the estate-wide setting, or auto), runners configured / reachable / busy / slots, lastSeenAt, state (ok | degraded | unconfigured | in-process) and holdReason — the sentence every queued run shows when no runner can take it. In-process never runs while external runners are configured. Site admins (admin scope) also get per-runner rows and may pass `declare` (external | in-process | auto) to set the estate-wide setting, audited (the answer then carries `saved`). Same as GET/PUT /api/v2/ci/executor and /admin/runners.

CI health, the same as GET /api/v2/ci/health and /admin/ci: status, the paging rules (queue p95, runner silent, timeout rate, heavy on the app box, runner_slow: a runner over 2x slower than its pool's fastest on the same heavy jobs), queue wait p50/p95 by work class, outcome rates, capacity, runnerSpeed24h (each runner's slowdown against its pool), and `measures`: capacity:compute_trigger (Tallrig ESTATE_PLAN §5's compute row: p95 push-to-start over 5 min for 7 days, or busy slots over 70% for 7 days) with firing, value, window, source and each day. Site admins (admin scope) also get `dashboard` (CAP-0.4) for 24 h and 7 d: startTimes (queue → start p50/p95 by class and pool), duplicateMinutes (lease time on a tree, workflow and job that already had a green job), poolCost (minutes per pool; a cost only where CI_POOL_COST_PER_MINUTE sets one, else 'cost not configured'), notMerged (merge-train dequeue and auto-merge reasons, counted), nonBillable (platform repositories on our machines vs customers'), testSelection (CAP-1.4: minutes saved by test selection and reuse, against full-run medians). Every number carries `source`: the table or setting it was read from. Read-only.

How full the shared CI queue is, and what to do about it: level (ok / busy / saturated), runs queued and running, runner slots, estimated minutes before a new run starts, and — with owner+repo — that repository's queued/running runs, its share of CI work, the slots it may hold while others wait (per work class, and across classes), a recommendation (e.g. batch changes into fewer pushes), and `explanation`: each work class's queued/running runs (interactive, review, push, schedule) and, for each of the repository's queued runs, its class and why it waits (code + sentence, from the claim plan itself). The same `ciQueue` block the write tools return. Ask before a burst of pushes. Also `executor`: where CI runs (external runners or in-process), runners configured / reachable / busy, and `holdReason` when no runner can take a run. Read-only.

Return the authenticated HTTPS clone URL for a repo + a credential-helper hint. Use this instead of embedding tokens in URLs. Returns {url, owner, repo, defaultBranch, hint} using the repo's stored casing.

Close an open issue. Requires authenticated caller with write access. Idempotent — closing an already-closed issue is a no-op. Returns {state}.

Close an open pull request without merging. Requires authenticated caller with write access. Idempotent. Returns {state}.

Add a comment to an existing issue. Requires authenticated caller with write access. Returns {commentId}.

Add a comment to a pull request. Requires authenticated caller with write access. Returns {commentId}.

Commit the saved resolutions for a PR's conflicts ON THE PR HEAD as a two-parent merge commit (old head, base tip) — never on the base branch — moved through the push gates so CI runs on it before anything merges. Every unresolved file needs a draft (gluecron_resolve_pr_conflict) or an entry in `resolutions`; files the merge rules settle are settled automatically. Both shas are compare-and-swapped: a branch that moved since is refused with nothing changed. The commit carries `Conflict-Resolution:` trailers; a gluecron[bot] comment records it. Requires write access and 'repo' scope.

Mint a new agent-multiplayer session. Returns the plaintext `token` exactly once (store it). Requires 'admin' scope.

Create a new branch ref pointing at an existing sha. Mirrors POST /api/v2/repos/.../git/refs. Gated like a push of the new branch (rulesets, secret scan of commits no other ref reaches) and fires CI/webhooks. Requires 'repo' scope. Returns {ref, sha}.

Mint a short-lived, repository-scoped HTTPS clone credential (a deploy token) for a sandbox or CI box that has no PAT. By default it returns NO token: {id, exchangeUrl, exchangeExpiresAt, gitConfig, url}. Run the gitConfig lines right before the first clone/fetch (the URL is single-use and dies in 60 s) and git fetches the token itself, so it never enters your transcript. Read-only by default; `read_only: false` asks for push access and is granted only if you have write access. Expires in 2 h by default (`expires_in_hours`, max 24). Needs owner / collaborator / team / org access to the repo (public read is not enough) and 'repo' scope. Audit-logged. Pass `token_id` (an id this tool returned) for a fresh exchange URL for the same grant; each exchange rotates the secret. `deliver: "token"` returns a read-only secret in the result instead (refused for push access: a push-capable secret in an agent's transcript outlives the run). Revoke the grant with gluecron_revoke_token {type: "deploy", id}.

Create a new issue on a Gluecron repository. Requires authenticated caller with write access on the target repo. Returns {number, url}.

Open a new pull request. `head_branch` is required; `base_branch` defaults to the repo default branch. Requires authenticated caller with write access. Returns {number, url}.

Mint a fine-grained repository token (`gcft_…`) for ONE repository and return it once. It authenticates the REST API (/api/v2 and the GitHub-compatible /api/v3), git over HTTPS and the container registry (images under owner/repo, by contents) for that repository only. `permissions` sets none/read/write for contents, issues, pull_requests, statuses and actions, and none/read for runners (admin and settings are never grantable); `expires_in` is optional: omit it (or "never") for no expiration, or give seconds or "30m", "12h", "7d", "1y" (min 5 minutes, max 1 year). Effective access is always held to YOUR current access to the repo, re-checked on every use, and branch protection applies as it does to you. Needs 'repo' scope. Audit-logged. Returns {id, name, repository, permissions, expiresAt, tokenPrefix, token}.

Create a one-time CI runner registration token for an owner (your username, an org you own or admin, or 'platform' as a site admin). A runner started with RUNNER_REGISTRATION_TOKEN=<token> registers once and gets its own long-lived credential; that owner's CI then runs on it. Expires in an hour. Pass exclusive: true for a label-only runner (a Mac for Xcode, a GPU box): it takes only jobs whose runs-on names its labels (e.g. [self-hosted, macos, xcode]), never runs-on: self / ubuntu-*, and the account keeps its shared lane; repositories narrows it to some of the owner's repositories. Both are fixed for the runner's life. Returns {owner, token, expiresAt, exclusive, repositoryIds, gluecronUrl}.

Delete a branch the way `git push --delete` would: write access, then branch protection (allow_deletion), rulesets and the push inspection apply; webhooks and CI fire. The default branch is never deleted. Pass expected_sha to delete only if the branch still points there. A missing branch is a not-found error. Mirrors DELETE /api/v3/repos/:o/:r/git/refs/heads/:branch. Audit-logged. Returns {branch, sha, deleted: true}.

Delete a comment on an issue or pull request (by comment id), with its edit history. Its author or a repository writer only. A missing comment is a not-found error, never reported as deleted. Mirrors DELETE /api/v3/repos/:o/:r/issues/comments/:id. Audit-logged (who wrote it, never what it said). Returns {id, kind, number, deleted: true}.

Delete a file from a branch via git plumbing. Requires the existing blob sha (optimistic concurrency) and 'repo' scope. Meets the same branch protection, rulesets and secret scan as a git push, and fires CI/webhooks like one. Mirrors DELETE /api/v2/contents.

Delete a repository — a SOFT delete (2026-10-19): it disappears at once from git, web, REST, MCP, CI, webhooks, search and pages, its name stays reserved, and it can be restored with gluecron_restore_repo until restorable_until (90 days by default). Queued/running CI is cancelled and pending webhook deliveries are stopped. Only the repository OWNER (the personal owner, or an org owner for an org repository) or a site admin may — admin collaborators and org admins are refused, as in the web UI. Requires 'admin' token scope. Audited as repo.delete; the owner is notified. To remove it for good before then, use gluecron_purge_repo. Returns {deleted: true, soft: true, id, restorable_until}.

Delete one workflow secret from a repository by name (cron_secret is read as CRON_SECRET). Idempotent: deleting a secret that is already gone succeeds with deleted:false, already_deleted:true, so a retry is safe. Workflows that reference it stop receiving it. Needs admin access to the repository and 'repo' scope. Audit-logged (name only). Returns {repository, name, deleted, already_deleted, at}.

Delete an Actions variable by name. Pass owner + repo for a repository variable, owner + repo + environment for an environment variable, or org for an organisation variable (organisation variables need an admin-scoped token). A variable that does not exist is a not-found error, never reported as deleted. Audit-logged. Returns {name, deleted: true}.

Dismiss the standing 'changes requested' reviews on a PR (all of them, or one reviewer's), so they no longer hold the merge. Requires 'repo' scope and write access; the reason is required and audited.

Replace the text of a comment on an issue or pull request (by comment id). Its author or a repository writer only; the previous text is kept in the edit history; the same text again is `unchanged`; a concurrent edit is a conflict, never overwritten. Mentions the edit adds are notified. Mirrors PATCH /api/v3/repos/:o/:r/issues/comments/:id. Returns {id, kind, number, effect}.

Explain a failed CI run: for each failed step, its class (compile / test / flaky / dependency / env / infra / lint / security / unknown) and the rule that chose it, the normalised error signature, failing tests, the files the commit touched, prior occurrences of the same failure (this repo, your other repos with the same owner or org, and platform-wide counts only) with the fix rate, and a suggested fix — the commit / PR that fixed it last time plus its diff limited to the relevant files, or the class's standard remedy. Infra and flaky failures never suggest a code change. `run_id` is the run's full id; with `owner` + `repo` an 8+ hex prefix also works.

Return the cached AI 'explain this codebase' Markdown for a repo. Pure read — never triggers a new generation (use the web UI for that).

Find definitions of a symbol by name within a repo. Wraps src/lib/symbols.findDefinitions.

Fork a repository to the authenticated caller's namespace. Mirrors POST /:owner/:repo/fork. Returns {owner, repo, url}. Requires 'repo' scope.

Generate a commit message for a diff. Same engine as gluecron_generate_pr_description but explicit for the commit-message use case.

Generate an AI commit-message-style description for a diff. Uses src/lib/ai-commit-message.ts under the hood; gracefully degrades to a heuristic when ANTHROPIC_API_KEY is missing. Returns {subject, body}.

Generate release notes between two tags. Wraps src/lib/ai-release-notes.generateReleaseNotes. Returns the rendered Markdown + section data.

Generate tests for a PR via Claude. Wraps src/lib/ai-test-generator.generateTestsForPr. Mode 'follow-up-pr' opens a new PR; 'append-commit' commits onto the head branch. Requires 'repo' scope.

Return spent / cap / remaining cents for an agent session.

Read the branch-protection rule that applies to a branch (exact name or the glob that covers it): required checks, require_pr_run, required approvals, AI / human review, green gates, force-push / deletion, auto-merge; plus `merge_train` {on, batch_max, effective_batch_max, host_ceiling} — whether the merge train runs for the repository and how many armed PRs it tests together. Read-only. Returns {protected: false, merge_train} when no rule applies, else {protected: true, pattern, matched_by, required_checks, …, merge_train}.

Fetch a single commit by SHA: metadata plus the list of files it changed (path, status, additions, deletions). Mirrors GET /api/v2/repos/.../commits/:sha. Patch bodies are NOT included — use gluecron_get_diff for those.

Read the actual changes in a commit or a branch range. Pass `sha` for one commit against its first parent, or `base`+`head` for everything head adds since the merge base (what a PR proposes). Returns {files:[{path, oldPath?, status, additions, deletions, binary, patch, patchTruncated}], stats, truncated}. Patch text is byte-capped; set include_patch=false for a files-changed summary only.

Fetch the full detail record of a pull request (title, body, state, branches, draft, author, timestamps), plus `mergeable` (true / false / null unknown) and `mergeState` from the same conflict probe the merge gate uses: status up-to-date | clean | conflicts | unknown, the unresolved files with their kinds, the files the merge rules settle, and conflictsUrl; and `conflictRisk` (early warning): level none | overlap | conflicts, the files the base changed since the PR branched that the PR changed too, and updateIsClean when updating now would merge cleanly. Authenticated callers only (the read tool surface still works anonymously).

List every check at a PR's current head — workflow runs, gates and commit statuses — with status, conclusion, whether branch protection requires it, and the run's log URL; plus each required check's state (passing / pending / failing / missing) and the merge gate's own CI verdict. A failed workflow run carries `failure`: the failed job and step, up to 8 file:line rows linked to the head sha, the tool's own guidance block ("What now?"), `budget` when a time budget rather than a test stopped the step (run conclusion `timed_out`: still blocks the merge), and the full step log URL — or `{withheld, required, hint}` when this credential may not read the run's logs (a private repository needs 'repo' scope). Read-only. Returns {head_sha, total_count, check_runs, required, ci}.

Return the branch-preview URL + status for a (repo, branch) pair. Wraps branch-previews.getPreviewForBranch. Returns {ok:false, reason:'not enabled on this host'} when the host has no PREVIEW_DOMAIN (no preview would ever resolve).

One of your tokens by type and id (from gluecron_list_tokens): everything list shows plus the audit trail (create, edits with a before/after diff, rotations, revocation). Never the secret. `type` is pat (personal access token, glc_), repo (repository token, gcft_) or deploy (deploy token, gcdt_). Same scopes as gluecron_list_tokens.