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

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 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.

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, 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. 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, 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 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. This script writes 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 to regenerate 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. 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 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 for API consumers
   • Updated documentation (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: The workflow definition containing all 20+ steps and deployment configurations.
• scripts/commands/playlist/update.ts: Contains IssueLoader and PlaylistParser classes that apply issue-driven changes to raw M3U files.
• scripts/commands/playlist/generate.ts: Builds the public playlist hierarchy from cleaned source data.
• scripts/commands/playlist/export.ts: Writes the .api/streams.json file consumed by the external API repository.
• scripts/commands/playlist/validate.ts: Implements linting and validation logic to ensure playlist integrity.
• scripts/commands/readme/update.ts: Regenerates PLAYLISTS.md documentation using current metadata tables.
• 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:

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:

# 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 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:

- 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 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 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 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.

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