The GitHub Tags API lets you create and manage Git tag objects in a repository. Tags are references that point to specific commits, commonly used to mark release points. The API supports creating annotated tags with messages and tagger information, as well as retrieving tag data including the tagged object, tag name, and message.
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: '{protocol}://{hostname}'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: api.github.com
protocol:
description: Self-hosted Enterprise Server protocol
default: https
externalDocs:
description: GitHub Enterprise Developer Docs
url: https://docs.github.com/[email protected]/rest/
tags:
- name: About
- name: Activity
- name: Alerts
- name: All
- name: Annotations
- name: Applications
- name: Archive
- name: Assets
- name: Assigned
- name: Assignees
- name: Associated
- name: Authenticated
- name: Between
- name: Bill
- name: Blobs
- name: Branches
- name: Builds
- name: Cache
- name: Check
- name: Checks
- name: Code Owners
- name: Combined
- name: Comment
- name: Comments
- name: Commits
- name: Compare
- name: Content
- name: Contributor
- name: Contributors
- name: Count
- name: Create
- name: Day
- name: Delete
- name: Dependencies
- name: Deploy
- name: Deployments
- name: Directories
- name: Disables
- name: Dispatch
- name: Download
- name: Enabled
- name: Enables
- name: Enterprise
- name: Environments
- name: Event
- name: Events
- name: Export
- name: Files
- name: Forks
- name: Generate
- name: Get
- name: Git
- name: Head
- name: Hourly
- name: Information
- name: Installations
- name: Issues
- name: Keys
- name: Labels
- name: Languages
- name: Large File Storage
- name: Last
- name: Latest
- name: Licenses
- name: Lists
- name: Mark
- name: Matching
- name: Materials
- name: Merge
- name: Milestones
- name: Name
- name: Notes
- name: Notifications
- name: Objects
- name: Pages
- name: Policies
- name: Preferences
- name: Protections
- name: Public
- name: Pull
- name: Re-Request
- name: Reaction
- name: Reactions
- name: Read
- name: Readme
- name: References
- name: Releases
- name: Replace
- name: Replication
- name: Repos
- name: Repositories
description: Source control repositories.
- name: Requests
- name: Rerequest
- name: Runs
- name: Scanning
- name: Search
- name: Secrets
- name: Servers
- name: Sets
- name: Sites
- name: Software
- name: Specific
- name: Stargazers
- name: State
- name: States
- name: Status
- name: Statuses
- name: Subscriptions
- name: Suites
- name: Sync
- name: Tar
- name: Teams
- name: Templates
- name: Topics
- name: Transfers
- name: Trees
- name: Update
- name: Upload
- name: Upstream
- name: Users
- name: Variables
- name: Vulnerabilities
- name: Watchers
- name: Weekly
- name: Year
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:
- Get
- 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-response:
$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:
delay: 0
dispatcher: FALLBACK
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
- Update
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:
delay: 0
dispatcher: FALLBACK
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:
- Delete
- 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:
delay: 0
dispatcher: FALLBACK
/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
- Lists
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:
delay: 0
dispatcher: FALLBACK
/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:
- Assigned
- Check
- Users
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:
delay: 0
dispatcher: FALLBACK
/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:
- Checks
- Create
- 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
description: |-
The start column of the annotation. Annotations only support `start_column` and `end_column` on the same line. Omit this parameter if `start_line` and `end_line` have different values. Column numbers start at 1.
end_column:
type: integer
description: |-
The end column of the annotation. Annotations only support `start_column` and `end_column` on the same line. Omit this parameter if `start_line` and `end_line` have different values.
annotation_level:
type: string
description: The level of the annotation.
enum:
- notice
- warning
- failure
message:
type: string
description: |-
short description of the feedback for these lines of code. The maximum size is 64 KB.
title:
type: string
description: |-
# --- truncated at 32 KB (1032 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-repo-tags-api-openapi.yml