GitHub Issues to Audit Report

A bash script that fetches all open issues from a GitHub repository and formats them into a structured markdown file for audit reports.

Features

• Fetches all open issues from any public or private GitHub repository
• Formats issues into a structured markdown format
• Includes issue metadata (status, creation date, labels)
• Automatically retrieves and includes all comments for each issue
• Supports pagination for repositories with many issues
• Pretty console output with color-coded messages

Prerequisites

The script requires the following dependencies:

• Bash (comes pre-installed on most Unix-based systems)
• curl (HTTP client for making API requests)
• jq (command-line JSON processor)
• Optional: GitHub CLI (gh) for token-free authentication

Installing Dependencies

macOS:

brew install curl jq
# Optional: GitHub CLI
brew install gh

Ubuntu/Debian:

sudo apt-get install curl jq
# Optional: GitHub CLI
sudo apt-add-repository -y ppa:git-core/ppa
sudo apt update
sudo apt install gh

CentOS/RHEL:

sudo yum install curl jq
# Optional: GitHub CLI installation (see GitHub docs)

Setup

1. Clone this repository or download the github_issues.sh script

2. Make the script executable:

   chmod +x github_issues.sh

3. Generate a GitHub Personal Access Token (recommended):

   • Go to GitHub Settings > Developer Settings > Personal Access Tokens
   • Create a new token with at least repo scope
   • Save the token securely

Usage

./github_issues.sh <owner> <repo> [github_token] [output_file]

Parameters

• owner: GitHub repository owner/organization (required)
• repo: GitHub repository name (required)
• github_token: GitHub personal access token (optional but recommended)
• output_file: Output markdown file name (optional, default: github_issues.md)

Examples

# Basic usage (public repositories)
./github_issues.sh 33Audits some-repo

# Using a GitHub token (recommended, required for private repos)
./github_issues.sh 33Audits some-repo ghp_xxxxxxxxxxxx

# Specifying an output file
./github_issues.sh 33Audits some-repo ghp_xxxxxxxxxxxx some-repo_issues.md

Authentication Methods

1. Direct token method (recommended for scripts/automation):

   ./github_issues.sh owner repo ghp_xxxxxxxxxxxx

2. GitHub CLI method (convenient for personal use):

   • First login with GitHub CLI:

     gh auth login

   • Then run the script without token:

     ./github_issues.sh owner repo

Output Format

The script generates a markdown file with issues formatted like this:

## Issue #123: Sample Issue Title

**Status:** OPEN
**Created:** 2023-01-01T12:34:56Z
**Labels:** bug,critical
**URL:** https://github.com/owner/repo/issues/123

**Title:** Sample Issue Title

**Description:** Issue description text goes here...

**Impact:** Not specified

**Proof of Concept:** Not specified

**Recommendation:** Not specified

**Resolution:** Not specified

**Comments:**
*Comment 1 by username on 2023-01-02T10:11:12Z:*
Comment text goes here...

Troubleshooting

• Rate limit exceeded: Use a GitHub token to increase your API rate limit
• Repository not found: Check the owner/repo names and ensure you have access
• Access forbidden: Check your token permissions or GitHub access rights
• Missing required tools: Install the required dependencies as shown above