Repositories

Learn and practice the functionalities of repositories in the GitHub API.

We'll cover the following

Overview

Repositories are containers where the complete project and its files are presented on GitHub. In addition, the files’ versions also exist in that repository. The owner of the repository can be the person themselves or anyone they would like to share the ownership with. We can create branches inside a repository where each type of file can be isolated from another.

Create a repository

Instead of actually moving to the website and manually creating the repository, the HTTP POST method creates a repository. Let’s try creating it by using the API in the code below. Please provide the repository name in the widget below against the REPOSITORY key. It'll be replaced in the code in line 9.

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
url = 'https://api.github.com/user/repos'
data = json.dumps({
    'name': '{{REPOSITORY}}'
})
response = requests.post(url, headers=headers, data=data)
print(json.dumps(response.json(), indent=4))

The HTTP response of the above code can be the following:

  • 201: The repository has been created.
  • 403: It is forbidden for the repository to be created.
  • 422: The validation of the code above has failed.

The other parameters of this endpoint are explained below:

Parameters of creating a repository

Name

Type

Present In

Description

name

string

body

This is the repository’s name.

description

string

body

This is the repository’s description.

homepage

string

body

This is the repository’s information URL.

private

boolean

body

This is true if the repository is private.

visibility

string

body

This indicates whether a repository is private or public.

has_issues

boolean

body

This is true if issues are enabled and false if issues are disabled.

has_projects

boolean

body

This is true if projects are enabled and false if projects are disabled.

has_wiki

boolean

body

This is true if wiki is enabled and false if wiki is disabled.

is_template

boolean

body

This is true if the repository can be made as a template repository and false if it can’t be.

auto_init

boolean

body

This is true if we want to make a commit on an empty README file.

gitignore_template

string

body

This is the name of the template required for the desired platform or language.

license_template

string

body

This is any suitable license template.

allow_squash_merge

boolean

body

This is true if squash merge is enabled and false if squash merge is disabled.

allow_merge_commit

boolean

body

This is true if merge commit is enabled and false if merge commit is disabled.

allow_rebase_merge

boolean

body

This is true if rebase merge is enabled and false if rebase merge is disabled.

allow_auto_merge

boolean

body

This is true if auto merge is enabled and false if auto merge is disabled.

delete_branch_on_merge

boolean

body

This is true if the delete branch on merge is enabled and false if the delete branch on merge is disabled.

List repositories

Let's see how we can list the public repositories of the specified user using the HTTP GET method. The username parameter in line 6 specifies the user for which we list the repositories.

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
url = "https://api.github.com/users/<username>/repos"
response = requests.get(url, headers=headers)
print(json.dumps(response.json(), indent=4))

The output parameters of the endpoint above are the same as creating a repository. The HTTP response of the code above can be 200, which specifies that the repositories have been successfully listed.

    Update a repository

    Once a repository has been created, it doesn’t mean that we can't make changes to it. We can update anything we require whether it's adding new files, deleting them, or any other update. This endpoint uses the HTTP PATCH method.

    Let's try to update the name of the repository we just created. Please specify the new name of the repository in line 7.

    Press + to interact
    headers = {
        'Authorization': 'token {{ACCESS_TOKEN}}',
        'Accept': 'application/vnd.github.v3+json'
    }
    data = json.dumps({
        'name': '<repository-new-name>'
    })
    url = "https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}"
    response = requests.patch(url, headers=headers, data=data)
    print(json.dumps(response.json(), indent=4))

    The HTTP response of the code above can be the following:

    • 200: The repository has been successfully updated.
    • 307: There has been a temporary redirection.
    • 403: It's forbidden for the repository to be updated.
    • 404: The repository to be updated was not found.
    • 422: The validation of the code above has failed.

    Most of the parameters of the update endpoint are the same as for creating the repository. There are some more parameters that can be updated. These are listed below.

    Additional parameters for updating a repository

    Name

    Type

    Present In

    Description

    security_and_analysis

    object or null

    body

    This passes the suitable security project, if required.

    default_branch

    string

    body

    The default branch of the repository is updated.

    archived

    boolean

    body

    This is true if the archiving of the repository is enabled and false if disabled.

    allow_forking

    boolean

    body

    This is true if forking is enabled and false if disabled.

    Delete a repository

    Users with admin privileges can delete a repository. A user without admin permission will get a 403 error. This endpoint uses the DELETE method of HTTP requests.

    The HTTP response of deleting a repository can be the following:

    • 204: The repository is deleted successfully.
    • 307: There has been a temporary redirection.
    • 404: The repository we were looking for was not found.

    Press + to interact
    headers = {
        'Authorization': 'token {{ACCESS_TOKEN}}',
        'Accept': 'application/vnd.github.v3+json'
    }
    url = 'https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}'
    response = requests.delete(url, headers=headers)
    if response.status_code == 204:
        print('The repository was deleted successfully.')
    elif response.status_code == 307:
        print('There has been a redirect temporarily.')
    else:
        print('The repository we were looking for was not found.')