# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for GitHub v3 REST Checks API
  version: 1.0.0
extends: openapi/github-checks-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-24'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 12
- target: $.paths['/repos/{owner}/{repo}/check-runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a check run for a commit
      effect: write
      questions:
      - How does my app report a CI result against a specific commit?
      - Can I create a check run that already has a conclusion and an output summary?
      - Do I need a GitHub App to create check runs, or will a personal token work?
      instructions:
      - text: Create a check run named {name} on commit {head_sha} in {owner}/{repo}.
        slots:
          name: requestBody.name
          head_sha: requestBody.head_sha
          owner: path.owner
          repo: path.repo
      - text: Start check {name} for commit {head_sha} in {owner}/{repo} with status {status}.
        slots:
          name: requestBody.name
          head_sha: requestBody.head_sha
          owner: path.owner
          repo: path.repo
          status: requestBody.status
      - text: Report a finished check {name} on {head_sha} in {owner}/{repo} with conclusion {conclusion} and output {output}.
        slots:
          name: requestBody.name
          head_sha: requestBody.head_sha
          owner: path.owner
          repo: path.repo
          conclusion: requestBody.conclusion
          output: requestBody.output
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/check-runs/{check_run_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a check run
      effect: read
      questions:
      - What's the status and conclusion of a specific check run?
      - Can I look up a single check run by its id?
      instructions:
      - text: Get check run {check_run_id} in {owner}/{repo}.
        slots:
          check_run_id: path.check_run_id
          owner: path.owner
          repo: path.repo
      - text: Show whether check run {check_run_id} in {owner}/{repo} passed or failed.
        slots:
          check_run_id: path.check_run_id
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/check-runs/{check_run_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update or complete a check run
      effect: write
      questions:
      - How do I mark an in-progress check run as completed with a conclusion?
      - Can I add more output or action buttons to an existing check run?
      instructions:
      - text: Complete check run {check_run_id} in {owner}/{repo} with conclusion {conclusion}.
        slots:
          check_run_id: path.check_run_id
          owner: path.owner
          repo: path.repo
          conclusion: requestBody.conclusion
      - text: Set existing check run {check_run_id} in {owner}/{repo} to status {status}.
        slots:
          check_run_id: path.check_run_id
          owner: path.owner
          repo: path.repo
          status: requestBody.status
      - text: Replace the output of check run {check_run_id} in {owner}/{repo} with {output}.
        slots:
          check_run_id: path.check_run_id
          owner: path.owner
          repo: path.repo
          output: requestBody.output
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/check-runs/{check_run_id}/annotations'].get
  update:
    x-apievangelist-phrasing:
      intent: List annotations on a check run
      effect: read
      questions:
      - What line-level warnings or failures did a check run annotate?
      - Which files and lines were flagged by a particular check run?
      instructions:
      - text: List the annotations for check run {check_run_id} in {owner}/{repo}.
        slots:
          check_run_id: path.check_run_id
          owner: path.owner
          repo: path.repo
      - text: Show the flagged files and lines from check run {check_run_id} in {owner}/{repo}.
        slots:
          check_run_id: path.check_run_id
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/check-runs/{check_run_id}/rerequest'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-run a single check run
      effect: write
      questions:
      - Can I re-run one failed check without pushing new code?
      - What event fires when a single check run is re-requested?
      instructions:
      - text: Re-run check run {check_run_id} in {owner}/{repo}.
        slots:
          check_run_id: path.check_run_id
          owner: path.owner
          repo: path.repo
      - text: Rerequest only the single check run {check_run_id} on {owner}/{repo} without a new push.
        slots:
          check_run_id: path.check_run_id
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/check-suites'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a check suite manually
      effect: write
      questions:
      - When would I need to create a check suite by hand instead of letting it happen automatically?
      - Can I create a check suite for a commit after turning off automatic creation?
      instructions:
      - text: Create a check suite for commit {head_sha} in {owner}/{repo}.
        slots:
          head_sha: requestBody.head_sha
          owner: path.owner
          repo: path.repo
      - text: Manually open a new check suite on {head_sha} in repository {owner}/{repo}.
        slots:
          head_sha: requestBody.head_sha
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/check-suites/preferences'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change automatic check suite creation for a repo
      effect: write
      questions:
      - Can I stop check suites from being created automatically on every push?
      - How do I turn automatic check suite creation back on for an app in a repository?
      instructions:
      - text: Set the check suite auto-trigger preferences for {owner}/{repo} to {auto_trigger_checks}.
        slots:
          owner: path.owner
          repo: path.repo
          auto_trigger_checks: requestBody.auto_trigger_checks
      - text: Turn off automatic check suite creation in {owner}/{repo} for the apps in {auto_trigger_checks}.
        slots:
          owner: path.owner
          repo: path.repo
          auto_trigger_checks: requestBody.auto_trigger_checks
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/check-suites/{check_suite_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a check suite
      effect: read
      questions:
      - What's the overall status and conclusion of a check suite?
      - Can I fetch one check suite by its id?
      instructions:
      - text: Get check suite {check_suite_id} in {owner}/{repo}.
        slots:
          check_suite_id: path.check_suite_id
          owner: path.owner
          repo: path.repo
      - text: Show the status and conclusion of check suite {check_suite_id} in {owner}/{repo}.
        slots:
          check_suite_id: path.check_suite_id
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/check-suites/{check_suite_id}/check-runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List the check runs in a check suite
      effect: read
      questions:
      - Which check runs belong to a given check suite?
      - Can I filter a suite's check runs by name or status?
      instructions:
      - text: List the check runs in check suite {check_suite_id} of {owner}/{repo}.
        slots:
          check_suite_id: path.check_suite_id
          owner: path.owner
          repo: path.repo
      - text: Show {status} runs named {check_name} inside suite {check_suite_id} of {owner}/{repo}.
        slots:
          status: query.status
          check_name: query.check_name
          check_suite_id: path.check_suite_id
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/check-suites/{check_suite_id}/rerequest'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-run an entire check suite
      effect: write
      questions:
      - Can I re-run every check in a suite without pushing a new commit?
      - How do I retrigger a whole check suite after a flaky failure?
      instructions:
      - text: Re-run check suite {check_suite_id} in {owner}/{repo}.
        slots:
          check_suite_id: path.check_suite_id
          owner: path.owner
          repo: path.repo
      - text: Rerequest the whole suite {check_suite_id} on {owner}/{repo} without a new push.
        slots:
          check_suite_id: path.check_suite_id
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/commits/{ref}/check-runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List check runs for a commit, branch or tag
      effect: read
      questions:
      - Did all the checks pass on the latest commit of my branch?
      - Can I see check runs for a tag or branch name rather than a commit SHA?
      - Which check runs from one specific app ran on a commit?
      instructions:
      - text: List the check runs for {ref} in {owner}/{repo}.
        slots:
          ref: path.ref
          owner: path.owner
          repo: path.repo
      - text: Show {status} check runs named {check_name} on ref {ref} in {owner}/{repo}.
        slots:
          status: query.status
          check_name: query.check_name
          ref: path.ref
          owner: path.owner
          repo: path.repo
      - text: List check runs from app {app_id} on {ref} in {owner}/{repo}.
        slots:
          app_id: query.app_id
          ref: path.ref
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'
- target: $.paths['/repos/{owner}/{repo}/commits/{ref}/check-suites'].get
  update:
    x-apievangelist-phrasing:
      intent: List check suites for a commit, branch or tag
      effect: read
      questions:
      - Which check suites ran against a given commit, branch or tag?
      - Can I narrow a ref's check suites down to one app?
      instructions:
      - text: List the check suites for {ref} in {owner}/{repo}.
        slots:
          ref: path.ref
          owner: path.owner
          repo: path.repo
      - text: Show check suites created by app {app_id} on ref {ref} in {owner}/{repo}.
        slots:
          app_id: query.app_id
          ref: path.ref
          owner: path.owner
          repo: path.repo
      method: generated
      generated: '2026-09-24'