feat: github app token management

[hminaee-tc]

GitHub App Token Management

Overview

This PR introduces a comprehensive GitHub App Token Generator package that provides JWT token generation, installation access token management, and GitHub API integration with full test coverage and professional tooling.

features added

🔐 Token Operations
✅ Generate JWT tokens from GitHub App credentials
✅ Generate installation access tokens for specific organizations or installations
✅ Validate existing tokens - Check if tokens are valid and active
✅ Revoke installation tokens - Invalidate tokens

📋 Installation Management
✅ List all installations - Show where the GitHub App is installed
✅ Show installation details - Organization/user information for each installation/ repos the app is installed on
✅ Find installation by organization - Get installation ID from org name and generate token (or do the same with directly use inst token)

🔍 App Analysis & Information
✅ Analyze GitHub App - Comprehensive app details, permissions, and capabilities
✅ Get app information - Basic app metadata and configuration
✅ Show installation statistics - Repository access and permission details

🛠 Authentication Methods
✅ Private key file authentication - --private-key-path bot.pem
✅ Raw private key authentication - --private-key "-----BEGIN RSA..."
✅ Environment variable support - APP_ID, PRIVATE_KEY_PATH, PRIVATE_KEY

🎯 Token Generation Options
✅ Generate by organization name
✅ Generate by installation ID
✅ JWT token generation - For GitHub App API authentication

🐛 Development & Debug Tools
✅ Debug logging - --debug flag for troubleshooting
✅ Help system - --help for usage guidance
✅ Force operations - --force to skip confirmations

[Copilot]

Pull Request Overview

This PR adds a complete GitHub App Token Generator package with JWT generation, installation token management, API client integration, CLI tooling, configuration management, and full test fixtures.

• Introduces TokenManager for validate/revoke/list/generate/analyze operations
• Implements GitHubAPIClient for all GitHub App API calls
• Adds CLI (cli.py), configuration (config.py), formatting (formatters.py), authentication (auth.py), and test fixtures

Reviewed Changes

Copilot reviewed 19 out of 25 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/conftest.py	Added common pytest fixtures for API responses
github_app_token_generator/token_manager.py	Core token operations (validate, revoke, list, generate, analyze)
github_app_token_generator/github_api.py	HTTP client for GitHub App endpoints
github_app_token_generator/formatters.py	CLI output formatting and coloring utilities
github_app_token_generator/cli.py	Argument parser and usage banner
github_app_token_generator/config.py	Environment/CLI config loading and validation
github_app_token_generator/auth.py	JWT generation and private key handling
github_app_token_generator/main.py	Entry point wiring CLI → token manager
README.md	Project overview and navigation

[aosagie-tc]

Testing result :

• Command : github-app-token-generator --app-id 1431365
• Result :

2025-06-19 21:11:53,886 - cpk_lib_python_github.github_app_token_generator_package.github_app_token_generator.config - ERROR - Private key is required for this operation. Set PRIVATE_KEY or PRIVATE_KEY_PATH environment variable or use --private-key/--private-key-path
Traceback (most recent call last):
  File "/Users/deji/work/automations/repo-transfer-from-one-org-to-another/venv/bin/github-app-token-generator", line 8, in <module>
    sys.exit(main())
             ~~~~^^
  File "/Users/deji/work/automations/repo-transfer-from-one-org-to-another/venv/lib/python3.13/site-packages/cpk_lib_python_github/github_app_token_generator_package/github_app_token_generator/main.py", line 40, in main
    config = get_config_from_env(args)
  File "/Users/deji/work/automations/repo-transfer-from-one-org-to-another/venv/lib/python3.13/site-packages/cpk_lib_python_github/github_app_token_generator_package/github_app_token_generator/config.py", line 90, in get_config_from_env
    raise ValueError(
    ...<3 lines>...
    )
ValueError: Private key is required for this operation. Set PRIVATE_KEY or PRIVATE_KEY_PATH environment variable or use --private-key/--private-key-path

• Recommendation: Stack trace should not be printed out

[aosagie-tc]

Command : github-app-token-generator --app-id 1431365 --private-key "$(cat ice-test-app-token-generator.2025-06-19.private-key.pem)" --analyze-app

Recommendation: Total Installations: 1 but it currently on new line

[aosagie-tc]

command: github-app-token-generator --help

Result :

A powerful CLI tool for generating, managing,
and analyzing GitHub App tokens

usage: github-app-token-generator [-h] [--app-id ID] [--private-key-path PATH | --private-key KEY_CONTENT] [--org ORG] [--installation-id ID] [--list-installations]
                                  [--analyze-app] [--validate-token TOKEN] [--revoke-token TOKEN] [--force] [--debug]

Generate and manage GitHub App installation tokens

options:
  -h, --help            show this help message and exit
  --app-id ID           GitHub App ID (or set APP_ID env var)
  --private-key-path PATH
                        Path to private key file
  --private-key KEY_CONTENT
                        Private key content directly
  --org ORG             Organization name to get token for
  --installation-id ID  Installation ID (if known)
  --list-installations  List all installations
  --analyze-app         Analyze GitHub App details
  --validate-token TOKEN
                        Validate an existing token
  --revoke-token TOKEN  Revoke an existing token
  --force               Skip confirmation prompts
  --debug               Enable debug logging

Recommendations: --app-id and --private-key or --private-key-path is compulsory and not optional.