Managing access control for GitHub repositories can become cumbersome, especially when dealing with multiple collaborators. This project aims to simplify the process by using a Bash script integrated with the GitHub API. By the end of this project, you will have a script that lists all users with access to a specified repository.
Objectives
Automate Access Management: Use a Bash script to automate managing access to GitHub repositories.
Integrate GitHub API: Leverage GitHub API to fetch and list collaborators of a repository.
Develop a Secure Script: Ensure the script handles sensitive information like access tokens securely.
Prerequisites
Before you begin, ensure you have the following:
Basic Knowledge of Bash Scripting: Understanding of how to write and execute Bash scripts.
GitHub Account: A GitHub account with repositories that you want to manage.
GitHub Personal Access Token: A token that grants API access to your GitHub account.
Step-by-Step Guide
1. Set Up the Environment
First, set up an EC2 instance with Ubuntu and connect to it via SSH. Update the package list and install necessary tools like jq for JSON parsing:
sudo apt-get update
sudo apt-get install jq
2. Create a Personal Access Token
Navigate to GitHub Settings > Developer settings > Personal access tokens to generate a token with the appropriate scopes, such as repo to access repository data.
3. Write the Bash Script
Create and edit a file named list-users.sh:
vim list-users.sh
Add the following content to your script:
#!/bin/bash
################################
# Author : Nishank
# Date : 01/06/24
#
# This script is responsible for listing the users who have access to a repository you own.
################################
# GitHub API URL
API_URL="https://api.github.com"
# GitHub Username and Personal Access Token
GITHUB_USERNAME="Enter your username here"
GITHUB_TOKEN="Enter your token value here"
# User and Repository information
REPO_OWNER=$1
REPO_NAME=$2
# Check if the required arguments are provided
if [ -z "$REPO_OWNER" ] || [ -z "$REPO_NAME" ]; then
echo "Usage: $0 <Repo_Owner> <Repo_Name>"
exit 1
fi
# Make the GET request to fetch collaborators
RESPONSE=$(curl -s -H "Authorization: token $GITHUB_TOKEN" "$API_URL/repos/$REPO_OWNER/$REPO_NAME/collaborators")
# Check if the response is empty or contains an error
if [ -z "$RESPONSE" ]; then
echo "Failed to fetch collaborators or no collaborators found."
exit 1
fi
# Parse and display the list of collaborators
echo "Collaborators for repository $REPO_OWNER/$REPO_NAME:"
echo "$RESPONSE" | jq -r '.[].login'
4. Explanation of the Script
Metadata
The script begins with a comment block that includes the author's name and the date. This is useful for documentation purposes and helps others understand who wrote the script and when.
API URL
The API_URL variable stores the base URL for the GitHub API. This will be used in our API requests.
Credentials
The GITHUB_USERNAME and GITHUB_TOKEN variables store your GitHub username and personal access token, respectively. These are necessary for authenticating API requests. Make sure to keep your token secure and not expose it publicly.
Arguments
The script accepts two command-line arguments: REPO_OWNER and REPO_NAME. These represent the repository's owner and the repository's name, respectively.
Argument Check
Before making any API requests, the script checks if the required arguments are provided. If not, it displays a usage message and exits.
if [ -z "$REPO_OWNER" ] || [ -z "$REPO_NAME" ]; then
echo "Usage: $0 <Repo_Owner> <Repo_Name>"
exit 1
fi
This ensures the script is used correctly and prevents errors caused by missing arguments.
GET Request
The script makes a GET request to the GitHub API to fetch the list of collaborators for the specified repository. The request is authenticated using the personal access token.
RESPONSE=$(curl -s -H "Authorization: token $GITHUB_TOKEN" "$API_URL/repos/$REPO_OWNER/$REPO_NAME/collaborators")
The curl command is used to make the request. The -s flag makes the request silent, and the -H flag adds an HTTP header for authentication.
Response Handling
The script checks if the response is empty or contains an error. If so, it displays an error message and exits.
if [ -z "$RESPONSE" ]; then
echo "Failed to fetch collaborators or no collaborators found."
exit 1
fi
This ensures the script handles errors gracefully and provides useful feedback to the user.
Output
The script uses the jq tool to parse the JSON response and display the list of collaborator usernames.
echo "Collaborators for repository $REPO_OWNER/$REPO_NAME:"
echo "$RESPONSE" | jq -r '.[].login'
The jq command extracts the login field from each collaborator object in the response and prints it. The -r flag ensures the output is raw and not wrapped in quotes.
5. Run the Script
Make the script executable:
chmod u+x list-users.sh
Execute the script with the repository owner and name as arguments:
./list-users.sh <Repo_Owner> <Repo_Name>
For example:
./list-users.sh nishankkoul StudentDBMS
6. Security Considerations
Note: Ensure you do not expose your GitHub personal access token. Remove it from the script before sharing or storing it in a public repository. Use environment variables or secure storage methods to manage sensitive information.
Conclusion
This project demonstrates how to automate GitHub repository access management using a Bash script and the GitHub API. By integrating these tools, you can efficiently manage collaborators across multiple repositories, enhancing your workflow and security.
For more details on the GitHub API, refer to the GitHub API documentation.