GitHub Repos API
The GitHub Repos API is a set of REST endpoints that let you programmatically create, read, update, and delete repositories and their resources, giving you control over a repos lifecycle and configuration.
OpenAPI Specification
openapi: 3.1.0
info:
version: 1.1.4
title: github-repos-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: http://localhost:8080/rest/github-repos-api/1.1.4
description: Sandbox
externalDocs:
description: GitHub Enterprise Developer Docs
url: https://docs.github.com/[email protected]/rest/
tags:
- name: App Installations
description: GitHub App installation information.
- name: Archives
description: Repository archive downloads (tarball/zipball).
- name: Assignees
description: Users available for issue assignment.
- name: Branch Policies
description: Branch protection policies for deployment environments.
- name: Check Runs
description: Individual check runs that report status for continuous integration.
- name: Check Suites
description: Collections of check runs associated with a specific commit.
- name: CODEOWNERS
description: CODEOWNERS file validation and errors.
- name: Commit Comments
description: Comments on specific commits in a repository.
- name: Commit Statuses
description: Status checks on commits from CI/CD systems.
- name: Commits
description: Git commits including history, comparisons, and associated data.
- name: Contents
description: Repository file and directory contents.
- name: Contributors
description: Repository contributors and their activity.
- name: Dependency Graph
description: Repository dependencies and SBOM generation.
- name: Deploy Keys
description: SSH keys for deployment access to repositories.
- name: Deployment Statuses
description: Status updates for deployment progress and results.
- name: Deployments
description: Deployment configurations for releasing code to environments.
- name: Environment Secrets
description: Encrypted secrets for deployment environments.
- name: Environment Variables
description: Configuration variables for deployment environments.
- name: Environments
description: Deployment environments with protection rules and secrets.
- name: Events
description: Repository activity events.
- name: Forks
description: Repository forks created from this repository.
- name: Git Blobs
description: Git blob objects representing file contents.
- name: Git LFS
description: Git Large File Storage configuration.
- name: Git Refs
description: Git references including branches and tags.
- name: Git Tags
description: Git annotated tag objects.
- name: Git Trees
description: Git tree objects representing directory structures.
- name: Labels
description: Labels for categorizing issues and pull requests.
- name: Languages
description: Programming languages detected in the repository.
- name: Licenses
description: Repository license information.
- name: Merges
description: Branch merging operations.
- name: Milestones
description: Milestones for tracking issue and PR progress.
- name: Notifications
description: Repository notification subscriptions.
- name: Pages
description: GitHub Pages site configuration.
- name: Pages Builds
description: GitHub Pages build history and status.
- name: Reactions
description: Emoji reactions on comments and releases.
- name: README
description: Repository README file contents.
- name: Release Assets
description: Files attached to releases for distribution.
- name: Releases
description: Repository releases for distributing software versions.
- name: Replicas
description: Repository cache and replica information.
- name: Repositories
description: Manage GitHub repositories including creation, configuration, and metadata.
- name: Repository Events
description: Trigger repository dispatch events.
- name: Search
description: Search across repositories.
- name: Secret Scanning
description: Secret scanning alerts for exposed credentials.
- name: Stargazers
description: Users who have starred the repository.
- name: Statistics
description: Repository statistics including commit activity and contributors.
- name: Teams
description: Teams with access to the repository.
- name: Templates
description: Create repositories from templates.
- name: Topics
description: Repository classification topics.
- name: Transfers
description: Repository ownership transfer operations.
- name: Vulnerability Alerts
description: Security vulnerability alerts from Dependabot.
- name: Watchers
description: Users watching the repository for notifications.
paths:
/repos/{owner}/{repo}:
get:
summary: GitHub Get Repository
description: |-
The `parent` and `source` objects are present when the repository is a fork. `parent` is the repository this repository was forked from, `source` is the ultimate source for the network.
**Note:** In order to see the `security_and_analysis` block for a repository you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "[Managing security managers in your organization](https://docs.github.com/[email protected]/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)."
tags:
- Repositories
operationId: getRepository
externalDocs:
description: API method documentation
url: https://docs.github.com/[email protected]/rest/repos/repos#get-a-repository
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
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/full-repository'
examples:
Default:
$ref: '#/components/examples/full-repository-default-response'
'301':
$ref: '#/components/responses/moved_permanently'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: repos
x-api-evangelist-certified: '2025-07-16'
x-api-naftiko-published: '2025-07-25'
security:
- bearerHttpAuthentication: []
x-microcks-operation:
dispatcher: SCRIPT
dispatcherRules: return "Default"
patch:
summary: GitHub Update Repository
description: '**Note**: To edit a repository''s topics, use the [Replace all repository topics](https://docs.github.com/[email protected]/rest/repos/repos#replace-all-repository-topics) endpoint.'
tags:
- Repositories
operationId: updateRepository
externalDocs:
description: API method documentation
url: https://docs.github.com/[email protected]/rest/repos/repos#update-a-repository
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: false
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the repository.
description:
type: string
description: short description of the repository.
homepage:
type: string
description: URL with more information about the repository.
private:
type: boolean
description: |-
Either `true` to make the repository private or `false` to make it public. Default: `false`.
**Note**: You will Get `422` error if the organization restricts [changing repository visibility](https://docs.github.com/[email protected]/articles/repository-permission-levels-for-an-organization#changing-the-visibility-of-repositories) to organization owners and a non-owner tries to change the value of private.
default: false
visibility:
type: string
description: The visibility of the repository.
enum:
- public
- private
- internal
security_and_analysis:
type: object
description: |-
Specify which security and analysis features to enable or disable for the repository.
To use this parameter, you must have admin permissions for the repository or be an owner or security manager for the organization that owns the repository. For more information, see "[Managing security managers in your organization](https://docs.github.com/[email protected]/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)."
For example, to enable GitHub Advanced Security, use this data in the body of the `PATCH` request:
`{ "security_and_analysis": {"advanced_security": { "status": "enabled" } } }`.
You can check which security and analysis features are currently enabled by using a `GET /repos/{owner}/{repo}` request.
properties:
advanced_security:
type: object
description: Use the `status` property to enable or disable GitHub Advanced Security for this repository. For more information, see "[About GitHub Advanced
Security](/github/getting-started-with-github/learning-about-github/about-github-advanced-security)."
properties:
status:
type: string
description: Can be `enabled` or `disabled`.
secret_scanning:
type: object
description: Use the `status` property to enable or disable secret scanning for this repository. For more information, see "[About secret
scanning](/code-security/secret-security/about-secret-scanning)."
properties:
status:
type: string
description: Can be `enabled` or `disabled`.
secret_scanning_push_protection:
type: object
description: Use the `status` property to enable or disable secret scanning push protection for this repository. For more information, see "[Protecting pushes with secret
scanning](/code-security/secret-scanning/protecting-pushes-with-secret-scanning)."
properties:
status:
type: string
description: Can be `enabled` or `disabled`.
has_issues:
type: boolean
description: Either `true` to enable issues for this repository or `false` to disable them.
default: true
has_projects:
type: boolean
description: Either `true` to enable projects for this repository or `false` to disable them. **Note:** If you're creating a repository in an organization that has disabled
repository projects, the default is `false`, and if you pass `true`, the API returns an error.
default: true
has_wiki:
type: boolean
description: Either `true` to enable the wiki for this repository or `false` to disable it.
default: true
is_template:
type: boolean
description: Either `true` to make this repo available as a template repository or `false` to prevent it.
default: false
default_branch:
type: string
description: Updates the default branch for this repository.
allow_squash_merge:
type: boolean
description: Either `true` to allow squash-merging pull requests, or `false` to prevent squash-merging.
default: true
allow_merge_commit:
type: boolean
description: Either `true` to allow merging pull requests with a merge commit, or `false` to prevent merging pull requests with merge commits.
default: true
allow_rebase_merge:
type: boolean
description: Either `true` to allow rebase-merging pull requests, or `false` to prevent rebase-merging.
default: true
delete_branch_on_merge:
type: boolean
description: Either `true` to allow automatically deleting head branches when pull requests are merged, or `false` to prevent automatic deletion.
default: false
allow_update_branch:
type: boolean
description: Either `true` to always allow a pull request head branch that is behind its base branch to be updated even if it is not required to be up to date before merging, or
false otherwise.
default: false
use_squash_pr_title_as_default:
type: boolean
description: Either `true` to allow squash-merge commits to use pull request title, or `false` to use commit message. **This property has been deprecated. Please use
`squash_merge_commit_title` instead.
default: false
deprecated: true
squash_merge_commit_title:
type: string
enum:
- PR_TITLE
- COMMIT_OR_PR_TITLE
description: |-
The default value for a squash merge commit title:
- `PR_TITLE` - default to the pull request's title.
- `COMMIT_OR_PR_TITLE` - default to the commit's title (if only one commit) or the pull request's title (when more than one commit).
squash_merge_commit_message:
type: string
enum:
- PR_BODY
- COMMIT_MESSAGES
- BLANK
description: |-
The default value for a squash merge commit message:
- `PR_BODY` - default to the pull request's body.
- `COMMIT_MESSAGES` - default to the branch's commit messages.
- `BLANK` - default to a blank commit message.
merge_commit_title:
type: string
enum:
- PR_TITLE
- MERGE_MESSAGE
description: |-
The default value for a merge commit title.
- `PR_TITLE` - default to the pull request's title.
- `MERGE_MESSAGE` - default to the classic title for a merge message (e.g., Merge pull request #123 from branch-name).
merge_commit_message:
type: string
enum:
- PR_BODY
- PR_TITLE
- BLANK
description: |-
The default value for a merge commit message.
- `PR_TITLE` - default to the pull request's title.
- `PR_BODY` - default to the pull request's body.
- `BLANK` - default to a blank commit message.
archived:
type: boolean
description: Whether to archive this repository. `false` will unarchive a previously archived repository.
default: false
allow_forking:
type: boolean
description: Either `true` to allow private forks, or `false` to prevent private forks.
default: false
web_commit_signoff_required:
type: boolean
description: Either `true` to require contributors to sign off on web-based commits, or `false` to not require contributors to sign off on web-based commits.
default: false
examples:
default:
value:
name: Hello-World
description: This is your first repository
homepage: https://github.com
private: true
has_issues: true
has_projects: true
has_wiki: true
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/full-repository'
examples:
Default:
$ref: '#/components/examples/full-repository'
'307':
$ref: '#/components/responses/temporary_redirect'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: repos
previews:
- required: false
name: nebula
note: |-
You can set the visibility of a repository using the new `visibility` parameter in the [Repositories API](https://docs.github.com/[email protected]/rest/repos), and Get repository's visibility with a new response key. For more information, see the [blog post](https://developer.github.com/changes/2019-12-03-internal-visibility-changes/).
To access repository visibility during the preview period, you must provide a custom [media type](https://docs.github.com/[email protected]/rest/overview/media-types) in the `Accept` header:
```shell
application/vnd.github.nebula-preview+json
```
- required: false
name: baptiste
note: |-
The `is_template` and `template_repository` keys are currently available for developer to preview. See [Create a repository using a template](https://docs.github.com/[email protected]/rest/repos/repos#create-a-repository-using-a-template) to learn how to create template repositories. To access these new response keys during the preview period, you must provide a custom [media type](https://docs.github.com/[email protected]/rest/overview/media-types) in the `Accept` header:
```shell
application/vnd.github.baptiste-preview+json
```
x-api-evangelist-certified: '2025-07-18'
x-api-naftiko-published: '2025-07-25'
security:
- bearerHttpAuthentication: []
x-microcks-operation:
dispatcher: SCRIPT
dispatcherRules: return "Default"
delete:
summary: GitHub Delete Repository
description: |-
Deleting a repository requires admin access.
If an organization owner has configured the organization to prevent members from deleting organization-owned
repositories, you will Get `403 Forbidden` response.
OAuth app tokens and personal access tokens (classic) need the `delete_repo` scope to use this endpoint.
tags:
- Repositories
operationId: deleteRepository
externalDocs:
description: API method documentation
url: https://docs.github.com/[email protected]/rest/repos/repos#delete-a-repository
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
responses:
'204':
description: Response
'307':
$ref: '#/components/responses/temporary_redirect'
'403':
description: 'If an organization owner has configured the organization to prevent members from deleting organization-owned repositories, a member will get this response:'
content:
application/json:
schema:
type: object
properties:
message:
type: string
documentation_url:
type: string
examples:
default:
value:
message: Organization members cannot delete repositories.
documentation_url: https://docs.github.com/[email protected]/rest/repos/repos#delete-a-repository
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: repos
subcategory: repos
security:
- bearerHttpAuthentication: []
x-microcks-operation:
dispatcher: SCRIPT
dispatcherRules: return "Default"
/repos/{owner}/{repo}/assignees:
get:
summary: GitHub List Assignees
description: Lists the [available assignees](https://docs.github.com/[email protected]/articles/assigning-issues-and-pull-requests-to-other-github-users/) for issues in a repository.
tags:
- Assignees
operationId: listAssignees
externalDocs:
description: API method documentation
url: https://docs.github.com/[email protected]/rest/issues/assignees#list-assignees
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $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: array
items:
$ref: '#/components/schemas/simple-user'
examples:
Default:
$ref: '#/components/examples/simple-user-items'
headers:
Link:
$ref: '#/components/headers/link'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: assignees
x-api-evangelist-certified: '2025-07-16'
x-api-naftiko-published: '2025-07-25'
security:
- bearerHttpAuthentication: []
x-microcks-operation:
dispatcher: SCRIPT
dispatcherRules: return "Default"
/repos/{owner}/{repo}/assignees/{assignee}:
get:
summary: GitHub Check if User Can Be Assigned
description: |-
Checks if a user has permission to be assigned to an issue in this repository.
If the `assignee` can be assigned to issues in the repository, a `204` header with no content is returned.
Otherwise a `404` status code is returned.
tags:
- Assignees
operationId: checkIfUserCanBeAssigned
externalDocs:
description: API method documentation
url: https://docs.github.com/[email protected]/rest/issues/assignees#check-if-a-user-can-be-assigned
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- name: assignee
in: path
required: true
schema:
type: string
example: example_value
- 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:
'204':
description: If the `assignee` can be assigned to issues in the repository, a `204` header with no content is returned.
'404':
description: Otherwise a `404` status code is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/basic-error'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: issues
subcategory: assignees
security:
- bearerHttpAuthentication: []
x-microcks-operation:
dispatcher: SCRIPT
dispatcherRules: return "Default"
/repos/{owner}/{repo}/check-runs:
post:
summary: GitHub Create Check Run
description: Creates a new check run for a specific commit in a repository. To create a check run, you must use a GitHub App. OAuth apps and authenticated users are not able to create a check
suite. array.
tags:
- Check Runs
operationId: createCheckRun
externalDocs:
description: API method documentation
url: https://docs.github.com/[email protected]/rest/checks/runs#create-a-check-run
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:
name:
type: string
description: The name of the check. For example, "code-coverage".
head_sha:
type: string
description: The SHA of the commit.
details_url:
type: string
description: The URL of the integrator's site that has the full details of the check. If the integrator does not provide this, then the homepage of the GitHub app is used.
external_id:
type: string
description: reference for the run on the integrator's system.
status:
type: string
description: The current status.
enum:
- queued
- in_progress
- completed
default: queued
started_at:
type: string
format: date-time
description: 'The time that the check run began. This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`.'
conclusion:
type: string
description: |-
**Required if you provide `completed_at` or a `status` of `completed`**. The final conclusion of the check.
**Note:** Providing `conclusion` will automatically set the `status` parameter to `completed`. You cannot change a check run conclusion to `stale`, only GitHub can set this.
enum:
- action_required
- cancelled
- failure
- neutral
- success
- skipped
- stale
- timed_out
completed_at:
type: string
format: date-time
description: 'The time the check completed. This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`.'
output:
type: object
description: Check runs can accept a variety of data in the `output` object, including a `title` and `summary` and can optionally provide descriptive details about the run.
properties:
title:
type: string
description: The title of the check run.
summary:
type: string
maxLength: 65535
description: 'The summary of the check run. This parameter supports Markdown. **Maximum length**: 65535 characters.'
text:
type: string
maxLength: 65535
description: 'The details of the check run. This parameter supports Markdown. **Maximum length**: 65535 characters.'
annotations:
type: array
description: Adds information from your analysis to specific lines of code. Annotations are visible on GitHub in the **Checks** and **Files changed** tab of the pull request. The
Checks API limits the number of annotations to a maximum of 50 per API request. To create more than 50 annotations, you have to make multiple requests to the [Update a check
run](https://docs.github.com/[email protected]/rest/checks/runs#update-a-check-run) endpoint. Each time you update the check run, annotations are appended to the list of
annotations that already exist for the check run. GitHub Actions are limited to 10 warning annotations and 10 error annotations per step. For details about how you can view
annotations on GitHub, see "[About status checks](https://docs.github.com/[email protected]/articles/about-status-checks#checks)".
maxItems: 50
items:
type: object
properties:
path:
type: string
description: The path of the file to add an annotation to. For example, `assets/css/main.css`.
start_line:
type: integer
description: The start line of the annotation. Line numbers start at 1.
end_line:
type: integer
description: The end line of the annotation.
start_column:
type: integer
# --- truncated at 32 KB (1000 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-repos-api-openapi.yml