openapi: 3.2.0
info:
version: 1.1.4
title: github-repos-api Suites API
description: 'Use the REST API to create, manage and control the workflow of public and
private GitHub repositories.'
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://docs.github.com/articles/github-terms-of-service
contact:
name: Support
url: https://support.github.com/contact
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: api.github.com
protocol:
description: Self-hosted Enterprise Server protocol
default: https
tags:
- name: Suites
paths:
/repos/{owner}/{repo}/check-suites:
post:
summary: GitHub Create Check Suite
description: 'Creates a check suite manually. By default, check suites are automatically created when you create a [check run](https://docs.github.com/enterprise-server@3.9/rest/checks/runs). You only need to use this endpoint for manually creating check suites when you''ve disabled automatic creation using "[Update repository preferences for check suites](https://docs.github.com/enterprise-server@3.9/rest/checks/suites#update-repository-preferences-for-check-suites)".
**Note:** The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty `pull_requests` array and a `null` value for `head_branch`.
OAuth apps and personal access tokens (classic) cannot use this endpoint.'
tags:
- Suites
operationId: createCheckSuite
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/checks/suites#create-a-check-suite
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
head_sha:
type: string
description: The sha of the head commit.
required:
- head_sha
examples:
default:
value:
head_sha: d6fde92930d4715a2b49857d24b940956b26d2d3
responses:
'200':
description: Response when the suite already exists
content:
application/json:
schema:
$ref: '#/components/schemas/check-suite'
examples:
default:
$ref: '#/components/examples/check-suite'
'201':
description: Response when the suite was created
content:
application/json:
schema:
$ref: '#/components/schemas/check-suite'
examples:
default:
$ref: '#/components/examples/check-suite'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: checks
subcategory: suites
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/check-suites/preferences:
patch:
summary: GitHub Update Repository Preferences for Check Suites
description: 'Changes the default automatic flow when creating check suites. By default, a check suite is automatically created each time code is pushed to a repository. When you disable the automatic creation of check suites, you can manually [Create a check suite](https://docs.github.com/enterprise-server@3.9/rest/checks/suites#create-a-check-suite).
You must have admin permissions in the repository to set preferences for check suites.'
tags:
- Suites
operationId: updateRepositoryPreferencesForCheckSuites
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/checks/suites#update-repository-preferences-for-check-suites
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
auto_trigger_checks:
type: array
description: Enables or disables automatic creation of CheckSuite events upon pushes to the repository. Enabled by default.
items:
type: object
properties:
app_id:
type: integer
description: The `id` of the GitHub App.
setting:
type: boolean
description: Set to `true` to enable automatic creation of CheckSuite events upon pushes to the repository, or `false` to disable them.
default: true
required:
- app_id
- setting
examples:
default:
value:
auto_trigger_checks:
- app_id: 4
setting: false
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/check-suite-preference'
examples:
default:
$ref: '#/components/examples/check-suite-preference'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: checks
subcategory: suites
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/check-suites/{check_suite_id}:
get:
summary: GitHub Get Check Suite
description: 'Gets a single check suite using its `id`.
**Note:** The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty `pull_requests` array and a `null` value for `head_branch`.
OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint on a private repository.'
tags:
- Suites
operationId: getCheckSuite
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/checks/suites#get-a-check-suite
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/check-suite-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/check-suite'
examples:
default:
$ref: '#/components/examples/check-suite'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: checks
subcategory: suites
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/check-suites/{check_suite_id}/check-runs:
get:
summary: GitHub List Check Runs in Check Suite
description: 'Lists check runs for a check suite using its `id`.
**Note:** The endpoints to manage checks only look for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty `pull_requests` array.
OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint on a private repository.'
tags:
- Suites
operationId: listCheckRunsInCheckSuite
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/checks/runs#list-check-runs-in-a-check-suite
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/check-suite-id'
- $ref: '#/components/parameters/check-name'
- $ref: '#/components/parameters/status'
- name: filter
description: Filters check runs by their `completed_at` timestamp. `latest` returns the most recent check runs.
in: query
required: false
schema:
type: string
enum:
- latest
- all
default: latest
example: latest
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
type: object
required:
- total_count
- check_runs
properties:
total_count:
type: integer
check_runs:
type: array
items:
$ref: '#/components/schemas/check-run'
examples:
default:
$ref: '#/components/examples/check-run-paginated'
headers:
Link:
$ref: '#/components/headers/link'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: checks
subcategory: runs
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/check-suites/{check_suite_id}/rerequest:
post:
summary: GitHub Rerequest Check Suite
description: 'Triggers GitHub to rerequest an existing check suite, without pushing new code to a repository. This endpoint will trigger the [`check_suite` webhook](https://docs.github.com/enterprise-server@3.9/webhooks/event-payloads/#check_suite) event with the action `rerequested`. When a check suite is `rerequested`, its `status` is reset to `queued` and the `conclusion` is cleared.
OAuth apps and personal access tokens (classic) cannot use this endpoint.'
tags:
- Suites
operationId: rerequestCheckSuite
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/checks/suites#rerequest-a-check-suite
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/check-suite-id'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/empty-object'
examples:
default:
value: {}
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: checks
subcategory: suites
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/commits/{ref}/check-suites:
get:
summary: GitHub List Check Suites for Git Reference
description: 'Lists check suites for a commit `ref`. The `ref` can be a SHA, branch name, or a tag name.
**Note:** The endpoints to manage checks only look for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty `pull_requests` array and a `null` value for `head_branch`.
OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint on a private repository.'
tags:
- Suites
operationId: listCheckSuitesForGitReference
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/checks/suites#list-check-suites-for-a-git-reference
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/commit-ref'
- name: app_id
description: Filters check suites by GitHub App `id`.
in: query
required: false
schema:
type: integer
example: 1
- $ref: '#/components/parameters/check-name'
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
type: object
required:
- total_count
- check_suites
properties:
total_count:
type: integer
check_suites:
type: array
items:
$ref: '#/components/schemas/check-suite'
examples:
default:
$ref: '#/components/examples/check-suite-paginated'
headers:
Link:
$ref: '#/components/headers/link'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: checks
subcategory: suites
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
parameters:
commit-ref:
name: ref
description: The commit reference. Can be a commit SHA, branch name (`heads/BRANCH_NAME`), or tag name (`tags/TAG_NAME`). For more information, see "[Git References](https://git-scm.com/book/en/v2/Git-Internals-Git-References)" in the Git documentation.
in: path
required: true
schema:
type: string
x-multi-segment: true
status:
name: status
description: Returns check runs with the specified `status`.
in: query
required: false
schema:
type: string
enum:
- queued
- in_progress
- completed
per-page:
name: per_page
description: The number of results per page (max 100). For more information, see "[Using pagination in the REST API](https://docs.github.com/enterprise-server@3.9/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
in: query
schema:
type: integer
default: 30
check-suite-id:
name: check_suite_id
description: The unique identifier of the check suite.
in: path
required: true
schema:
type: integer
repo:
name: repo
description: The name of the repository without the `.git` extension. The name is not case sensitive.
in: path
required: true
schema:
type: string
page:
name: page
description: The page number of the results to fetch. For more information, see "[Using pagination in the REST API](https://docs.github.com/enterprise-server@3.9/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
in: query
schema:
type: integer
default: 1
check-name:
name: check_name
description: Returns check runs with the specified `name`.
in: query
required: false
schema:
type: string
owner:
name: owner
description: The account owner of the repository. The name is not case sensitive.
in: path
required: true
schema:
type: string
schemas:
code-of-conduct:
title: Code Of Conduct
description: Code Of Conduct
type: object
properties:
key:
type: string
example: contributor_covenant
name:
type: string
example: Contributor Covenant
url:
type: string
format: uri
example: https://api.github.com/codes_of_conduct/contributor_covenant
body:
type: string
example: "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nIn the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.\n\n## Our Standards\n\nExamples of behavior that contributes to creating a positive environment include:\n\n* Using welcoming and inclusive language\n* Being respectful of differing viewpoints and experiences\n* Gracefully accepting constructive criticism\n* Focusing on what is best for the community\n* Showing empathy towards other community members\n\nExamples of unacceptable behavior by participants include:\n\n* The use of sexualized language or imagery and unwelcome sexual attention or advances\n* Trolling, insulting/derogatory comments, and personal or political attacks\n* Public or private harassment\n* Publishing others' private information, such as a physical or electronic address, without explicit permission\n* Other conduct which could reasonably be considered inappropriate in a professional setting\n\n## Our Responsibilities\n\nProject maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n to any instances of unacceptable behavior.\n\nProject maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.\n\n## Scope\n\nThis Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address,\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [EMAIL]. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.\n\nProject maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.4, available at [http://contributor-covenant.org/version/1/4](http://contributor-covenant.org/version/1/4/).\n"
html_url:
type: string
format: uri
example: https://api.github.com/repos/octocat/Hello-World
required:
- url
- html_url
- key
- name
minimal-repository:
title: Minimal Repository
description: Minimal Repository
type: object
properties:
id:
type: integer
format: int64
example: 1296269
node_id:
type: string
example: MDEwOlJlcG9zaXRvcnkxMjk2MjY5
name:
type: string
example: Hello-World
full_name:
type: string
example: octocat/Hello-World
owner:
$ref: '#/components/schemas/simple-user'
private:
type: boolean
example: true
html_url:
type: string
format: uri
example: https://github.com/octocat/Hello-World
description:
type: string
example: This your first repo!
fork:
type: boolean
example: true
url:
type: string
format: uri
example: https://api.github.com/repos/octocat/Hello-World
archive_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}
assignees_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/assignees{/user}
blobs_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}
branches_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/branches{/branch}
collaborators_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}
comments_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/comments{/number}
commits_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/commits{/sha}
compare_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}
contents_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/contents/{+path}
contributors_url:
type: string
format: uri
example: http://api.github.com/repos/octocat/Hello-World/contributors
deployments_url:
type: string
format: uri
example: http://api.github.com/repos/octocat/Hello-World/deployments
downloads_url:
type: string
format: uri
example: http://api.github.com/repos/octocat/Hello-World/downloads
events_url:
type: string
format: uri
example: http://api.github.com/repos/octocat/Hello-World/events
forks_url:
type: string
format: uri
example: http://api.github.com/repos/octocat/Hello-World/forks
git_commits_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/git/commits{/sha}
git_refs_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/git/refs{/sha}
git_tags_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/git/tags{/sha}
git_url:
type: string
issue_comment_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/issues/comments{/number}
issue_events_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/issues/events{/number}
issues_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/issues{/number}
keys_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/keys{/key_id}
labels_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/labels{/name}
languages_url:
type: string
format: uri
example: http://api.github.com/repos/octocat/Hello-World/languages
merges_url:
type: string
format: uri
example: http://api.github.com/repos/octocat/Hello-World/merges
milestones_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/milestones{/number}
notifications_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}
pulls_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/pulls{/number}
releases_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/releases{/id}
ssh_url:
type: string
stargazers_url:
type: string
format: uri
example: http://api.github.com/repos/octocat/Hello-World/stargazers
statuses_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/statuses/{sha}
subscribers_url:
type: string
format: uri
example: http://api.github.com/repos/octocat/Hello-World/subscribers
subscription_url:
type: string
format: uri
example: http://api.github.com/repos/octocat/Hello-World/subscription
tags_url:
type: string
format: uri
example: http://api.github.com/repos/octocat/Hello-World/tags
teams_url:
type: string
format: uri
example: http://api.github.com/repos/octocat/Hello-World/teams
trees_url:
type: string
example: http://api.github.com/repos/octocat/Hello-World/git/trees{/sha}
clone_url:
type: string
mirror_url:
type: string
hooks_url:
type: string
format: uri
example: http://api.github.com/repos/octocat/Hello-World/hooks
svn_url:
type: string
homepage:
type: string
language:
type: string
forks_count:
type: integer
stargazers_count:
type: integer
watchers_count:
type: integer
size:
description: The size of the repository, in kilobytes. Size is calculated hourly. When a repository is initially created, the size is 0.
type: integer
default_branch:
type: string
open_issues_count:
type: integer
is_template:
type: boolean
topics:
type: array
items:
type: string
has_issues:
type: boolean
has_projects:
type: boolean
has_wiki:
type: boolean
has_pages:
type: boolean
has_downloads:
type: boolean
has_discussions:
type: boolean
archived:
type: boolean
disabled:
type: boolean
visibility:
type: string
pushed_at:
type: string
format: date-time
example: '2011-01-26T19:06:43Z'
created_at:
type: string
format: date-time
example: '2011-01-26T19:01:12Z'
updated_at:
type: string
format: date-time
example: '2011-01-26T19:14:43Z'
permissions:
type: object
properties:
admin:
type: boolean
maintain:
type: boolean
push:
type: boolean
triage:
type: boolean
pull:
type: boolean
role_name:
type: string
example: admin
temp_clone_token:
type: string
delete_branch_on_merge:
type: boolean
subscribers_count:
type: integer
network_count:
type: integer
code_of_conduct:
$ref: '#/components/schemas/code-of-conduct'
license:
type: object
properties:
key:
type: string
name:
type: string
spdx_id:
type: string
url:
type: string
node_id:
type: string
forks:
type: integer
example: 0
open_issues:
type: integer
example: 0
watchers:
type: integer
example: 0
allow_forking:
type: boolean
web_commit_signoff_required:
type: boolean
example: false
security_and_analysis:
$ref: '#/components/schemas/security-and-analysis'
required:
- archive_url
- assignees_url
- blobs_url
- branches_url
- collaborators_url
- comments_url
- commits_url
- compare_url
- contents_url
- contributors_url
- deployments_url
- description
- downloads_url
- events_url
- fork
- forks_url
- full_name
- git_commits_url
- git_refs_url
- git_tags_url
- hooks_url
- html_url
- id
- node_id
- issue_comment_url
- issue_events_url
- issues_url
- keys_url
- labels_url
- languages_url
- merges_url
- milestones_url
- name
- notifications_url
- owner
- private
- pulls_url
- releases_url
- stargazers_url
- statuses_url
- subscribers_url
- subscription_url
- tags_url
- teams_url
- trees_url
- url
check-suite:
title: CheckSuite
description: suite of checks performed on the code of a given code change
type: object
properties:
id:
type: integer
example: 5
node_id:
type: string
example: MDEwOkNoZWNrU3VpdGU1
head_branch:
type: string
example: master
head_sha:
description: The SHA of the head commit that is being checked.
example: 009b8a3a9ccbb128af87f9b1c0f4c62e8a304f6d
type: string
status:
# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-suites-api-openapi.yml