octahedroid / wp-build-hooks

Build Hooks

Description

This plugin allows you to trigger a build hook on CircleCI and Gatsby Cloud Services.

CircleCI

Requirements

Terminus Secrets Plugin

You should set a secret key named CIRCLE_CI_TOKEN containing your CircleCI token value in the live environemt of your wordpress site.

https://github.com/pantheon-systems/terminus-secrets-plugin

Configure plugin

To configure the build hook on CircleCI we need add some required values.

On the settings page of this plugin, please select CircleCI for the Web Hook type.

Followed by the repository in format <organization or user>/<project> and the CircleCi Job to execute (e.g pfe/gatsby_build_and_deploy).

Save the settings and now we are ready to trigger a build from our wordpress site

In order to verify if the hook is setting up correctly you can check on the build hook page the Current webhook an url similar to this:

https://circleci.com/api/v1.1/project/gh/<organization or user>/<project>/tree/master?circle-token=72************************************fc

wp-build-hooks's Issues

Consider separate option for Pantheon Orb

I think at this point our CircleCI configuration is pretty pantheon-specific. Should we break out a separate option here for CircleCI + Pantheon Orb? https://github.com/octahedroid/wp-build-hooks/blob/master/wp-build-hooks.php#L16

Display build and deploy on workflow table

Test form with bad data

When incorrect values are added for job or repo, a PHP error is shown that includes the full CircleCI token.

Add help text

Add help text to the form that shows the format of the data that is supposed to be entered.
For instance my-github-username/my-github-repo-name.

Add Deploy to Live Button

Test on a site building to Netlify

Add a UI option for setting CircleCI token

I think we saw yesterday that reliance on the Terminus Secrets Plugin can slow down someone installing this plugin.

I still think it makes sense to store the token in an unversioned json file, but let's try writing that file through the UI. Maybe name it secrets.wp-build-hooks.json

Limit queue execution

Limit queue execution to one build at the time

PHP warning when setting token

Rachel set up this plugin on a Pantheon live environment and got multiple PHP errors because the secrets.json file or the private directory did not exist yet. Both set_secret() and get_secret() presume that the file exists.

Add branch selection option for CircleCI and Pantheon Orb configurations

WPCampus switched from master to main and now can't trigger builds.

Add a settings page link on plugin page

A minor UX improvement but one I find handy with new plugins because, once added, it can be a challenge to know where to find the settings page--if there even is one.

See the comment at the bottom for adding in the settings page link.
https://developer.wordpress.org/reference/hooks/plugin_action_links_plugin_file/

Remove CircleCI field

This configuration is no longer needed , remove from form and avoid storing those values as wp-options

Namespace or prefixes or singleton

I'm super excited about what this plugin is enabling content creators to do. Reviewed the code and it seems to work well. I'm just going to submit some issues around best practices for when this moves into the clean up tech debt phase.

To make sure common function names don't conflict with other plugins it is recommended to take steps to make yours unique. It use to be best practice was to prefix the plugin name to all functions but now that the WP minimum supported PHP version has been bumped people have been moving to using name spaces.
https://developer.wordpress.org/plugins/plugin-basics/best-practices/#avoid-naming-collisions

Refactor code

Refactor code into separated file to re-use functions between plugin and CLI commands.

Add php_Codesniffer with WP Coding Standards

We need to configure phpcs using the WP Coding Standards

We can take inspiration on how is managed these utilities on the wp-graphql plugin

allow full url as input format for repo

The last two people we've walked through setting up this plugin have tried copying the full repo URL (https://github.com/user-name/repo-name) rather than the format CircleCI wants (github/user-name/repo-name). I think we should allow either.

This need might also be an opportunity to start adding automated tests. If we have a function that breaks the user input string into the usable subcomponents (git provider, username, repo name) then that is a very unit-test element.

Make a configuration option to switch between bitbucket and github

Maybe a select list that defaults to github: https://github.com/octahedroid/wp-build-hooks/blob/master/wp-build-hooks.php#L151

Start doing releases with version numbers/release notes

As we have more sites and teams using this plugin we need version numbers and release notes that track changes so that users know when and how to safely upgrade.

Add ability to override variables sent to CircleCI

Our current pilot project will need the ability to generate non-live Gatsby previews from non-live WordPress instances. Basically, we need the ability to have a WordPress Multidev where WordPress core updates can be applied and then have a Gatsby site built that reads from that WordPress Multidev environment.

I can add more details and thought about how best to do this, but I wanted to make sure now that I got the issue captured in the queue before daily stand up.

data-source-url is getting sent as a hostname rather than a full url

This command is sending a hostname like mu-my-awesome-site.pantheonsite.io rather than a full url like https://mu-my-awesome-site.pantheonsite.io, which is what we have in examples. I think we should be sending the https:// too in the param name.

This difference isn't breaking anything as long as the Gatsby site getting triggered knows if the incoming param will have https:// or not. But it's worth picking one and aligning this plugin with the orb examples.

Show status of recent build(s) in UI

Let's use the CircleCI API to get the status of the most recent build or list of builds on the master branch.
https://circleci.com/docs/api/#recent-builds-for-a-single-project

Test on a site building to Gatsby Cloud

Security of secret JSON file

Right now this plugin is using a private json file to store the CircleCI API key. That's more secure than putting it in the database or in version control but we're relying on the private files directory being protected to prevent it from being read publicly. I don't think other hosts have that convention. The default behavior when not on Pantheon might need to be to store the API key in the database.

This task isn't critical right now when all sites using the plugin are on Pantheon, but this should block adding the plugin to the WordPress plugin directory.

Use CircleCI API version 2 for triggering builds

CircleCI is ending the ability to trigger jobs through the v1.1. API. https://circleci.com/blog/a-deprecation-notice-on-job-triggering-with-api-v1-1/

@jmolivas I know we talked about this at some point and I think you had a reason to stick with 1.1. But I just tried triggering a "pipeline via the version 2 API and it seemed to work fine. That seems like the safer API to build on: https://circleci.com/docs/api/v2/#circleci-api-pipeline

Add site-name field

Update README

Make sure README reflect latests changes

Actual:

This plugin allows you to trigger a build hook on CircleCI and Gatsby Cloud Services.
Suggestion
This plugin allows you to trigger a build hook on any service provider that supports build hooks.

We currently support wp-options

Se support full repo URL and V2 of CircleCI API

Lint for WP coding standards

I'm super excited about what this plugin is enabling content creators to do. Reviewed the code and it seems to work well. I'm just going to submit some issues around best practices for when this moves into the clean up tech debt phase.

A linter should be used to ensure the code follows WP PHP coding standards if the plan is to eventually submit to the WP repo.
https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/

In-line Documentation

Adding some inline documentation before launching would be helpful for developers looking to expand Build Hooks' functionality. Take a look at the best practices for documentation page which gives advice on WP's standards for doc blocks. https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#docblock-formatting

make pantheonsite url scheme configurable

Right now the plugin presumes sites are hosted on domains from pantheonsite.io https://github.com/octahedroid/wp-build-hooks/blob/master/wp-build-hooks.php#L400

That'll be a problem for sites like https://live--wpcampus-gatsby.my.pantheonfrontend.website/

Broken form on initial configuration

I just installed this plugin on a fresh WordPress site and I'm getting this behavior:

Looking closer, it seems like this select list is just causing the entire page to refresh:

Add back help text

It looks like it was accidentally deleted here: 3f91020