How to Check Who Has Read Access in Your GitHub Repositories

Introduction

Managing repository access is a crucial part of maintaining security and collaboration in GitHub. Whether you're an open-source maintainer or a DevOps engineer, knowing who has access to your repositories helps ensure proper permissions are in place.

In this blog post, we’ll explore a Bash script that uses the GitHub API to list all users with read (pull) access to a given repository.

---

Why This Script is Useful

1. Audit Repository Access – Quickly check who can view your private or public repositories.

2. Security Compliance – Ensure only authorized users have access.

3. Automate Permission Checks – Useful for CI/CD pipelines or automated security scans.

---

How the Script Works

The script performs the following steps:

1. Authenticates with GitHub API using a personal access token.

2. Takes a repository owner and name as input.

3. Fetches collaborators via GitHub’s API.

4. Filters users with read (pull) access using jq.

5. Displays the results in a clean format.

---

Breaking Down the Script

1. GitHub API Setup

The script starts by defining the GitHub API URL and authenticating using:

• USERNAME (GitHub username)

• TOKEN (GitHub personal access token)

These are passed as environment variables for security.

API_URL="https://api.github.com"
USERNAME=$username
TOKEN=$token

---

2. Fetching Collaborators

The function github_api_get makes an authenticated curl request to GitHub’s API:

function github_api_get {
    local endpoint="$1"
    local url="${API_URL}/${endpoint}"
    curl -s -u "${USERNAME}:${TOKEN}" "$url"
}

• -s silences unnecessary output.

• -u "${USERNAME}:${TOKEN}" provides Basic Auth for API access.

---

3. Filtering Users with Read Access

The script checks collaborators and filters those with pull (read) permissions using jq:

collaborators="$(github_api_get "$endpoint" | jq -r '.[] | select(.permissions.pull == true) | .login')"

• jq processes JSON output.

• select(.permissions.pull == true) keeps only users with read access.

• .login extracts their GitHub usernames.

---

4. Handling Input & Errors

A helper function ensures correct usage:

function helper {
    expected_cmd_args=2
    if [ $# -ne $expected_cmd_args ]; then
        echo "Usage: $0 <repo_owner> <repo_name>"
        exit 1
    fi
}

• Checks if both <repo_owner> and <repo_name> are provided.

• Exits with an error if arguments are missing.

---

Running the Script

Prerequisites

• Bash (Linux/macOS/WSL)

• curl (for API requests)

• jq (for JSON parsing)

Install jq if missing:

sudo apt-get install jq  # Debian/Ubuntu
brew install jq          # macOS

---

Step 1: Set GitHub Credentials

Store your GitHub username and token as environment variables:

export username="your_github_username"
export token="ghp_your_personal_access_token"

⚠️ Security Note: Never hardcode tokens in scripts! Use environment variables or secret managers.

---

Step 2: Execute the Script

./list-users.sh octocat Hello-World

Example Output:

Users with read access to octocat/Hello-World:
user1
user2
contributor-x

If no users have read access:

No users with read access found for octocat/Hello-World.

---

Possible Enhancements

1. Export to CSV/JSON – Modify the script to save results in a file.

2. Check Multiple Repos – Accept a list of repositories for batch processing.

3. Slack/Email Alerts – Integrate with notification systems for access changes.

4. GitHub Actions Integration – Run this script in a workflow for automated audits.

---

Conclusion

This script provides a quick, automated way to audit GitHub repository access. It’s useful for:

• Open-source maintainers managing contributors.

• DevOps teams enforcing security policies.

• Developers checking their own repo permissions.

By integrating this into your workflow, you can ensure better access control and reduce security risks.

---

Try It Yourself!

🔗 Get the full script here

Would you like any improvements or additional features? Let me know in the comments! 🚀

---

Happy Coding! 🎉