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

> Learn how to create issue reports automatically for the iptv-org/iptv repository. Discover the built-in command for scanning classifying and structuring stream request statuses.

- Repository: [iptv-org/iptv](https://github.com/iptv-org/iptv)
- Tags: how-to-guide
- Published: 2026-02-25

---

**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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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.

```bash

# 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`](https://github.com/iptv-org/iptv/blob/main/.github/workflows/update.yml). This ensures maintainers receive updated issue status without manual intervention.

```yaml
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`](https://github.com/iptv-org/iptv/blob/main/.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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/report/create.ts) | Core command implementation that orchestrates issue loading, validation, and table generation |
| [`tests/commands/report/create.test.ts`](https://github.com/iptv-org/iptv/blob/main/tests/commands/report/create.test.ts) | Unit tests verifying report output format and status assignment logic |
| [`.github/ISSUE_TEMPLATE/3_streams_report.yml`](https://github.com/iptv-org/iptv/blob/main/.github/ISSUE_TEMPLATE/3_streams_report.yml) | Issue form template defining required fields for stream reports |
| [`.github/workflows/update.yml`](https://github.com/iptv-org/iptv/blob/main/.github/workflows/update.yml) | GitHub Actions workflow scheduling daily report generation |
| [`CONTRIBUTING.md`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/.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`](https://github.com/iptv-org/iptv/blob/main/.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`](https://github.com/iptv-org/iptv/blob/main/.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`](https://github.com/iptv-org/iptv/blob/main/.github/ISSUE_TEMPLATE/3_streams_report.yml) template incorrectly.