action-reporting-cli

CLI to report on GitHub Actions usage across enterprises, organizations, users, and repositories

action-reporting-cli helps you audit GitHub Actions usage across your entire GitHub environment. It collects comprehensive data about workflows, actions, secrets, variables, permissions, and dependencies, giving you valuable insights into your Actions usage. The tool works with GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server.

Table of Contents

• Installation
• Authentication
• Usage
• Options
• Examples
• Report Files
• Contributing
• License

Installation

Using npx (recommended)

Run without installing:

$ npx @stoe/action-reporting-cli [--options]

Global Installation

$ npm install -g @stoe/action-reporting-cli
$ action-reporting-cli [--options]

Local Installation

$ npm install @stoe/action-reporting-cli
$ npx action-reporting-cli [--options]

Authentication

You'll need a GitHub Personal Access Token (PAT) with these permissions:

• For GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Cloud with Data Residency:

  • repo scope to access private repositories
  • workflow scope to read GitHub Actions data
  • admin:org scope when using --owner with organizations

• For GitHub Enterprise Server:

  • Same permissions as above
  • Make sure you have network access to your GitHub Enterprise Server instance

You can provide your token using the --token parameter or by setting the GITHUB_TOKEN environment variable.

Usage

You'll need to specify one target scope to analyze (enterprise, owner, or repository):

# Basic usage pattern
$ action-reporting-cli --<scope> <name> --<report-options> --<output-options>

Options

Target Scope (Required, choose one)

Option	Description	Example
--enterprise, -e	GitHub Enterprise Cloud or Server account slug	my-enterprise
--owner, -o	GitHub organization or user login. When --owner is a user, you'll get results for the authenticated user	my-org
--repository, -r	GitHub repository name with owner	my-org/my-repo

Authentication and Connection

Option	Description	Default
--token, -t	Your GitHub Personal Access Token	Environment variable GITHUB_TOKEN
--hostname	GitHub Enterprise Server hostname or GitHub Enterprise Cloud with Data Residency endpoint: - For GitHub Enterprise Server: github.example.com - For GitHub Enterprise Cloud with Data Residency: api.example.ghe.com	api.github.com

Report Content Options

Option	Description	Default	Notes
--all	Generate all report types listed below
--listeners	Report workflow on event listeners and triggers used
--permissions	Report permissions values set for GITHUB_TOKEN
--runs-on	Report runs-on runner environments used
--secrets	Report secrets referenced in workflows
--uses	Report uses statements for actions referenced
--exclude	Skip GitHub-created Actions (from github.com/actions and github.com/github)		Use with --uses
--unique	List unique GitHub Actions references	false both when used with --all	Values: true, false, or both. When true creates a .unique file with unique third-party actions. When both, creates two files: one with all actions and one with unique third-party actions.
--vars	Report vars referenced in workflows

Repository Filtering (for Enterprise/Owner Scopes)

Option	Description	Default
--archived	Skip archived repositories	false
--forked	Skip forked repositories	false

Output Format Options

Option	Description	Example
--csv	Path to save CSV output	./reports/report.csv
--json	Path to save JSON output	./reports/report.json
--md	Path to save Markdown output	./reports/report.md

Utility Options

Option	Description
--debug, -d	Enable debug mode with verbose logging
--skipCache	Disable caching of API responses (gets fresh data each time, only works with --debug)
--help, -h	Show command help and usage information
--version, -v	Display the tool's version

Report Files

The tool generates reports in your specified format(s):

• CSV: Comma-separated values that you can easily import into spreadsheets
• JSON: Structured data format for programmatic access or further processing
• Markdown: Human-readable format that's perfect for documentation or sharing

When you use --unique both with --uses, you'll get an additional file with the .unique suffix containing only unique third-party actions.

Examples

Here are some common usage scenarios to help you get started:

Enterprise-Wide Audit

Get a complete report on all GitHub Actions usage across your enterprise:

# Analyze everything in your GitHub Enterprise Cloud account
$ npx @stoe/action-reporting-cli \
  --token ghp_000000000000000000000000000000000000 \
  --enterprise my-enterprise \
  --all \
  --csv ./reports/actions.csv \
  --json ./reports/actions.json \
  --md ./reports/actions.md

Organization-Level Analysis

Focus on specific aspects of GitHub Actions in an organization:

# Check permissions, runners, secrets, actions, and variables in your org
$ npx @stoe/action-reporting-cli \
  --token ghp_000000000000000000000000000000000000 \
  --owner my-org \
  --permissions \
  --runs-on \
  --secrets \
  --uses \
  --vars \
  --json ./reports/actions.json

Repository-Specific Analysis

Find unique third-party actions used in a specific repository:

# Identify third-party actions in your repository
$ npx @stoe/action-reporting-cli \
  --token ghp_000000000000000000000000000000000000 \
  --repository my-org/my-repo \
  --uses \
  --exclude \
  --unique both \
  --csv ./reports/actions.csv

GitHub Enterprise Server

Run the tool against your GitHub Enterprise Server instance:

# Analyze an organization on GitHub Enterprise Server
$ npx @stoe/action-reporting-cli \
  --hostname github.example.com \
  --token ghp_000000000000000000000000000000000000 \
  --owner my-org \
  --all \
  --json ./reports/actions.json

Using Environment Variables

Use environment variables for authentication:

# Set your token as an environment variable
$ export GITHUB_TOKEN=ghp_000000000000000000000000000000000000

# Run without including token in the command
$ npx @stoe/action-reporting-cli \
  --owner my-org \
  --uses \
  --csv ./reports/actions.csv

Advanced Usage

Filtering Repositories

Skip archived or forked repositories in your enterprise-wide scan:

$ npx @stoe/action-reporting-cli \
  --enterprise my-enterprise \
  --all \
  --archived \
  --forked \
  --json ./reports/actions.json

Debugging Issues

Enable debug mode when you need more information:

$ npx @stoe/action-reporting-cli \
  --repository my-org/my-repo \
  --all \
  --debug \
  --md ./reports/actions.md

Getting Fresh Data

Skip the cache to get the most up-to-date information (uses more API calls, only works with --debug):

$ npx @stoe/action-reporting-cli \
  --owner my-org \
  --all \
  --skipCache \
  --json ./reports/actions.json

Performance Tips

When working with large GitHub environments:

• Use the --debug flag to monitor progress and identify any issues
• For very large enterprises, consider running separate scans for specific organizations
• Use repository filtering options (--archived and --forked) to reduce API calls or exclude unnecessary data

Contributing

We welcome and appreciate your contributions! Whether you're reporting bugs, suggesting features, or submitting code changes, your help makes this project better.

Please check out our contributing guidelines for information on:

• How to submit bug reports and feature requests
• Development workflow and coding standards
• Pull request process
• Project structure

Thank you to everyone who's contributed!

License

MIT © Stefan Stölzle