https://github.com/eduardovillao/wp-self-host-updater-generator
A GitHub Action for WordPress plugin and theme developers to enable self-hosted updates directly from GitHub.
https://github.com/eduardovillao/wp-self-host-updater-generator
self-host-in-github self-host-plugins wordpress wordpress-actions
Last synced: 3 months ago
JSON representation
A GitHub Action for WordPress plugin and theme developers to enable self-hosted updates directly from GitHub.
- Host: GitHub
- URL: https://github.com/eduardovillao/wp-self-host-updater-generator
- Owner: eduardovillao
- License: mit
- Created: 2024-12-23T00:56:07.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-01-20T19:51:35.000Z (5 months ago)
- Last Synced: 2025-01-20T20:34:13.154Z (5 months ago)
- Topics: self-host-in-github, self-host-plugins, wordpress, wordpress-actions
- Language: JavaScript
- Homepage:
- Size: 30.3 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# 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 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](#preparing-the-distribution-file-excluding-pathsfiles-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](https://eduardovillao.me/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](https://github.com/eduardovillao/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:
```yaml
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:
```gitattributes
# 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
```