Day 8 | Advanced Shell Script that lists GitHub Users with GitHub API Integration

Generally, In an organization to list users or collaborators with access or revoke access of a particular user from a specific GitHub repository, the procedure using the UI is as follows:

1. Navigate to the GitHub repository in the organization.

2. Click on the "Settings" tab located at the right end of the menu bar.

3. In the left sidebar, select "Access" or "Manage access" to view the list of users and teams with permissions.

4. Here the list of collaborators, teams, and their access levels (e.g., read, write, admin) are displayed.

5. To add or remove collaborators, use the "Invite a collaborator" or "Remove" button, respectively.

This procedure allows organizations to manage and view repository access via the GitHub UI. Since this is a herculean task, it is better to automate the same with a shell script.

Creating a shell script to automate the list of GitHub Users

1. I have created an EC2 instance, ubuntu-free tier, and updated the instance using "sudo apt update" and connected to it using

   "ssh -i keypar.pem ubuntu@publicipaddress" .

1. Verify if Git is installed or not using "git --version"

1. copy the code https code from GitHub to clone as shown below (in this case I have forked a public repository of Abhishek Veeramalla)

1. Use the "git clone" command and paste the copied https link here to clone the project.

1. After cloning navigate to the "github-api" folder.

1. change the permissions of the file using "chmod ___". and the run the command.

1. Here in my case, I ran through an error that said " jq: command not found"

{
  "name": "John Doe",
  "age": 30,
  "city": "New York"
}

jq can be used to extract the value of the "name" field like this:

You can use jq to extract the value of the "name" field like this:

bashCopy codecat data.json | jq .name

The output will be:

arduinoCopy code"John Doe"

In this example, jq .name tells jq to extract the "name" field from the JSON object. It's a handy tool for filtering and transforming JSON data within your shell scripts.

1. Install jq parser using "sudo apt install jq -y".

1. Then run the script "./list-users.sh (arg1) (arg2).

In my case, as I have no list of users it didn't display any users.

BREAKDOWN of the Code:

#!/bin/bash


#####################
# Author: Sarat & Abhishek
# Version: v1
# Date: 1st-Nov
# Description: This script lists users with read access to a GitHub repository of a specified organization. 
# It uses the GitHub API and requires a GitHub username and personal access token for authentication.
#########################

# GitHub API URL
API_URL="https://api.github.com"

# GitHub username and personal access token
USERNAME=$username
TOKEN=$token

# Function to make a GET request to the GitHub API
function github_api_get {
    local endpoint="$1"
    local url="${API_URL}/${endpoint}"

    # Send a GET request to the GitHub API with authentication
    curl -s -u "${USERNAME}:${TOKEN}" "$url"
}

# Function to list users with read access to the repository
function list_users_with_read_access {
    local endpoint="repos/${REPO_OWNER}/${REPO_NAME}/collaborators"

    # Fetch the list of collaborators on the repository
    collaborators="$(github_api_get "$endpoint" | jq -r '.[] | select(.permissions.pull == true) | .login')"

    # Display the list of collaborators with read access
    if [[ -z "$collaborators" ]]; then
        echo "No users with read access found for ${REPO_OWNER}/${REPO_NAME}."
    else
        echo "Users with read access to ${REPO_OWNER}/${REPO_NAME}:"
        echo "$collaborators"
    fi
}

# Helper function to check and handle command-line arguments
function check_arguments {
    if [ $# -ne 2 ]; then
        echo "Usage: $0 <organization> <repository>"
        exit 1
    fi
}

# Main script
check_arguments "$@"
REPO_OWNER=$1
REPO_NAME=$2

echo "Listing users with read access to ${REPO_OWNER}/${REPO_NAME}..."
list_users_with_read_acces

I have created a helper function when a user runs the script without arguments, it helps the user to mention the arguments.

1. GitHub API Setup: The script interacts with the GitHub API to retrieve information about the repository's collaborators. It requires authentication using a GitHub username and a personal access token.

2. Function for Making API Requests: The script defines a function named github_api_get. This function takes an API endpoint as its parameter, constructs the API URL, and makes a GET request to the GitHub API. This is how it communicates with GitHub's servers.

3. Listing Users with Read Access: Another function, list_users_with_read_access, is responsible for listing users with read access. It queries the GitHub API to fetch the list of collaborators. It filters this list to include only those with "pull" (read) permissions and extracts their usernames.

4. Command-line Arguments Handling: A helper function, check_arguments, ensures that the script is provided with the necessary command-line arguments, specifically the organization name and repository name.

5. Executing the Script: In the main script section, check_arguments is called to verify the command-line arguments. Then, the organization name and repository name are assigned based on these arguments.

6. Results Display: Finally, the script displays the list of users with read access to the specified repository. If no such users are found, it provides an appropriate message.

By executing this script with the organization and repository as arguments, we can easily identify who has read access to a particular GitHub repository. The script leverages GitHub's API, providing a useful automation tool for GitHub repository management.