mirror of
https://github.com/eduardovillao/wp-self-host-updater-generator.git
synced 2025-11-23 02:05:46 +08:00
112 lines
No EOL
4.5 KiB
Markdown
112 lines
No EOL
4.5 KiB
Markdown
# 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
|
||
``` |
