WP Self-Host Updater Generator

A GitHub Action for WordPress plugin and theme developers to enable self-hosted updates directly from GitHub. This Action simplifies the process of self-hosting your plugins and themes by:

1. Generating and commititing a JSON file based on the readme.txt.

• The JSON file will be used by plugin/theme to check updates.
• The JSON file will be created on wp-dist/data-json.

2. Creating a new release with a .zip distribution file.

• The .zip file follows the folder structure requires by WordPress.
• You can define folders or files to be excluded from the .zip file. To more details check the section Preparing the Distribution File: Excluding Paths/Files from the ZIP

Use this action to streamline the self-hosting process for your WordPress plugins and themes.

How to Use

This repository provides everything you need to the GitHub Action to work seamlessly and the "server" side of the self-host working as expected. However, this is just the “server” side of the solution. To fully enable self-hosted updates, you’ll need to integrate a simple PHP file into your plugin or theme. This file will manages communication with the JSON and release files generated by this Action directly from your repository.

• Quick Start Guide: Explore our guide How to Self-Host WordPress Plugins on Github and Deliver Updates for an easy-to-follow walkthrough of the entire self-hosting setup. It covers integrating this GitHub Action with the required PHP file in your plugin to ensure seamless updates.

• Required Integration: Check out WP Self-Host Updater Checker to get the required PHP file to add in your plugin/theme. This is an essential step to enable the fully self-hosted update mechanism.

Requirements

Before using this GitHub Action, ensure the following:

• readme.txt File: A valid WordPress plugin readme file must exist in the root of your repository.
• GitHub Token: The repository must allow write access for the GitHub Actions token. You need to define the necessary permissions in your workflow file (details below).

Workflow Configuration

To use this Action, create a new workflow file in your repository:

1. Navigate to .github/workflows/.
2. Create a new file, e.g., generate-dist-file.yaml.
3. Add the following content to the file:

name: Generate Dist File for Plugin
on:
  push:
    tags:
      - '*'

permissions:
  contents: write

jobs:
  generate-json-and-release:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          ref: main

      - name: Run WP Self-Host Update JSON Generator
        uses: eduardovillao/wp-self-host-updater-generator@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Important Notes

1. Permissions: Ensure that contents: write is defined in the workflow file for the GITHUB_TOKEN.
2. Repository Checkout: The first step must check out the repository, specifying the branch where the JSON file will be committed (main or master).
3. Trigger Events: Currently, the Action supports triggers only when a tag is created. Future versions may support additional trigger events.

---

Preparing the Distribution File: Excluding Paths/Files from the ZIP

To exclude specific files or directories from the .zip file generated during the release process, configure a .gitattributes file in your repository. This file ensures that unnecessary files are omitted from the export.

Here’s an example of a .gitattributes file:

# Exclude the wp-dist folder and its contents
wp-dist/ export-ignore

# Exclude hidden files and directories
.* export-ignore

# Exclude Git metadata
.git/ export-ignore

# Exclude local configuration files
*.env export-ignore
*.log export-ignore

# Exclude development and editor-specific settings
.vscode/ export-ignore
.idea/ export-ignore
*.iml export-ignore

# Exclude unnecessary documentation
*.md export-ignore

# Exclude test files and directories
tests/ export-ignore
*.spec.js export-ignore
*.test.js export-ignore

# Exclude CI configuration files
.github/ export-ignore
.gitlab-ci.yml export-ignore

# Exclude build configurations and dependencies
node_modules/ export-ignore
package-lock.json export-ignore
yarn.lock export-ignore