Skip to content

Operations

Jump to bottom
github-actions[bot] edited this page Aug 25, 2026 · 14 revisions

Operations

Every Pukbot mutation has a command and a typed JSON operation. Commands are convenient for interactive use. pukbot apply --input request.json --json is the canonical agent interface.

Common contracts

  • Repositories use owner/name.
  • Issue and pull request numbers start at 1.
  • Comment IDs are GitHub database IDs, not issue numbers.
  • --dry-run validates input and prints the final operation without dispatching.
  • --json emits one result object and suppresses workflow progress.
  • Destructive comment deletion and pull request merging require --yes.
  • Pull request merges always use squash.
  • Every JSON object rejects unknown fields.

Successful JSON output contains the operation name, workflow URL, and resource URL:

{
  "operation": "issue_create",
  "workflowUrl": "https://github.com/pulkitxm/pukbot/actions/runs/123",
  "resourceUrl": "https://github.com/owner/repository/issues/456"
}

Comments

pukbot comment create 123 --repo owner/repository --body "message"
pukbot comment edit 456 --repo owner/repository --body "updated"
pukbot comment delete 456 --repo owner/repository --yes
pukbot comment react 456 --repo owner/repository --reaction eyes

JSON operations are comment_create, comment_edit, comment_delete, and comment_react. Comment create and edit accept body plus an optional media array. Media names replace matching {NAME} placeholders inline.

{
  "operation": "comment_create",
  "repository": "owner/repository",
  "number": 123,
  "body": "{SCREENSHOT} result {DEMO}",
  "media": [
    {
      "name": "SCREENSHOT",
      "path": "/absolute/result.png",
      "alt": "result"
    },
    {
      "name": "DEMO",
      "url": "https://example.com/demo.mp4",
      "alt": "demo"
    }
  ]
}

Reactions are +1, -1, laugh, confused, heart, hooray, rocket, and eyes.

Issues

pukbot issue create \
  --repo owner/repository \
  --title "title" \
  --body "body" \
  --label bug \
  --assignee octocat

pukbot issue edit 123 --repo owner/repository --title "new title"
pukbot issue close 123 --repo owner/repository
pukbot issue reopen 123 --repo owner/repository
pukbot issue labels 123 --repo owner/repository --add urgent --remove stale
pukbot issue assignees 123 --repo owner/repository --add octocat
pukbot issue react 123 --repo owner/repository --reaction rocket

JSON operation names are:

  • issue_create
  • issue_edit
  • issue_close
  • issue_reopen
  • issue_labels
  • issue_assignees
  • issue_react

Create accepts title, optional body, and optional labels and assignees arrays. Edit accepts number and at least one of title or body. Label and assignee operations accept add and remove arrays.

Pull requests

pukbot pr create \
  --repo owner/repository \
  --title "title" \
  --body "one line" \
  --head feature \
  --base main \
  --draft

pukbot pr edit 123 --repo owner/repository --base develop
pukbot pr close 123 --repo owner/repository
pukbot pr reopen 123 --repo owner/repository
pukbot pr ready 123 --repo owner/repository
pukbot pr draft 123 --repo owner/repository
pukbot pr review 123 --repo owner/repository --event approve --body "looks good"
pukbot pr labels 123 --repo owner/repository --add ready --remove draft
pukbot pr assignees 123 --repo owner/repository --add octocat
pukbot pr react 123 --repo owner/repository --reaction heart
pukbot pr update-branch 123 --repo owner/repository
pukbot pr merge 123 --repo owner/repository --yes

JSON operation names are:

  • pull_request_create
  • pull_request_edit
  • pull_request_close
  • pull_request_reopen
  • pull_request_merge
  • pull_request_ready
  • pull_request_draft
  • pull_request_review
  • pull_request_labels
  • pull_request_assignees
  • pull_request_react
  • pull_request_update_branch

Create accepts title, optional body, head, base, and optional draft. Edit accepts number and at least one of title, body, or base. Review events are approve, request_changes, and comment. Requesting changes requires a body.

Commits

git add data/members.json
pukbot commit create --repo owner/repository --branch main --message "data: update roster"

pukbot commit create reads whatever is already staged in the local git index (git diff --cached) and commits exactly that content to the given branch of the target repository, atomically, through the GitHub Git Data API. Pass one or more pathspecs to restrict the commit to a subset of the staged changes:

pukbot commit create data/members.json --repo owner/repository --branch main --message "data: update roster"

The commit is created and verified as the Pukbot App's bot identity, never your local git author. The branch ref update is never forced: if the branch has moved since the commit was built, the operation fails instead of overwriting the newer history.

The JSON operation is commit_create and accepts branch, message, and a files array of {path, content, delete} objects. Set delete: true to remove a path, otherwise provide content as UTF-8 text. At most 50 files, 60,000 bytes per file, and 120,000 bytes combined.

Only text content is supported. Staged binary files (images, video, and other non-UTF-8 content) are rejected before any request is sent; commit those with local git for now.

Permissions

The protected operation workflow requests issue, pull request, and repository content write permissions from the Pukbot GitHub App. The App installation must include the target repository and grant those permissions. The CLI never receives the App private key or its short-lived installation token.

Clone this wiki locally