mlkdev / bitbucket-deploy-wordpress-plugin

Creates a connection between WordPress and Bitbucket to allow streamlined deployment for plugins and themes being managed by private .git repositories.

The Bitbucket Deploy Plugin

Integration Instructions...

These steps will provide a simple and straight-forward approach to adding the service provided by the plugin to your own plugins and/or themes, enabling them to supply updates securely from behind a private repository.

...for plugins!

In your main plugin file, place the following lines of code:

// Register the plugin with the service if the service is available...
add_action(  'init',  function()  {
	if(  class_exists(  'BitbucketDeploy'  )  )  {
		$deploy  =  BitbucketDeploy::instance();
		$deploy->register_plugin(  __FILE__,  'your-account/your-repo'  );
	}
}  );

Walkthrough:

1. WordPress’s init action is hooked, supplying a callback directly to an anonymous function.
2. A class_exists() check is performed to see if the BitbucketDeploy class exists.
3. The singleton instance is retrieved for the BitbucketDeploy class by calling it’s instance static method.
4. Basic information about the plugin main file, and source repository are supplied to the singleton, by passing __FILE__, and the name of the repository where your plugin’s code is managed.

...for themes!

In your theme’s function file, place the following lines of code:

// Register the theme with the service if the service is available...
add_action(  'init',  function()  {
	if(  class_exists(  'BitbucketDeploy'  )  )  {
		$deploy  =  BitbucketDeploy::instance();
		$deploy->register_theme(
			get_stylesheet_directory().'/style.css',
			'your-account/your-repo'
		);
	}
}  );

Walkthrough:

1. WordPress’s init action is hooked, supplying a callback directly to an anonymous function.
2. A class_exists() check is performed to see if the BitbucketDeploy class exists.
3. The singleton instance is retrieved for the BitbucketDeploy class by calling it’s instance static method.
4. Basic information about the theme, and source repository are supplied to the singleton, by passing the filename of the theme’s style.css file, and the name of the repository where your theme’s code is managed.

Tagging Releases in Bitbucket

In order for the plugin to supply information to the WordPress transient interface, it must be able to retrieve information from the private repositories in the form of tagging. The deploy service will compare versions and supply update information to the WordPress transient interface, notifying it that there is a tagged release ready to be downloaded and installed.

To manage this, while in Bitbucket, navigate to the commit on your main repository branch that you want to mark for release, and tag it using the SEMVER format. Ensure that the tag matches the value in the plugin or theme’s metadata values.

Bitbucket Application Passwords

In order for the Bitbucket Deploy plugin to observe private repositories, it needs to supply an application password, associated with a privileged Bitbucket user account.

To create application passwords:

1. Sign into Bitbucket as the desired account.
2. Navigate to “Personal Settings” from the user avatar circle, screen top-right.
3. Make note of the “Username” under the “Bitbucket Profile Settings” section, screen main-area.
4. Choose “App passwords” in the “ACCESS MANAGEMENT” cluster, screen left-rail.
5. Click the “Create app password” button.
   • Choose a label that indicates the site ownership, the client’s name is a good choice here.
   • The only permission needed is “Repositories > Read”, so check that box, and uncheck the others.
   • Click “Create”.
6. Make note of the password, it will not be supplied again.
7. If a key needs to be revoked in the future, it can be done from this list.

Now that an application and password combination exist in Bitbucket with the privileges we need to begin pulling down updates for themes and plugins, we need to first tell the plugin what those credentials actually are.

There is a known issue with how Bitbucket rate-limits application password API requests. The rate limit can quickly be consumed by some setups. An update is currently being worked on to allow for on-demand update checks, rather than through the transient interface.

Configuring the Bitbucket Deploy Plugin

1. Sign into the desired WordPress installation where the Bitbucket Deploy plugin is installed.
2. Navigate to “Settings > Bitbucket Deploy”.
3. Supply the Bitbucket account username that owns the application password.
4. Supply the Bitbucket application password.
5. Click “Save Settings”.

The plugin will begin to poll at native WordPress intervals, looking for updates for anything registered on the service, without the need for cron.