Github Step Reference

This page is generated from the public step inventory and shows the documented workflow contract for each public step.

Pull Requests

create_pr

Creates a GitHub pull request using data from the workflow context.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: create_pr

Used by built-in workflows: create-pr-ai

Available to later steps: pr_number, pr_url

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.
ctx.git	-	An initialized GitClient.

Inputs (from ctx.data)

Name	Type	Description
pr_title	str	The title of the pull request.
pr_body	str, optional	The body/description of the pull request.
pr_head_branch	str	The branch with the new changes.
pr_base_branch	str, optional	The branch to merge into. Defaults to the git plugin's configured main branch.
pr_is_draft	bool, optional	Whether to create the PR as a draft. Defaults to False.
pr_reviewers	list, optional	List of GitHub usernames or team slugs to request review from.
pr_excluded_reviewers	list, optional	List of GitHub usernames to exclude from team expansion.
pr_labels	list, optional	List of label names to add to the PR.
auto_assign_prs	bool	If True, automatically assigns the PR to the current GitHub user.

Outputs (saved to ctx.data)

Name	Type	Description
pr_number	int	The number of the created pull request.
pr_url	str	The URL of the created pull request.

Returns

Result	Saved for later steps	Description
Success	pr_number, pr_url	If the PR is created successfully.
Error	-	If any required context arguments are missing or if the API call fails.

get_pull_request

Fetch a pull request and store it in workflow context.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: get_pull_request

Available to later steps: pr_info

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
pr_number	int	Pull request number to fetch.

Outputs (saved to ctx.data)

Name	Type	Description
pr_info	-	The fetched pull request object.

Returns

Result	Saved for later steps	Description
Success	pr_info	If the pull request is fetched successfully.
Error	-	If required context is missing or the GitHub call fails.

check_merge_queue

Check whether the pull request's base branch requires a merge queue.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: check_merge_queue

Available to later steps: merge_queue_enabled, merge_queue_state

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
pr_number	int	Pull request number to inspect.

Outputs (saved to ctx.data)

Name	Type	Description
merge_queue_enabled	bool | None	Whether the base branch requires a merge queue, or None when the lookup failed.
merge_queue_state	-	The merge queue state object, when the lookup succeeded.

Returns

Result	Saved for later steps	Description
Success	merge_queue_enabled, merge_queue_state	When the PR number is available. A failed lookup is not fatal: it reports merge_queue_enabled=None, so the merge falls back to a direct merge and says the queue was never checked.
Error	-	If required context is missing.

merge_pull_request

Merge a pull request, or add it to the base branch's merge queue.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: merge_pull_request

Available to later steps: merge_result, merge_queued, expected_pr_state

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
pr_number	int	Pull request number to merge.
merge_method	str, optional	Merge strategy. Ignored with a merge queue.
commit_title	str, optional	Override commit title. Ignored with a merge queue.
commit_message	str, optional	Override commit message. Ignored with a merge queue.
merge_queue_enabled	bool, optional	Result of a previous check_merge_queue, reused to avoid looking the queue up twice. None means unknown, and the queue is looked up again here.

Outputs (saved to ctx.data)

Name	Type	Description
merge_result	-	The GitHub merge result object.
merge_queued	bool	True when the PR was added to the merge queue.
expected_pr_state	str	"MERGED" after a regular merge, "OPEN" once queued.

Returns

Result	Saved for later steps	Description
Success	merge_result, merge_queued, expected_pr_state	If the pull request is merged or added to the merge queue.
Error	-	If required context is missing or the GitHub call fails.

verify_pull_request_state

Verify a pull request is currently in the expected state.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: verify_pull_request_state

Available to later steps: verified_pr_info

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
pr_number	int	Pull request number to inspect.
expected_state	str	Expected pull request state.

Outputs (saved to ctx.data)

Name	Type	Description
verified_pr_info	-	The pull request object when verification succeeds.

Returns

Result	Saved for later steps	Description
Success	verified_pr_info	If the pull request is in the expected state.
Error	-	If required context is missing, verification fails, or the GitHub call fails.

verify_merge_outcome

Verify the outcome of a merge that may have gone through a merge queue.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: verify_merge_outcome

Available to later steps: verified_pr_info, merge_queue_state

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
pr_number	int	Pull request number to inspect.
merge_queued	bool	Set by merge_pull_request; True when the PR was added to the merge queue. Required - a missing value is treated as a workflow configuration error.

Outputs (saved to ctx.data)

Name	Type	Description
verified_pr_info	-	The pull request object; saved only on the regular merge path (merge_queued falsy).
merge_queue_state	-	The merge queue state; saved only on the queued merge path (merge_queued truthy).

Returns

Result	Saved for later steps	Description
Success	verified_pr_info, merge_queue_state	If the PR is merged, or still queued when it was enqueued. Exactly one output key is saved - verified_pr_info on the regular merge path, merge_queue_state on the queued merge path - never both.
Error	-	If required context is missing, the PR is in neither state, or the GitHub call fails.

ai_suggest_pr_description

Generate PR title and description using PRAgent.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: ai_suggest_pr_description

Used by built-in workflows: create-pr-ai

Available to later steps: pr_title, pr_body, pr_size, ai_generated

Requires

Name	Type	Description
ctx.ai_router	-	The AI execution façade (falls back to ctx.ai)
ctx.git	-	An initialized GitClient
ctx.github	-	An initialized GitHubClient

Inputs (from ctx.data)

Name	Type	Description
pr_head_branch	str	The head branch for the PR

Outputs (saved to ctx.data)

Name	Type	Description
pr_title	str	AI-generated PR title
pr_body	str	AI-generated PR description
pr_size	str	Size classification (small/medium/large/very large)
ai_generated	bool	True if AI generated the content

Returns

Result	Saved for later steps	Description
Success	pr_title, pr_body, pr_size, ai_generated	PR description generated
Skip	pr_title, pr_body, pr_size, ai_generated	AI not configured or user declined
Error	-	Failed to generate PR description

Prompt and Selection

prompt_for_pr_title

Interactively prompts the user for a Pull Request title.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: prompt_for_pr_title

Available to later steps: pr_title

Requires

Name	Type	Description
ctx.textual	-	Textual UI components.

Outputs (saved to ctx.data)

Name	Type	Description
pr_title	str	The title entered by the user.

Returns

Result	Saved for later steps	Description
Success	pr_title	If the title was captured successfully.
Error	-	If the user cancels or the title is empty.
Skip	pr_title	If pr_title already exists.

prompt_for_pr_body

Interactively prompts the user for a Pull Request body.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: prompt_for_pr_body

Available to later steps: pr_body

Requires

Name	Type	Description
ctx.textual	-	Textual UI components.

Outputs (saved to ctx.data)

Name	Type	Description
pr_body	str	The body/description entered by the user.

Returns

Result	Saved for later steps	Description
Success	pr_body	If the body was captured successfully.
Error	-	If the user cancels.
Skip	pr_body	If pr_body already exists.

prompt_for_pr_draft

Ask whether the pull request should be created as a draft.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: prompt_for_pr_draft

Used by built-in workflows: create-pr-ai

Available to later steps: pr_is_draft

Requires

Name	Type	Description
ctx.textual	-	Textual UI components.

Inputs (from ctx.data)

Name	Type	Description
draft	bool | None, optional	Draft mode from workflow params. Use True/False to skip the prompt, or None to ask interactively.

Outputs (saved to ctx.data)

Name	Type	Description
pr_is_draft	bool	Whether the PR should be created as a draft.

Returns

Result	Saved for later steps	Description
Success	pr_is_draft	If the draft preference was resolved successfully.
Error	-	If the user cancels or the prompt fails.

prompt_for_issue_body_step

Interactively prompts the user for a GitHub issue body.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: prompt_for_issue_body_step

Used by built-in workflows: create-issue-ai

Available to later steps: issue_body

Requires

Name	Type	Description
ctx.textual	-	Textual UI components.

Outputs (saved to ctx.data)

Name	Type	Description
issue_body	str	The body/description entered by the user.

Returns

Result	Saved for later steps	Description
Success	issue_body	If the body was captured successfully.
Error	-	If the user cancels.
Skip	issue_body	If issue_body already exists.

prompt_for_self_assign

Asks the user if they want to assign the issue to themselves.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: prompt_for_self_assign

Used by built-in workflows: create-issue-ai

Available to later steps: assignees

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Outputs (saved to ctx.data)

Name	Type	Description
assignees	list[str]	Updated assignees list when the user chooses self-assignment.

Returns

Result	Saved for later steps	Description
Success	assignees	If the assignment preference is captured successfully.
Error	-	If the GitHub client is unavailable or the prompt fails.

prompt_for_labels

Prompt the user to select repository labels and save them to context.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: prompt_for_labels

Used by built-in workflows: create-pr-ai

Available to later steps: <output_key>

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
output_key	str, optional	Context key where selected labels should be stored. Defaults to "labels".
prompt	str, optional	Prompt text shown to the user. Defaults to "Select labels:".
default_selected_key	str, optional	Context key used to preselect labels. Defaults to output_key.

Outputs (saved to ctx.data)

Name	Type	Description
<output_key>	list[str]	Labels selected by the user.

Returns

Result	Saved for later steps	Description
Success	<output_key>	If label selection completes successfully.
Skip	<output_key>	If the repository has no labels.
Error	-	If the GitHub client is unavailable or the prompt fails.

Issue Creation

ai_suggest_issue_title_and_body

Use AI to suggest a title and description for a GitHub issue.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: ai_suggest_issue_title_and_body

Used by built-in workflows: create-issue-ai

Available to later steps: issue_title, issue_body, issue_category, labels

Inputs (from ctx.data)

Name	Type	Description
issue_body	str	Raw issue request entered by the user.

Outputs (saved to ctx.data)

Name	Type	Description
issue_title	str	AI-generated or user-edited title.
issue_body	str	AI-generated or user-edited body.
issue_category	str	Detected issue category.
labels	list[str]	Suggested labels for the issue.

Returns

Result	Saved for later steps	Description
Success	issue_title, issue_body, issue_category, labels	If issue content is generated and accepted.
Skip	issue_title, issue_body, issue_category, labels	If AI is unavailable or the user rejects the generated issue.
Error	-	If required context is missing or generation fails.

preview_and_confirm_issue

Show a preview of the AI-generated issue and ask for confirmation.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: preview_and_confirm_issue

Inputs (from ctx.data)

Name	Type	Description
issue_title	str	Generated issue title.
issue_body	str	Generated issue body.

Returns

Result	Saved for later steps	Description
Success	-	If the user confirms the issue preview.
Error	-	If required context is missing, the user rejects, or the prompt is cancelled.

create_issue

Create a new GitHub issue.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: create_issue

Used by built-in workflows: create-issue-ai

Available to later steps: issue

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
issue_title	str	Issue title.
issue_body	str	Issue body.
assignees	list, optional	Usernames to assign.
labels	list, optional	Labels to apply.

Outputs (saved to ctx.data)

Name	Type	Description
issue	GitHubIssue	The created issue object.

Returns

Result	Saved for later steps	Description
Success	issue	If the issue is created successfully.
Error	-	If required context is missing or the GitHub call fails.

Pull Request Review

select_pr_for_review

Select a PR from the user's open PRs to review comments.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: select_pr_for_review

Used by built-in workflows: respond-pr-comments

Available to later steps: selected_pr_number, selected_pr_title

Outputs (saved to ctx.data)

Name	Type	Description
selected_pr_number	int	The selected PR number
selected_pr_title	str	The selected PR title

Returns

Result	Saved for later steps	Description
Success	selected_pr_number, selected_pr_title	PR selected successfully
Exit	-	No PRs available or user cancelled
Error	-	Failed to fetch PRs

fetch_pending_comments

Fetch unresolved review threads for the selected PR using GraphQL.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: fetch_pending_comments

Used by built-in workflows: respond-pr-comments

Available to later steps: review_threads

Outputs (saved to ctx.data)

Name	Type	Description
review_threads	List[UICommentThread]	Unresolved review threads

Returns

Result	Saved for later steps	Description
Success	review_threads	Threads fetched
Exit	-	No unresolved threads
Error	-	Failed to fetch threads

check_clean_state

Check that the working tree is clean before checking out the PR branch.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: check_clean_state

Used by built-in workflows: respond-pr-comments

Returns

Result	Saved for later steps	Description
Success	-	Working tree is clean
Exit	-	Uncommitted changes detected — user must stash manually
Error	-	Failed to check status

checkout_pr_branch

Save the current branch and checkout the PR branch.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: checkout_pr_branch

Used by built-in workflows: respond-pr-comments

Available to later steps: original_branch

Outputs (saved to ctx.data)

Name	Type	Description
original_branch	str	Branch to restore after review

Returns

Result	Saved for later steps	Description
Success	original_branch	PR branch checked out
Error	-	Failed to fetch or checkout

review_comments

Review all unresolved comment threads one by one and take action.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: review_comments

Used by built-in workflows: respond-pr-comments

Returns

Result	Saved for later steps	Description
Success	-	All threads processed
Error	-	Failed to process threads

push_commits

Push commits to PR branch.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: push_commits

Used by built-in workflows: respond-pr-comments

Available to later steps: push_successful

Outputs (saved to ctx.data)

Name	Type	Description
push_successful	bool	Whether push succeeded

Returns

Result	Saved for later steps	Description
Success	push_successful	Commits pushed
Skip	push_successful	No commits to push or user cancelled
Error	-	Failed to push

send_comment_replies

Send comment replies (both text responses and commit hashes).

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: send_comment_replies

Used by built-in workflows: respond-pr-comments

Returns

Result	Saved for later steps	Description
Success	-	Replies sent
Skip	-	No replies to send or user cancelled
Error	-	Failed to send replies

request_review

Re-request review from existing reviewers.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: request_review

Used by built-in workflows: respond-pr-comments

Returns

Result	Saved for later steps	Description
Success	-	Review re-requested
Skip	-	Push didn't succeed or user cancelled
Error	-	Failed to request review

checkout_original_branch

Restore the original branch after PR review.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: checkout_original_branch

Used by built-in workflows: respond-pr-comments

Returns

Result	Saved for later steps	Description
Success	-	Restored to original branch
Exit	-	No original branch saved or checkout failed

Code Review

select_pr_for_code_review

List all open PRs and ask user to select one.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: select_pr_for_code_review

Used by built-in workflows: review-pr, review-pr-thread-resolution

Available to later steps: review_pr_number, review_pr_title, review_pr_head, review_pr_base

Outputs (saved to ctx.data)

Name	Type	Description
review_pr_number	int	Selected PR number
review_pr_title	str	PR title
review_pr_head	str	Head branch
review_pr_base	str	Base branch

Returns

Result	Saved for later steps	Description
Success	review_pr_number, review_pr_title, review_pr_head, review_pr_base	A PR was selected.
Exit	-	No PRs, or the user cancelled.
Error	-	If listing PRs fails.

fetch_pr_review_bundle

Fetch all data needed for a full PR review cycle.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: fetch_pr_review_bundle

Used by built-in workflows: review-pr, review-pr-thread-resolution

Available to later steps: review_pr, review_diff, review_changed_files, review_changed_files_with_stats, review_commit_sha, review_threads, review_general_comments, pr_template

Inputs (from ctx.data)

Name	Type	Description
review_pr_number	int	PR number

Outputs (saved to ctx.data)

Name	Type	Description
review_pr	UIPullRequest	Pull request details
review_diff	str	Full unified diff
review_changed_files	List[str]	Changed file paths (may be subset for large PRs)
review_changed_files_with_stats	List[UIFileChange]	All files with add/del stats
review_commit_sha	str	Head commit SHA
review_threads	List[UICommentThread]	Inline review threads (unresolved)
review_general_comments	List[UICommentThread]	General PR-level comments
pr_template	str | None	PR template content if available

Returns

Result	Saved for later steps	Description
Success	review_pr, review_diff, review_changed_files, review_changed_files_with_stats, review_commit_sha, review_threads, review_general_comments, pr_template	The step completed.
Skip	review_pr, review_diff, review_changed_files, review_changed_files_with_stats, review_commit_sha, review_threads, review_general_comments, pr_template	Nothing to do (empty diff).
Error	-	The step failed.

build_change_manifest

Build a structured manifest of the PR changes (no AI involved).

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: build_change_manifest

Used by built-in workflows: review-pr

Available to later steps: change_manifest

Inputs (from ctx.data)

Name	Type	Description
review_pr	UIPullRequest	Pull request details
review_changed_files_with_stats	List[UIFileChange]	Files with add/del stats

Outputs (saved to ctx.data)

Name	Type	Description
change_manifest	ChangeManifest	Structured PR context

Returns

Result	Saved for later steps	Description
Success	change_manifest	The step completed.
Error	-	The step failed.

build_existing_comments_index

Build a compact index of existing PR comments for deduplication.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: build_existing_comments_index

Used by built-in workflows: review-pr

Available to later steps: existing_comments_index

Inputs (from ctx.data)

Name	Type	Description
review_threads	List[UICommentThread]	Inline review threads
review_general_comments	List[UICommentThread]	General PR-level comments

Outputs (saved to ctx.data)

Name	Type	Description
existing_comments_index	List[ExistingCommentIndexEntry]	-

Returns

Result	Saved for later steps	Description
Success	existing_comments_index	The step completed.

write_review_material

Put what the review would otherwise fetch into the PR worktree, as files.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: write_review_material

Used by built-in workflows: review-pr

Available to later steps: review_material

Inputs (from ctx.data)

Name	Type	Description
change_manifest	ChangeManifest	-
review_diff_manager	DiffContextManager	-
review_threads, review_general_comments	List[UICommentThread]	-
worktree_path	str	-

Outputs (saved to ctx.data)

Name	Type	Description
review_material	dict[str, bool]	each changed path -> whether it has a base version

Returns

Result	Saved for later steps	Description
Success	review_material	The step completed.
Error	-	The step failed.

ai_review_findings

Run the review session, and report its cost even if it is abandoned.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: ai_review_findings

Used by built-in workflows: review-pr

Available to later steps: raw_findings, ai_findings_failed

Inputs (from ctx.data)

Name	Type	Description
change_manifest	ChangeManifest	-
worktree_path	str	with the material write_review_material left in it

Outputs (saved to ctx.data)

Name	Type	Description
raw_findings	list	the session's findings, mapped onto Finding's fields
ai_findings_failed	bool	True when no review happened

Returns

Result	Saved for later steps	Description
Success	raw_findings, ai_findings_failed	With the raw findings, or with none when AI is off for the task.
Error	-	If the session could not run or produced nothing readable.

normalize_findings

Parse and validate raw AI output into Finding models.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: normalize_findings

Used by built-in workflows: review-pr

Available to later steps: normalized_findings

Inputs (from ctx.data)

Name	Type	Description
raw_findings	list | str	Raw AI output from ai_review_findings

Outputs (saved to ctx.data)

Name	Type	Description
normalized_findings	List[Finding]	Validated Finding objects

Returns

Result	Saved for later steps	Description
Success	normalized_findings	The step completed.
Error	-	The step failed.

dedupe_findings

Remove findings that duplicate existing PR comments.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: dedupe_findings

Used by built-in workflows: review-pr

Available to later steps: deduped_findings

Inputs (from ctx.data)

Name	Type	Description
normalized_findings	List[Finding]	-
existing_comments_index	List[ExistingCommentIndexEntry]	-

Outputs (saved to ctx.data)

Name	Type	Description
deduped_findings	List[Finding]	Findings after duplicate removal

Returns

Result	Saved for later steps	Description
Success	deduped_findings	The step completed.
Error	-	The step failed.

build_new_comment_actions

Convert deduplicated findings into ReviewActionProposal objects.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: build_new_comment_actions

Used by built-in workflows: review-pr

Available to later steps: review_action_proposals

Inputs (from ctx.data)

Name	Type	Description
deduped_findings	List[Finding]	-

Outputs (saved to ctx.data)

Name	Type	Description
review_action_proposals	List[ReviewActionProposal]	-

Returns

Result	Saved for later steps	Description
Success	review_action_proposals	The step completed.
Skip	review_action_proposals	Nothing to do (no findings).

validate_review_actions

Present each ReviewActionProposal to the user for approval, editing, or skipping.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: validate_review_actions

Used by built-in workflows: review-pr, review-pr-thread-resolution

Available to later steps: approved_action_proposals

Inputs (from ctx.data)

Name	Type	Description
review_action_proposals	List[ReviewActionProposal]	-
review_diff	str	Full PR diff for extracting diff context per comment

Outputs (saved to ctx.data)

Name	Type	Description
approved_action_proposals	List[ReviewActionProposal]	-

Returns

Result	Saved for later steps	Description
Success	approved_action_proposals	The step completed.
Skip	approved_action_proposals	Nothing to do (none approved).
Error	-	The step failed.

submit_review_actions

Submit approved ReviewActionProposal objects to GitHub.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: submit_review_actions

Used by built-in workflows: review-pr, review-pr-thread-resolution

Inputs (from ctx.data)

Name	Type	Description
approved_action_proposals	List[ReviewActionProposal]	-
review_pr_number	int	-
review_commit_sha	str	Head commit SHA (fetched if missing)
review_diff	str	Full PR diff for inline comment validation

Returns

Result	Saved for later steps	Description
Success	-	The step completed.
Skip	-	Nothing to do (no approved actions).
Error	-	The step failed.

build_thread_review_candidates

Select open inline threads worth AI analysis.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: build_thread_review_candidates

Used by built-in workflows: review-pr-thread-resolution

Available to later steps: thread_review_candidates

Inputs (from ctx.data)

Name	Type	Description
review_threads	List[UICommentThread]	Unresolved inline review threads
review_pr	UIPullRequest	PR object with author info
review_current_user	str	GitHub login running Titan

Outputs (saved to ctx.data)

Name	Type	Description
thread_review_candidates	List[ThreadReviewCandidate]	-

Returns

Result	Saved for later steps	Description
Success	thread_review_candidates	The step completed.
Skip	thread_review_candidates	Nothing to do (no candidates).
Error	-	The step failed.

build_thread_review_contexts

Enrich thread candidates with diff hunk context and full reply history.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: build_thread_review_contexts

Used by built-in workflows: review-pr-thread-resolution

Available to later steps: thread_review_contexts

Requires

Name	Type	Description
ctx.github	-	Optional GitHub client used to inspect referenced commits.

Inputs (from ctx.data)

Name	Type	Description
thread_review_candidates	List[ThreadReviewCandidate]	-
review_threads	List[UICommentThread]	For extracting reply history
review_diff	str	Full PR unified diff

Outputs (saved to ctx.data)

Name	Type	Description
thread_review_contexts	List[ThreadReviewContext]	-

Returns

Result	Saved for later steps	Description
Success	thread_review_contexts	The step completed.
Skip	thread_review_contexts	Nothing to do (no candidates).
Error	-	The step failed.

ai_thread_resolution

AI call: decide what to do with each open thread.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: ai_thread_resolution

Used by built-in workflows: review-pr-thread-resolution

Available to later steps: raw_thread_decisions

Inputs (from ctx.data)

Name	Type	Description
thread_review_contexts	List[ThreadReviewContext]	-

Outputs (saved to ctx.data)

Name	Type	Description
raw_thread_decisions	list	Raw AI output aggregated across batches, before normalization

Returns

Result	Saved for later steps	Description
Success	raw_thread_decisions	The step completed.
Error	-	The step failed.

normalize_thread_decisions

Parse and validate raw AI output into ThreadDecision models.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: normalize_thread_decisions

Used by built-in workflows: review-pr-thread-resolution

Available to later steps: thread_decisions

Inputs (from ctx.data)

Name	Type	Description
raw_thread_decisions	list | str	Raw AI output from ai_thread_resolution

Outputs (saved to ctx.data)

Name	Type	Description
thread_decisions	List[ThreadDecision]	Validated ThreadDecision objects

Returns

Result	Saved for later steps	Description
Success	thread_decisions	The step completed.
Error	-	The step failed.

build_thread_actions

Transform ThreadDecision objects into ReviewActionProposal objects.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: build_thread_actions

Used by built-in workflows: review-pr-thread-resolution

Available to later steps: review_action_proposals

Inputs (from ctx.data)

Name	Type	Description
thread_decisions	List[ThreadDecision]	-
thread_review_contexts	List[ThreadReviewContext]	-

Outputs (saved to ctx.data)

Name	Type	Description
review_action_proposals	List[ReviewActionProposal]	-

Returns

Result	Saved for later steps	Description
Success	review_action_proposals	The step completed.
Skip	review_action_proposals	Nothing to do (no actionable decisions).
Error	-	The step failed.

Worktree Support

create_worktree

Create a worktree for PR review.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: create_worktree

Used by built-in workflows: review-pr

Available to later steps: worktree_path, worktree_created

Outputs (saved to ctx.data)

Name	Type	Description
worktree_path	str	Absolute path to worktree
worktree_created	bool	Whether worktree was created

Returns

Result	Saved for later steps	Description
Success	worktree_path, worktree_created	Worktree created
Error	-	Failed to create worktree

cleanup_worktree

Cleanup a worktree created for PR review.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: cleanup_worktree

Used by built-in workflows: review-pr

Returns

Result	Saved for later steps	Description
Success	-	Worktree cleaned up
Skip	-	Nothing to clean up, no git client, or removal failed
Never returns Exit	-	that would stop the whole workflow, and this step may run
before others (nothing was created is a normal case when worktree setup was	-	-
allowed to fail). Skip keeps the workflow going.	-	-

Releases

select_release

List published GitHub releases and select one to use as a notes source.

How to read this contract

• Inputs (from ctx.data) shows what the step expects before it runs.
• Outputs (saved to ctx.data) shows the metadata keys later steps can read after Success or Skip.
• Returns describes the workflow result type (Success, Skip, Error, Exit), not a separate function return payload.

Workflow usage

- plugin: github
  step: select_release

Available to later steps: selected_release, selected_release_tag, selected_release_notes, selected_release_url

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
github_release_limit	int, optional	Maximum number of releases to list. Defaults to 15.

Outputs (saved to ctx.data)

Name	Type	Description
selected_release	UIRelease	Selected GitHub release, including its notes body.
selected_release_tag	str	Tag name of the selected release.
selected_release_notes	str	Release notes body of the selected release.
selected_release_url	str	URL of the selected release.

Returns

Result	Saved for later steps	Description
Success	selected_release, selected_release_tag, selected_release_notes, selected_release_url	If a release is selected successfully.
Skip	selected_release, selected_release_tag, selected_release_notes, selected_release_url	If no published releases exist.
Error	-	If the GitHub client is not available or the request fails.