Use GitHub REST API v3 to do administration tasks within a GitHub organisation. The main aim of this project is prevent accidental access loss to organisation repositories when individuals leave the organisation by programatically adding, and setting team permissions across multiple repositories.

ℹ️ Where this documentation refers to the root folder we mean where this README.md is located.

⚠️ You can only complete tasks where your GitHub username has organisation owner and/or repository administrator privileges.

❗️ Some actions, such as setting team permissions can be destructive. Take care when using them!

To get started, make sure your system meets the requirements, and you have set up all secrets, and credentials.

This project heavily leverages the PyGithub package, and has wrapped functions around different methods. The advantage of these wrapped functions is that they leverage multiprocessing to speed up the API requests, as well as providing convenience functions for GitHub organisation administration.

All functions can be imported directly from the src package, and documentation is available in the Reference section of the Sphinx documentation.

The functions can:

• Find all repositories in a GitHub organisation (src.find_organisation_repos)
• Get information from a PyGithub single repositories (src.get_items_for_repo)
• Get information from a PyGithub paginated list of repositories (src.get_items_for_all_repos)
• Extract a specific attribute from a PyGithub paginated list of information (src.extract_attribute_from_dict_of_paginated_lists)

Here is an example of getting the names of all contributors across all organisation repositories:

⚠️ Note that, because the name attribute is not in the API response for getting repository contributors, PyGithub will send another API GET request for each contributor to obtain their name! This may quickly exceed the API rate limit for large organisations.

from github import Github
from src import extract_attribute_from_dict_of_paginated_lists, find_organisation_repos, get_items_for_all_repos
import os

# Instantiate the github.Github class to gain access to GitHub REST APIv3 via your GitHub personal access token
g = Github(os.getenv("GITHUB_API_KEY"), per_page=100)

# Get all the repositories for your GitHub organisation
organisation_repositories = find_organisation_repos(g, os.getenv("GITHUB_ORGANISATION"))

# Get all the contributors for these repositories
organisation_contributors = get_items_for_all_repos(g, "get_contributors", organisation_repositories)

# Show the contributors names in each repository
extract_attribute_from_dict_of_paginated_lists(organisation_contributors, "name")

For more information, see the example notebooks in the notebooks folder.

• A .secrets file with the required secrets and credentials
• Load environment variables from .envrc
• Python 3.8 or later with a virtual environment set up
• All packages from requirements.txt installed in your environment
  • For ease, open your terminal and run the Make command make requirements, which will install package requirements as well as pre-commit hooks to prevent committing of secrets, Jupyter notebook outputs, and large files

To run this project, you need a .secrets file with secrets/credentials as environmental variables; see the documentation for further guidance. The secrets/credentials should have the following environment variable name(s):

Once you've added these environment variables to .secrets you will need to load them via .envrc.

To build the documentation locally, open your Terminal, and enter the following command:

make docs

You can then access the documentation by opening docs/_build/index.html in your preferred web browser.

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation. The documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.

If you want to help us build, and improve GitHub Organisation Administration, view our contributing guidelines.

This project structure is based on the govcookiecutter template project.