A Cloudflare Worker that provides a REST API for WordPress plugin and theme data. Most commonly, this API is used to manage custom plugin and theme updates in WordPress.
All data is fetched from GitHub directly and makes a few assumptions:
- Your WordPress plugin or theme lives in a public or private GitHub repository.
- You've created at least one release on GitHub.
- Your releases contain a
.zip
artifact that is used for the plugin or theme installation and the file name matches the repo slug.
- Install Node and NPM.
- Install the Wrangler CLI by running
npm i -g @cloudflare/wrangler
. - Run
wrangler login
to link the Wrangler CLI to your Cloudflare account.
- Run
git clone [email protected]:bluehost/worker-wp-github-release-api.git
to clone the repository. - Run
cp wrangler.example.toml wrangler.toml
to create your ownwrangler.toml
file. - Run
wrangler whoami
to get your Cloudflare Account ID. - Set your Cloudflare Account ID as
account_id
in thewrangler.toml
file. - Set your GitHub username as
GITHUB_USER
in thewrangler.toml
file. - Run
wrangler publish
to deploy the Worker to Cloudflare. - Create a personal access token on GitHub (don't set an expiration and only
check the
repo
permissions). - Run
wrangler secret put GITHUB_TOKEN
to set your GitHub token as an environmental secret on Cloudflare.
If you want to configure a custom route via the wrangler.toml
file, you will need to provide your Cloudflare Zone
ID as zone_id
in the wrangler.toml
file.
Once installed, you should be able to access the API at https://wp-github-release-api.<your-subdomain>.workers.dev
.
If you prefer to have the API live on a custom domain, follow the steps on setting up a custom route for your Cloudflare Worker.
Requests to the API use the following pattern: /:entity/:vendor:/:package/[:version]/[download]
.
Plugin Requests
# Get plugin info for latest version
/plugins/:vendor/:package
# Get plugin data for specific version
/plugins/:vendor/:package/:version
# Download latest plugin version
/plugins/:vendor/:package/download
# Download specific plugin version
/plugins/:vendor/:package/:version/download
Theme Requests
# Get theme info for latest version
/themes/:vendor/:package
# Get theme data for specific version
/themes/:vendor/:package/:version
# Download latest theme version
/themes/:vendor/:package/download
# Download specific theme version
/themes/:vendor/:package/:version/download
Required path parameters:
- entity - The entity type. Can be either
plugin
,plugins
,theme
orthemes
. - vendor - This is the GitHub username or organization name where the repository is located.
- package - This is the slug of the GitHub repository name.
Optional path parameters:
- version - The plugin or theme version number. When absent, the latest version will be returned. When present, the requested version will be returned.
- download - When appended to the URL path, this will trigger a download of the plugin or theme
.zip
file.
Optional query parameters:
- slug - The folder name of the plugin or theme. Allows you to override your plugin or theme slug if it is different from the package name.
- file - The file containing the WordPress plugin headers. Only required for plugin requests, this allows you to
override the main plugin file name if it doesn't match the expected pattern:
{package}.php
.
/plugins/wpscholar-wp-plugins/shortcode-scrubber
# OR
/plugins/wpscholar-wp-plugins/shortcode-scrubber/1.0.3
In this scenario, the plugin basename is assumed to be shortcode-scrubber/shortcode-scrubber.php
. This is derived
from the provided slug
and file
query parameters, if provided. Otherwise, the slug is assumed to match the
package
name and the file
is assumed to match the {package}.php
pattern.
/plugins/wpscholar-wp-plugins/shortcode-scrubber?slug=shortcode-scrubber-pro&file=scrubber.php
The example above would result in the following plugin basename: shortcode-scrubber-pro/scrubber.php
.
{
"name": "Shortcode Scrubber",
"type": "plugin",
"version": {
"current": "1.0.3",
"latest": "1.0.3"
},
"description": "A powerful tool for cleaning up shortcodes on your site and confidently managing plugins and themes that use shortcodes.",
"author": {
"name": "Micah Wood",
"url": "https://wpscholar.com"
},
"updated": "2020-05-11T22:23:45Z",
"slug": "shortcode-scrubber",
"basename": "shortcode-scrubber/shortcode-scrubber.php",
"url": "https://wpscholar.com/wordpress-plugins/shortcode-scrubber/",
"download": "https://github.com/wpscholar-wp-plugins/shortcode-scrubber/releases/download/1.0.3/shortcode-scrubber.zip",
"requires": {
"wp": "3.2",
"php": "5.6"
},
"tested": {
"wp": ""
}
}
/themes/wpscholar/block-theme
# OR
/themes/wpscholar/block-theme/1.0
{
"name": "Block Theme",
"type": "theme",
"version": {
"current": "1.0",
"latest": "1.0"
},
"description": "A block theme experiment",
"author": {
"name": "Micah Wood",
"url": "https://wpscholar.com"
},
"updated": "2021-08-06T13:27:23Z",
"slug": "block-theme",
"url": "",
"download": "https://github.com/wpscholar/block-theme/releases/download/1.0/block-theme.zip",
"requires": {
"wp": "",
"php": ""
},
"tested": {
"wp": ""
}
}
- Install the GitHub CLI. Mac users can simply run
brew install gh
if Homebrew is installed. - Fork this repository into your own GitHub account.
- Clone your new repository onto your local machine.
- Run
npm install
from the project root to install dependencies. - Create an API Token on Cloudflare using the
Cloudflare Workers
template. - Run
gh secret set CLOUDFLARE_API_TOKEN
to set your Cloudflare API key as a secret on GitHub. - Run
wrangler whoami
to get your Cloudflare Account ID. - Run
gh secret set CLOUDFLARE_ACCOUNT_ID
to set your Cloudflare Account ID as a secret on GitHub. - Run
gh secret set GH_USER
to set your GitHub user as a secret on GitHub. - Optionally, set your Cloudflare Zone ID by running
gh secret set CLOUDFLARE_ZONE_ID
. - Run
wrangler publish
to deploy the Worker to Cloudflare. This must be done once initially so that the secret we set next has an existing Worker to be applied to. - Create a personal access token on GitHub (don't set an expiration and only
check the
repo
permissions). - Run
wrangler secret put GITHUB_TOKEN
to set your GitHub token as an environmental secret on Cloudflare.
Any push to the master
branch on your GitHub repo will trigger the .github/workflows/deploy-cloudflare-worker.yml
workflow via GitHub Actions and deploy your Worker to Cloudflare automatically. If you use a different default branch,
such as main
, simply update the deploy-cloudflare-worker.yml
file to reflect the correct branch name.
- If certain bits of data are missing from the response, it could be that you haven't added all of the necessary file headers.