Releases and versioning

• Use SemVer for tags and releases (v1.2.3).
• Keep a consistent changelog.
• Publish releases with clear notes.

Security

• Use tokens with minimum permissions.
• Enable the repo whitelist with wpak_deploy2wp_allowed_repos.
• Configure the webhook with a secret and HMAC signature.

Update stability

• Include checksums (a .sha256 asset) when possible.
• Avoid “draft” or “pre-release” releases unless needed.
• Test updates in staging.
• Use the Update Policy: Production = stable-only, Staging/Test = prereleases allowed.

Performance

• Do not force checks too frequently.
• Keep caching and rate limiting enabled.

Operations

• Use the “System Info” page for diagnostics.
• Check logs after each automatic update.

This guide explains how to create and use a GitHub token for private repositories or higher API limits.

Recommended token (fine-grained)

1. Go to GitHub > Settings > Developer settings > Personal access tokens.
2. Select “Fine-grained tokens” and create a new token.
3. Select only the required repository.
4. Recommended minimum permissions:

• Repository permissions: Contents: Read
• Metadata: Read

1. Save the token.

Classic token

1. Go to GitHub > Settings > Developer settings > Personal access tokens.
2. Select “Tokens (classic)” and create a new token.
3. Minimum scope for private repos: repo.

Where to save the token

• WordPress admin: “Global GitHub token”.
• config.php for specific plugins:

'my-plugin' => [
    'repo' => 'username/my-plugin',
    'token' => 'ghp_xxxxx'
]

Note

• Never share the token in public code.
• Rotate the token periodically.

1. Single public plugin

Configure the plugin in config.php without a token:

'my-plugin' => [
    'repo' => 'username/my-plugin',
    'branch' => 'main'
]

2. Private plugins with a global token

Save a global token in the admin and add plugins without per-repo tokens.

3. Real-time updates via webhook

Configure the GitHub webhook and use tags to release new versions.

4. Multi-plugin with manual checks

Use the “Check updates” button for a global refresh.

5. Automatic rollback

If an update fails, the system restores the previous version from backup.

6. Staging prerelease channel

Set Site profile to Staging/Test to accept prereleases (beta/RC and other prerelease tags).

Check plugins in real time when a release is published or a tag is created on GitHub.

Endpoint

https://yourdomain.com/wp-json/wpak-deploy2wp/v1/webhook

Secret (recommended)

Set the secret in wp-config.php:

define('WPAK_DEPLOY2WP_WEBHOOK_SECRET', 'your-secret');

GitHub setup

1. Go to the repository > Settings > Webhooks > Add webhook.
2. Payload URL: the endpoint above.
3. Content type: application/json.
4. Secret: the configured secret.
5. Events: enable Release and Create.
6. Save.

Supported events

• release (action published).
• create (only tag).

Update Policy (important)

• Production blocks all prereleases (beta/RC and other prerelease tags).
• Staging/Test allows prereleases.
• Notify-only will show an admin notice instead of auto-installing.

Test

• Use the “Test” button in GitHub to send an event.
• Check plugin logs in WordPress.
• Verify the X-Hub-Signature-256 signature.