Usage Guide

This guide covers everything you need to use the RepoMetro GitHub Action.

---

Quick Start

Create .github/workflows/repometro.yml in your repository:

name: RepoMetro

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  repometro:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: kirasync/repometro@v1

RepoMetro will run on every push to main and on every pull request.

---

Inputs

Input	Required	Default	Description
output-dir	no	repometro-output	Directory for generated output files
generate-json	no	true	Generate repometro.json
generate-markdown	no	true	Generate repometro.md
generate-svg	no	true	Generate SVG visualizations (tree, languages, treemap)
pr-comment	no	true	Post a summary comment on pull requests
ignore	no	""	Comma-separated list of directories to ignore
max-file-size	no	10485760	Maximum file size to scan in bytes (default: 10MB)

Outputs

Output	Description
json-path	Absolute path to the generated repometro.json

---

Examples

Minimal (defaults)

- uses: kirasync/repometro@v1

Runs with all defaults — generates JSON, Markdown, SVG, and posts PR comments.

Disable PR Comments

- uses: kirasync/repometro@v1
  with:
    pr-comment: false

JSON Only

- uses: kirasync/repometro@v1
  with:
    generate-markdown: false
    generate-svg: false
    pr-comment: false

Custom Ignore List

- uses: kirasync/repometro@v1
  with:
    ignore: node_modules,dist,build,coverage,.cache,vendor

Larger File Size Limit

- uses: kirasync/repometro@v1
  with:
    max-file-size: 52428800  # 50MB

---

Configuration File

Instead of (or in addition to) Action inputs, you can create a repometro.yml in your repository root:

version: 1

scan:
  hidden: false

output:
  json: true
  markdown: true
  svg: true

pullRequest:
  comment: true

ignore:
  - node_modules
  - dist
  - build
  - coverage
  - .git
  - .next
  - target

limits:
  maxFileSize: 10485760  # 10MB

---

Output Files

All generated files are written to the output-dir (default: repometro-output):

File	Description
repometro.json	Machine-readable structured repository map
repometro.md	Human-readable Markdown report with tables and file tree
repometro-tree.svg	Directory tree visualization
repometro-languages.svg	Language distribution bar chart
repometro-treemap.svg	File size treemap visualization

Downloading Artifacts

The workflow uploads the output as an artifact named repometro-data. Download from the Actions tab, or use in a subsequent step:

- uses: actions/download-artifact@v4
  with:
    name: repometro-data
    path: repometro-output

---

Permissions

permissions:
  contents: read        # Required — read repository files
  pull-requests: write  # Required only if pr-comment is true

---

Triggering

RepoMetro supports these events:

Event	Use case
push	Generate maps on every commit
pull_request	Generate maps and post PR comments
schedule	Periodic repository snapshots
workflow_dispatch	Manual on-demand runs

Example with schedule:

on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sunday