https://github.com/psilore/squad
Generate comprehensive reports about GitHub organizations and teams, including repositories, Dependabot alerts, pull requests, and team members.
https://github.com/psilore/squad
devops devops-tools markdown report squad team
Last synced: 3 months ago
JSON representation
Generate comprehensive reports about GitHub organizations and teams, including repositories, Dependabot alerts, pull requests, and team members.
- Host: GitHub
- URL: https://github.com/psilore/squad
- Owner: psilore
- License: mit
- Created: 2025-12-14T16:27:39.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-12-23T06:03:23.000Z (3 months ago)
- Last Synced: 2025-12-24T20:32:35.904Z (3 months ago)
- Topics: devops, devops-tools, markdown, report, squad, team
- Language: Shell
- Homepage:
- Size: 39.1 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# squad
[](https://conventionalcommits.org)
[](https://github.com/semantic-release/semantic-release)
[](https://github.com/psilore/squad/actions/workflows/main.yml)
A GitHub Action that generates comprehensive reports about GitHub organizations and teams, including repositories, Dependabot alerts, pull requests, and team members.
## Features
- 📊 **Repository Overview** - List all repositories with visibility status and public repo warnings
- 🔒 **Security Scanning** - Analyze Dependabot alerts with CVE links and severity tracking
- 🔀 **Pull Request Tracking** - Monitor open pull requests with draft status and author info
- 👥 **Team Management** - Track team members and organization users
- 📈 **Detailed Reports** - Generate markdown reports with comprehensive statistics
- 🎯 **Flexible Targeting** - Report on entire organizations, specific teams, or individual users
- 📦 **JSON Exports** - Comprehensive team_data.json with all collected metrics
## Usage
### Basic Example
```yaml
name: Monthly Security Report
on:
schedule:
- cron: '0 0 1 * *' # First day of every month
workflow_dispatch:
jobs:
generate-report:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Generate Report
uses: psilore/squad@v1
with:
owner: 'your-organization'
github-token: ${{ secrets.GITHUB_TOKEN }}
```
### Advanced Example with Team
```yaml
- name: Generate Team Report
id: squad-report
uses: psilore/squad@v1
with:
owner: 'your-organization'
team-slug: 'engineering-team'
github-token: ${{ secrets.PAT_TOKEN }}
since-date: '2024-01-01'
until-date: '2024-12-31'
report-path: './reports'
alerts: 'true'
users: 'true'
pull-requests: 'true'
- name: Upload Report
uses: actions/upload-artifact@v4
with:
name: squad-report
path: ./reports/
```
## Inputs
| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `owner` | GitHub organization or owner name | ✅ Yes | - |
| `team-slug` | Team slug within the organization | ❌ No | `''` (entire org) |
| `github-token` | GitHub token with appropriate permissions | ✅ Yes | - |
| `since-date` | Start date for report range (YYYY-MM-DD) | ❌ No | First day of previous month |
| `until-date` | End date for report range (YYYY-MM-DD) | ❌ No | Today |
| `report-path` | Path where report will be saved | ❌ No | `./report` |
| `alerts` | Include Dependabot alerts scanning | ❌ No | `true` |
| `users` | Include user/member data collection | ❌ No | `true` |
| `pull-requests` | Include open pull requests tracking | ❌ No | `true` |
## Outputs
| Output | Description |
|--------|-------------|
| `report-path` | Path to the generated report directory |
| `total-alerts` | Total number of Dependabot alerts found |
| `critical-alerts` | Number of critical severity alerts |
| `total-repos` | Total number of repositories analyzed |
| `total-users` | Total number of users/members |
## Permissions
The GitHub token needs the following permissions:
```yaml
permissions:
contents: read
issues: read
pull-requests: read
repository-projects: read
```
For organization-level reporting, you may need a Personal Access Token (PAT) with:
- `repo` - Full control of private repositories
- `read:org` - Read org and team membership
- `read:user` - Read user profile data
## Report Contents
The generated report includes:
### Markdown Report (report_summary.md)
1. **Users Table** - Team members with avatars and GitHub profiles
2. **Repositories Table** - All repos with visibility status and public repo warnings
3. **Open Pull Requests Table** - Active PRs with status, author, and dates
4. **Vulnerabilities Table** - Dependabot alerts with CVE links and severity levels
### JSON Exports
- **team_data.json** - Comprehensive data with all metrics and summaries
- **repos.json** - Repository details with visibility information
- **users.json** - User/member data with avatars and profiles
- **prs.json** - Open pull request details
- **alerts.json** - Dependabot vulnerability data
- **public_repos.json** - List of public repositories (if any detected)
## Example Workflow with Notifications
```yaml
- name: Generate Report
id: squad
uses: psilore/squad@v1
with:
owner: 'your-org'
github-token: ${{ secrets.GITHUB_TOKEN }}
- name: Check Critical Alerts
if: steps.squad.outputs.critical-alerts > 0
run: |
echo "::warning::Found ${{ steps.squad.outputs.critical-alerts }} critical alerts!"
- name: Create Issue on Critical Alerts
if: steps.squad.outputs.critical-alerts > 0
uses: actions/github-script@v7
with:
script: |
github.rest.issues.create({
owner: context.repo.owner,
repo: context.repo.repo,
title: '🚨 Critical Security Alerts Detected',
body: `Found ${{ steps.squad.outputs.critical-alerts }} critical alerts.\n\nSee the full report in the workflow artifacts.`,
labels: ['security', 'critical']
});
```
## Local Development
### Using Make (Recommended)
The project includes a Makefile for easy development:
```bash
# View all available commands
make help
# Run all linters (Docker, YAML, Shell)
make lint
# Build the Docker image
make build
# Build and run
make run OWNER=your-org GITHUB_TOKEN=ghp_...
# Quick run without rebuilding
make quick-run OWNER=your-org GITHUB_TOKEN=ghp_...
# Run tests
make test
# Clean up
make clean
```
### Manual Commands
#### Running the Script Directly
```bash
# Set required environment variables
export OWNER="your-organization"
export TEAM_SLUG="your-team" # Optional
export GITHUB_TOKEN="ghp_yourtoken"
# Run the script
./scripts/squad.sh -o "$OWNER" -t "$TEAM_SLUG"
```
#### Building the Docker Image
```bash
docker build -t squad:latest .
```
#### Testing the Action Locally
```bash
# Method 1: Using the built image
docker run --rm \
-e GITHUB_TOKEN="$GITHUB_TOKEN" \
-e INPUT_OWNER="your-org" \
squad:test
# Method 2: Generate report in a specific directory
mkdir -p output && chmod 777 output
docker run --rm \
-e GITHUB_TOKEN="$GITHUB_TOKEN" \
-e INPUT_OWNER="your-org" \
-v $(pwd)/output:/workspace/report \
squad:test
```
### Quality Assurance
```bash
# Lint Dockerfile
make lint-docker
# Lint YAML files
make lint-yaml
# Lint shell scripts
make lint-shell
# Verify all dependencies
make verify-deps
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT License - see LICENSE file for details
## Support
If you encounter any issues or have questions, please file an issue in the GitHub repository.