How to Create Issue Reports Automatically in IPTV-ORG/IPTV

The IPTV-ORG/IPTV repository provides a built-in command that scans open GitHub issues, classifies them by label, and generates a structured table showing the status of each stream request.

Managing thousands of stream requests manually is unsustainable for large IPTV repositories. The iptv-org/iptv project solves this by providing an automated reporting command that validates issue data against the current playlist state. This guide explains how to create issue reports automatically using the built-in tooling found in scripts/commands/report/create.ts.

Understanding the Automatic Issue Report Architecture

The reporting system follows a multi-stage pipeline defined in scripts/commands/report/create.ts. It integrates with the GitHub API and local playlist data to produce actionable reports.

Issue Loading and Data Preparation

The IssueLoader class fetches every open issue from the GitHub API. Simultaneously, the command calls loadData() to retrieve the latest channel definitions and block-list entries from the internal API. This ensures the report reflects the current repository state.

Playlist Parsing and Request Filtering

The PlaylistParser processes all .m3u files located in the STREAMS_DIR directory, creating a collection of Stream objects indexed by URL, channel, and stream ID. The system then filters issues by their GitHub labels: streams:add, streams:remove, streams:edit, and channel search.

Validation and Status Assignment

For each filtered request, the script performs rigorous validation:

• Verifies required fields (stream_id, stream_url) exist
• Validates URL format using isURI
• Checks against block-lists and closed channels
• Detects duplicate URLs already in the playlist or duplicate requests within the same batch
• Validates channel ID existence

Results are stored in a status enum (e.g., pending, invalid_channel_id, duplicate_link, channel_blocked).

How to Run the Report Command Locally

To create issue reports automatically on your local machine, execute the npm script with the appropriate environment variables pointing to your data directories.

# Configure paths to test fixtures or production data

export DATA_DIR=tests/__data__/input/data
export STREAMS_DIR=tests/__data__/input/report_create

# Execute the report generation command

npm run report:create

The command outputs a structured table via console.table, displaying each issue's number, type, stream ID, URL, and validation status:

┌─────────┬─────────────┬──────────────────┬───────────────────────────────┬───────────────────────────────────────────────┬──────────────────────┐
│ (index) │ issueNumber │ type             │ streamId                      │ streamUrl                                     │ status               │
├─────────┼─────────────┼──────────────────┼───────────────────────────────┼───────────────────────────────────────────────┼──────────────────────┤
│ 0       │ 14120       │ 'streams:edit'   │ 'boo.us'                      │ 'https://livestream.telvue.com/...'           │ 'invalid_channel_id' │
│ 1       │ 14135       │ 'streams:add'    │ 'BBCWorldNews.uk@SouthAsia'   │ 'http://103.199.161.254/...'                  │ 'invalid_channel_id' │
└─────────┴─────────────┴──────────────────┴───────────────────────────────┴───────────────────────────────────────────────┴──────────────────────┘

Automating Reports in CI/CD Workflows

The repository integrates automatic report generation into its daily maintenance workflow via .github/workflows/update.yml. This ensures maintainers receive updated issue status without manual intervention.

on:
  schedule:
    - cron: '0 0 * * *'   # daily at midnight UTC

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: npm ci
      - name: Generate issue report
        run: npm run report:create

The workflow executes npm run report:create, capturing the output for downstream automation steps such as auto-merging approved streams:add requests or notifying maintainers of blocked streams.

Issue Templates and Required Fields

For the automatic reporting system to function correctly, contributors must use the structured issue template defined in .github/ISSUE_TEMPLATE/3_streams_report.yml. This template enforces the presence of:

• stream_url – The URL of the stream being reported
• stream_id – The channel identifier (optional but recommended)

When users submit issues using this template, the scripts/commands/report/create.ts command can extract and validate the fields against the current playlist data, assigning appropriate statuses like nonexistent_link or duplicate_link.

Key Implementation Files

File	Purpose
scripts/commands/report/create.ts	Core command implementation that orchestrates issue loading, validation, and table generation
tests/commands/report/create.test.ts	Unit tests verifying report output format and status assignment logic
.github/ISSUE_TEMPLATE/3_streams_report.yml	Issue form template defining required fields for stream reports
.github/workflows/update.yml	GitHub Actions workflow scheduling daily report generation
CONTRIBUTING.md	Contributor guidelines explaining the automated reporting process

These components together enable automatic issue reporting, giving maintainers an up‑to‑date overview of all stream‑related requests without manual triage.

Summary

• The IPTV-ORG/IPTV repository provides a built-in command at scripts/commands/report/create.ts to create issue reports automatically.
• The system uses IssueLoader and PlaylistParser to fetch GitHub issues and parse local .m3u files, then validates requests against block-lists and duplicate checks.
• Run the report locally using npm run report:create with DATA_DIR and STREAMS_DIR environment variables set.
• The .github/workflows/update.yml workflow automates daily report generation, enabling maintainers to process stream requests efficiently.
• Contributors must use the .github/ISSUE_TEMPLATE/3_streams_report.yml template to ensure the automation can extract stream_url and stream_id fields.

Frequently Asked Questions

How does the automatic issue report command classify GitHub issues?

The command filters open issues by their GitHub labels—specifically streams:add, streams:remove, streams:edit, and channel search—then validates each issue's data against the current playlist and block-list to assign statuses like pending, duplicate_link, or invalid_channel_id.

What environment variables are required to run the report locally?

You must set DATA_DIR to point to the directory containing channel and block-list data, and STREAMS_DIR to the directory containing .m3u playlist files. For example: export DATA_DIR=tests/__data__/input/data and export STREAMS_DIR=tests/__data__/input/report_create.

Can the report generation be integrated into custom CI/CD pipelines?

Yes, the repository provides the npm run report:create command which can be executed in any CI environment. The official workflow in .github/workflows/update.yml demonstrates running this command on a daily schedule using GitHub Actions, but you can adapt the same command for Jenkins, GitLab CI, or other platforms.

What happens if an issue is missing required fields like stream_url?

If an issue lacks the required stream_url or contains an invalid stream_id, the report command assigns a status such as invalid_stream_url or invalid_channel_id. These entries appear in the generated table, allowing maintainers to identify and request corrections from contributors who used the .github/ISSUE_TEMPLATE/3_streams_report.yml template incorrectly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}