Add Oribi Sync plugin for syncing WordPress pages and theme files from a Git repository
- Implement encryption helpers for storing and retrieving the Personal Access Token (PAT). - Create REST API endpoints for triggering sync, checking sync status, and handling webhooks. - Develop the sync engine to fetch pages from the Git repository, create/update WordPress pages, and trash removed pages. - Add functionality for previewing and applying theme files from the repository. - Set up plugin activation and deactivation hooks to manage default options and scheduled tasks. - Implement uninstall routine to clean up plugin options and metadata from posts.
This commit is contained in:
Matt Batchelder
139
README.md
Normal file
139
README.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# Oribi Tech Sync
|
||||
|
||||
WordPress plugin that syncs pages and theme files from a remote Git repository.
|
||||
|
||||
## Features
|
||||
|
||||
- **Page sync** — Reads Gutenberg HTML files from the repo's `pages/` directory and creates/updates WordPress pages automatically.
|
||||
- **Theme file preview & apply** — Fetches files from the repo's `theme/` directory, shows a side-by-side preview against the active theme, and lets an admin selectively apply changes.
|
||||
- **Encrypted PAT storage** — Personal Access Tokens are stored encrypted (AES-256-CBC) in the database with `autoload=false`.
|
||||
- **Dry-run mode** — Preview what a sync would do without making any changes.
|
||||
- **Sync log** — Keeps a history of the last 20 syncs with details on created, updated, trashed, and skipped pages.
|
||||
- **REST API & webhook** — Trigger syncs programmatically or via Git host webhooks.
|
||||
- **Trash policy** — Pages removed from the repo are moved to Trash for manual review.
|
||||
|
||||
## Repository Layout
|
||||
|
||||
The plugin expects the following structure in the remote Git repository:
|
||||
|
||||
```
|
||||
repo/
|
||||
├── pages/
|
||||
│ ├── home.php
|
||||
│ ├── about.php
|
||||
│ ├── contact.php
|
||||
│ ├── managed-it.php
|
||||
│ └── ...
|
||||
├── theme/
|
||||
│ ├── style.css
|
||||
│ ├── theme.json
|
||||
│ └── assets/
|
||||
│ ├── css/
|
||||
│ │ └── main.css
|
||||
│ └── js/
|
||||
│ └── main.js
|
||||
└── (other files — ignored)
|
||||
```
|
||||
|
||||
### `pages/` directory
|
||||
- **PHP files** (`.php`) — Use the `oribi_b()`, `oribi_b_open()`, and `oribi_b_close()` block helpers to build Gutenberg markup and `return` the result (same format as the theme's `page-data/*.php` files). Requires the **Oribi Tech Setup** plugin to be active for the helper functions.
|
||||
- **HTML files** (`.html`) — Contain raw Gutenberg block markup (`<!-- wp:... -->`) and are used directly as page content.
|
||||
- The filename (without extension) becomes the page slug: `home.php` → slug `home`.
|
||||
- Page title is derived from the slug: `managed-it` → "Managed It".
|
||||
- Only direct children of `pages/` are processed (no subdirectories).
|
||||
|
||||
### `theme/` directory
|
||||
- Contains theme style/asset files (CSS, JS, JSON, PHP, HTML, SVG, TXT).
|
||||
- Subdirectories are supported — e.g., `theme/assets/css/main.css` maps to `<active-theme>/assets/css/main.css`.
|
||||
- Files are **not** applied automatically — they are fetched for preview.
|
||||
- Admin can review each file, compare against the active theme, and selectively apply.
|
||||
- Applied files are written directly into the active theme directory.
|
||||
|
||||
## Supported Git Providers
|
||||
|
||||
| Provider | Auth method | PAT format |
|
||||
|---|---|---|
|
||||
| **GitHub** (github.com + GHE) | `Bearer` token | Fine-grained PAT with `Contents: Read` |
|
||||
| **GitLab** (gitlab.com + self-hosted) | `PRIVATE-TOKEN` header | Project/personal access token with `read_repository` |
|
||||
| **Bitbucket Cloud** | Basic or Bearer | App password (`username:app_password`) or repository token |
|
||||
| **Gitea / Forgejo** | `token` header | Application token with repo read access |
|
||||
| **Azure DevOps** | Basic (`:PAT`) | Personal access token with `Code: Read` scope |
|
||||
|
||||
Select your provider on the settings page, or leave it on "Auto-detect" to infer from the URL.
|
||||
|
||||
## Setup
|
||||
|
||||
1. Install and activate the plugin on your WordPress site.
|
||||
2. Go to **Settings → Oribi Sync**.
|
||||
3. Enter the **Repository URL** (HTTPS format, e.g., `https://github.com/owner/repo`, `https://gitlab.com/owner/repo`, `https://bitbucket.org/owner/repo`, `https://gitea.example.com/owner/repo`, or `https://dev.azure.com/org/project/_git/repo`).
|
||||
4. Select the **Provider** (or leave on auto-detect).
|
||||
5. Enter the **Branch** (defaults to `main`).
|
||||
6. Enter a **Personal Access Token** with read access to the repository (see table above for format).
|
||||
7. Click **Save Settings**.
|
||||
|
||||
## Usage
|
||||
|
||||
### Manual Sync
|
||||
- Click **Sync Now** on the settings page to sync pages immediately.
|
||||
- Click **Dry Run** to preview changes without modifying anything.
|
||||
- Click **Preview Theme Files** to fetch and review theme files from the repo.
|
||||
|
||||
### REST API
|
||||
|
||||
All REST endpoints require `manage_options` capability (authenticated admin).
|
||||
|
||||
```bash
|
||||
# Trigger sync
|
||||
curl -X POST https://yoursite.com/wp-json/oribi-sync/v1/sync \
|
||||
-H "X-WP-Nonce: <nonce>" \
|
||||
--cookie "wordpress_logged_in_...=..."
|
||||
|
||||
# Trigger dry-run
|
||||
curl -X POST "https://yoursite.com/wp-json/oribi-sync/v1/sync?dry_run=1" \
|
||||
-H "X-WP-Nonce: <nonce>" \
|
||||
--cookie "wordpress_logged_in_...=..."
|
||||
|
||||
# Get status
|
||||
curl https://yoursite.com/wp-json/oribi-sync/v1/status \
|
||||
-H "X-WP-Nonce: <nonce>" \
|
||||
--cookie "wordpress_logged_in_...=..."
|
||||
```
|
||||
|
||||
### Webhook
|
||||
|
||||
Set up a webhook on your Git host to trigger syncs on push:
|
||||
|
||||
**Endpoint:** `POST https://yoursite.com/wp-json/oribi-sync/v1/webhook`
|
||||
|
||||
**Authentication** (one of):
|
||||
- `Authorization: Bearer <secret>` header
|
||||
- GitHub `X-Hub-Signature-256` header (HMAC-SHA256)
|
||||
|
||||
**Secret configuration** (one of):
|
||||
- Define `ORIBI_SYNC_WEBHOOK_SECRET` in `wp-config.php`
|
||||
- Store in WP option `oribi_sync_webhook_secret`
|
||||
|
||||
## Security
|
||||
|
||||
- PAT is encrypted with AES-256-CBC using a key derived from `AUTH_SALT`.
|
||||
- All admin actions require `manage_options` capability and nonce verification.
|
||||
- REST endpoints require authenticated admin user.
|
||||
- Webhook endpoint validates shared secret or HMAC signature.
|
||||
- Theme file writes are restricted to allowed extensions (CSS, JS, JSON, PHP, HTML, SVG, TXT).
|
||||
|
||||
## Sync Behavior
|
||||
|
||||
| Scenario | Action |
|
||||
|---|---|
|
||||
| New file in `pages/` | Create new WP page (published) |
|
||||
| Changed file in `pages/` | Overwrite page content |
|
||||
| Unchanged file in `pages/` | Skip (no unnecessary revisions) |
|
||||
| File removed from `pages/` | Move corresponding WP page to Trash |
|
||||
| New file in `theme/` | Available for preview & manual apply |
|
||||
| Changed file in `theme/` | Available for preview & manual apply |
|
||||
|
||||
## Requirements
|
||||
|
||||
- WordPress 6.0+
|
||||
- PHP 7.4+ with `openssl` extension
|
||||
- Git host with API access (GitHub or GitLab supported)
|
||||
Reference in New Issue
Block a user