# How the GitHub Actions Update Workflow Automates Playlist Maintenance in iptv-org/iptv

> Discover how the iptv-org/iptv GitHub Actions workflow automates daily playlist maintenance, stream validation, and deployment for accurate M3U playlists and API updates.

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

---

**The GitHub Actions update workflow runs daily at 00:00 UTC or on manual trigger to process approved GitHub issues, regenerate M3U playlists, validate streams, and deploy updates to GitHub Pages and a separate API repository.**

The `update` workflow defined in [`.github/workflows/update.yml`](https://github.com/iptv-org/iptv/blob/main/.github/workflows/update.yml) serves as the continuous integration backbone for the iptv-org/iptv repository. This GitHub Actions update workflow transforms community-submitted issues into structured playlist data without requiring manual file edits, ensuring the public M3U files and JSON API remain current.

## Workflow Triggers and Scheduling

The GitHub Actions update workflow initiates through two distinct mechanisms defined in the `on` block of [`.github/workflows/update.yml`](https://github.com/iptv-org/iptv/blob/main/.github/workflows/update.yml).

**Manual execution** via `workflow_dispatch` allows maintainers to trigger the pipeline immediately from the GitHub Actions tab, useful for urgent updates or testing changes.

**Automated scheduling** uses a cron expression set to `'0 0 * * *'`, executing the workflow once daily at 00:00 UTC. This ensures the playlist data remains synchronized with upstream sources on a consistent schedule.

## Job Configuration and Environment

The workflow contains a single job named `main` that runs on `ubuntu-latest`. The environment standardizes on **Node.js 22**, installed via `actions/setup-node@v6` with npm caching enabled to accelerate dependency resolution.

Authentication relies on a **GitHub App token** rather than a personal access token. The step `tibdex/github-app-token@v1.8.2` generates a short-lived token using `APP_ID` and `APP_PRIVATE_KEY` secrets, granting the workflow permission to push commits without exposing long-lived credentials.

## Step-by-Step Pipeline Execution

The GitHub Actions update workflow executes a 20-step pipeline that transforms raw issues into deployed artifacts.

### Repository Checkout and Authentication

The workflow performs two checkout operations. First, `actions/checkout@v6` retrieves the code with default permissions. After generating the GitHub App token, a second checkout occurs with the token parameter enabled, ensuring subsequent steps have write access to the repository.

### Dependency Installation

The pipeline installs project dependencies using `npm install`. This command retrieves all packages defined in [`package.json`](https://github.com/iptv-org/iptv/blob/main/package.json), including TypeScript execution environments and parsing libraries required by the custom scripts.

### Playlist Update Processing

The **critical transformation step** runs `npm run playlist:update`, which executes [`scripts/commands/playlist/update.ts`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/playlist/update.ts). This script implements the `IssueLoader` class to gather open GitHub issues labeled `streams:add`, `streams:edit`, or `streams:remove` that also carry the `approved` label.

The `PlaylistParser` reads existing `.m3u` files from the `streams/` directory. The script applies transformations—adding new streams, modifying existing entries, or removing deprecated links—then writes the updated data back to the source files.

### Validation and Linting

Before generating public artifacts, the workflow enforces quality controls through `npm run playlist:lint` and `npm run playlist:validate`. These commands, defined in [`scripts/commands/playlist/validate.ts`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/playlist/validate.ts), check M3U syntax and verify that streams comply with project-specific rules, preventing broken playlists from reaching production.

### Public Playlist Generation

The `npm run playlist:generate` command executes [`scripts/commands/playlist/generate.ts`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/playlist/generate.ts) to create the public-facing playlist structure. This includes organizing streams into categorized folders (`categories/`, `countries/`), generating `index.m3u` files, and producing assorted log files that track stream availability.

### API Data Export

The workflow exports machine-readable data using `npm run playlist:export`, which runs [`scripts/commands/playlist/export.ts`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/playlist/export.ts). This script writes [`streams.json`](https://github.com/iptv-org/iptv/blob/main/streams.json) into the hidden `.api` directory, formatting the stream metadata for consumption by external applications.

### Documentation Update

The `npm run readme:update` step executes [`scripts/commands/readme/update.ts`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/readme/update.ts) to regenerate [`PLAYLISTS.md`](https://github.com/iptv-org/iptv/blob/main/PLAYLISTS.md). This script injects fresh data tables—listing countries, languages, and categories—into a template file, ensuring documentation remains synchronized with the actual playlist content.

### Git Operations and Deployment

The final phase configures Git identity using `git config` commands, then commits changes in two discrete steps: first staging modified `.m3u` files from the `streams/` directory, then staging the updated [`PLAYLISTS.md`](https://github.com/iptv-org/iptv/blob/main/PLAYLISTS.md). The workflow uses `git commit --allow-empty` to maintain consistent history even when no changes occur.

The `git push` command transmits these commits to the `master` branch, executing only on the actual GitHub runner.

Finally, the workflow deploys artifacts to two destinations:
- **GitHub Pages**: Uses `JamesIves/github-pages-deploy-action@4.1.1` to publish the `.gh-pages` folder containing public playlists.
- **External API Repository**: Deploys [`.api/streams.json`](https://github.com/iptv-org/iptv/blob/main/.api/streams.json) to the `iptv-org/api` repository, making the data available at `https://iptv-org.github.io/api/streams.json`.

## Data Flow Architecture

Understanding the GitHub Actions update workflow requires tracing how raw community input becomes structured output.

1. **Issue Ingestion**: The `IssueLoader` class scans for approved issues with specific labels, extracting stream metadata from the issue body.
2. **Playlist Mutation**: The `PlaylistParser` reads existing M3U files from `streams/`, applies the requested additions, edits, or removals, and writes the modified structures back to disk.
3. **Quality Assurance**: Validation scripts verify syntax and business rules before generating public artifacts.
4. **Artifact Generation**: The system produces three distinct outputs:
   - Human-readable M3U playlists organized by category and country
   - Machine-readable [`streams.json`](https://github.com/iptv-org/iptv/blob/main/streams.json) for API consumers
   - Updated documentation ([`PLAYLISTS.md`](https://github.com/iptv-org/iptv/blob/main/PLAYLISTS.md)) reflecting current content
5. **Distribution**: Commits push source changes to `master`, while deployment actions publish the public site and API data to their respective endpoints.

## Key Implementation Files

The GitHub Actions update workflow orchestrates several TypeScript modules located in the `scripts/commands/` directory.

- **[`.github/workflows/update.yml`](https://github.com/iptv-org/iptv/blob/main/.github/workflows/update.yml)**: The workflow definition containing all 20+ steps and deployment configurations.
- **[`scripts/commands/playlist/update.ts`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/playlist/update.ts)**: Contains `IssueLoader` and `PlaylistParser` classes that apply issue-driven changes to raw M3U files.
- **[`scripts/commands/playlist/generate.ts`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/playlist/generate.ts)**: Builds the public playlist hierarchy from cleaned source data.
- **[`scripts/commands/playlist/export.ts`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/playlist/export.ts)**: Writes the [`.api/streams.json`](https://github.com/iptv-org/iptv/blob/main/.api/streams.json) file consumed by the external API repository.
- **[`scripts/commands/playlist/validate.ts`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/playlist/validate.ts)**: Implements linting and validation logic to ensure playlist integrity.
- **[`scripts/commands/readme/update.ts`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/readme/update.ts)**: Regenerates [`PLAYLISTS.md`](https://github.com/iptv-org/iptv/blob/main/PLAYLISTS.md) documentation using current metadata tables.
- **[`package.json`](https://github.com/iptv-org/iptv/blob/main/package.json)**: Defines the NPM scripts referenced by the workflow steps.

## Code Examples

### Manually Triggering the Workflow

You can initiate the GitHub Actions update workflow manually using the GitHub CLI:

```bash
gh workflow run update.yml

```

Alternatively, navigate to the Actions tab in the repository, select the "Update" workflow, and click "Run workflow".

### Processing a Stream Addition Issue

When a maintainer approves a stream addition issue, the workflow consumes it during the `playlist:update` step. An example issue format:

```markdown

# Issue Title

Add new stream: BBC World (HD)

# Labels

streams:add, approved

# Body

stream_id: bbc_world@hd
stream_url: https://example.com/bbc.m3u8
label: HD
quality: 1080p

```

The [`update.ts`](https://github.com/iptv-org/iptv/blob/main/update.ts) script creates a new `Stream` object and appends it to the appropriate country file under `streams/`. The commit message automatically references the closed issue:

```

[Bot] Update /streams
Committed by iptv-bot via update workflow.
closes #123, closes #124

```

### Deploying to the External API Repository

The workflow deploys JSON data to a separate repository using the following configuration:

```yaml
- name: Move .api/streams.json to iptv-org/api
  uses: JamesIves/github-pages-deploy-action@4.1.1
  with:
    repository-name: iptv-org/api
    branch: gh-pages
    folder: .api
    token: ${{ steps.create-app-token.outputs.token }}
    commit-message: '[Bot] Deploy to iptv-org/api'
    clean: false

```

After deployment, the API is accessible at `https://iptv-org.github.io/api/streams.json`.

## Summary

The GitHub Actions update workflow in iptv-org/iptv provides a fully automated pipeline that transforms approved GitHub issues into deployed playlist artifacts.

- **Triggers** execute daily at 00:00 UTC or on manual dispatch via `workflow_dispatch`.
- **Authentication** uses a GitHub App token to enable secure, short-lived write permissions.
- **Core logic** in [`scripts/commands/playlist/update.ts`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/playlist/update.ts) parses issues labeled `streams:add`, `streams:edit`, or `streams:remove` and mutates M3U files in `streams/`.
- **Validation** ensures syntax correctness before generating public artifacts.
- **Outputs** include categorized M3U playlists, a JSON API export, and updated documentation.
- **Deployment** pushes commits to `master`, publishes to GitHub Pages, and syncs JSON data to the `iptv-org/api` repository.

## Frequently Asked Questions

### How does the GitHub Actions update workflow handle authentication securely?

The workflow generates a short-lived token using the `tibdex/github-app-token@v1.8.2` action with `APP_ID` and `APP_PRIVATE_KEY` repository secrets. This GitHub App token grants temporary write access for committing changes and deploying to external repositories without exposing long-lived personal access tokens in the CI environment.

### What types of GitHub issues does the update workflow process?

The workflow specifically processes open issues carrying the `approved` label alongside one of three action labels: `streams:add` for new entries, `streams:edit` for modifications, or `streams:remove` for deletions. The [`scripts/commands/playlist/update.ts`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/playlist/update.ts) script parses these issues to determine which transformations to apply to the raw `.m3u` files stored in the `streams/` directory.

### Can I manually trigger the update workflow if I need immediate changes?

Yes, the workflow includes a `workflow_dispatch` trigger that allows maintainers to run the pipeline on demand through the GitHub Actions web interface or via the GitHub CLI using `gh workflow run update.yml`. This manual trigger bypasses the daily cron schedule, enabling immediate processing of critical stream updates or urgent bug fixes.

### Where does the workflow deploy the generated API data?

The workflow deploys machine-readable data to two distinct endpoints. The public M3U playlists deploy to GitHub Pages from the `.gh-pages` folder within the same repository. Simultaneously, the [`streams.json`](https://github.com/iptv-org/iptv/blob/main/streams.json) file deploys to the separate `iptv-org/api` repository using `JamesIves/github-pages-deploy-action@4.1.1`, making the data available at `https://iptv-org.github.io/api/streams.json`.