GitHub API Repositories

The GitHub Repositories API lets you create, update and retrieve repositories and their related issues, pull requests, and settings. This is the human-friendly guide to the API.

What can you do with Repositories in the GitHub API?

The most common operations people perform on repositories using the GitHub API.

Action HTTP Method Endpoint
Create a Repository
POST /user/repos
Update a Repository
PATCH /repos/{owner}/{repo}
Get a Repository
GET /repos/{owner}/{repo}
List Repositories
GET /user/repos
Search Repositories
GET /search/repositories
Delete a Repository
DELETE /repos/{owner}/{repo}

Repositories are identified by their full name in the format owner/repo. You need this identifier to get, update, or delete a repository. These operations are performed using the HTTP methods GET, PATCH, and DELETE on the same endpoint.

When creating a repository, you need to provide a name. Optionally, you can set the description, visibility (public/private), and initialize with a README file.

If you don't know the exact repository name, you can search for repositories by name, description, topics, or other criteria using the search endpoint.

Properties of a Repository

The 10 most important properties a repository can have in the GitHub API. Some properties are required, some are optional, and some are read-only. Show all properties Only show essential properties

Field Name Type Short Description
id integer Unique identifier for the repository
name string The name of the repository
full_name string The full name of the repository (owner/name)
description string A short description of the repository
private boolean Whether the repository is private
html_url string The URL to view the repository on GitHub
clone_url string The URL to clone the repository
created_at datetime When the repository was created
updated_at datetime When the repository was last updated
language string The primary programming language of the repository
archived boolean Whether the repository is archived
default_branch string The default branch of the repository
disabled boolean Whether the repository is disabled
fork boolean Whether the repository is a fork
forks_count integer Number of forks of this repository
has_issues boolean Whether issues are enabled for the repository
has_pages boolean Whether GitHub Pages is enabled
has_wiki boolean Whether the wiki is enabled
homepage string The repository's homepage URL
license object License information for the repository
open_issues_count integer Number of open issues
owner object Information about the repository owner
pushed_at datetime When the repository was last pushed to
size integer Size of the repository in kilobytes
stargazers_count integer Number of stars the repository has
topics array List of topics associated with the repository
visibility string Repository visibility: public, private, or internal
watchers_count integer Number of watchers of the repository

What to watch out for

Did you know that deleting a repository is permanent and cannot be undone? Or that repository names are case-insensitive? Here are some common pitfalls and gotchas when working with repositories in the GitHub API.

Repository Deletion is Permanent

When you delete a repository, it's permanently removed and cannot be recovered. Make sure you have backups before deleting.

Case-Insensitive Repository Names

Repository names are case-insensitive. MyRepo and myrepo are considered the same repository name.

Rate Limiting

GitHub API has strict rate limits. Authenticated requests get 5,000 requests per hour, while unauthenticated requests get only 60 per hour.

Repository Name Restrictions

Repository names can only contain alphanumeric characters, hyphens, and underscores. They cannot start with a hyphen or be longer than 100 characters.

Fork Relationships

When you fork a repository, the fork field is set to true and the original repository information is stored in the parent field.

Private Repository Limits

Free GitHub accounts have limits on the number of private repositories and collaborators. Check your plan limits before creating private repositories.

Branch Protection Rules

Protected branches cannot be deleted through the API. You must first remove branch protection rules before attempting to delete a branch.

Repository Transfer Requirements

To transfer a repository, the target user or organization must have sufficient permissions and repository limits available.