Skip to content
Example scripts for using Pantheon's Quicksilver Platform Hooks
PHP
Branch: master
Clone or download
Latest commit 0c49174 Aug 14, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
asana_integration Change PHP keywords to comply with PSR2 (#156) Apr 6, 2019
backtrac_visualregression Updating API Call to Use New HTTPS Endpoint Apr 20, 2016
chikka-sms-notification Change PHP keywords to comply with PSR2 (#156) Apr 6, 2019
cloudflare_cache Change PHP keywords to comply with PSR2 (#156) Apr 6, 2019
db_sanitization Fixing a typo in the comment Aug 13, 2019
debugging_example Updated README.md for Terminus 1.0 Jan 23, 2017
diffy_visualregression Diffy documentation update. Switch to token based authentication. (#158) May 22, 2019
drush_config_import Use `workflow:watch` instead of `workflows watch` (#146) Aug 28, 2018
drush_revert_features Update README for revert all features example to suggest reverting af… Feb 6, 2016
enable_dev_modules Rename 'drush example' to 'enable dev modules'. Feb 6, 2016
generate_dev_content fixing a minor typo in description Oct 23, 2016
hipchat_notification Change PHP keywords to comply with PSR2 (#156) Apr 6, 2019
jenkins Change PHP keywords to comply with PSR2 (#156) Apr 6, 2019
jira_integration Change PHP keywords to comply with PSR2 (#156) Apr 6, 2019
new_relic_apdex_t Bug fix in new_relic_apdex_t Aug 23, 2016
new_relic_deploy Change PHP keywords to comply with PSR2 (#156) Apr 6, 2019
pivotal-tracker Change PHP keywords to comply with PSR2 (#156) Apr 6, 2019
slack_notification Change PHP keywords to comply with PSR2 (#156) Apr 6, 2019
spotbot_visualregression Integration with Spotbot.qa for Visual Regression Testing Mar 29, 2016
trello_integration Change PHP keywords to comply with PSR2 (#156) Apr 6, 2019
url_checker Fixing a typo that breaks checks on test because the pattern is wrong Jan 29, 2019
webhook Cleaning up for release Feb 6, 2016
wp_cfm_import Import all wp-cfm config files in private/scripts (#136) Mar 26, 2018
wp_search_replace
wp_solr_index Clarify WordPress for this example Aug 30, 2016
.gitignore Initial commit Dec 10, 2015
LICENSE Initial commit Dec 10, 2015
README.md Improved documentation relating to private directories. (#117) Mar 27, 2018
example.pantheon.yml Add drush_version to example.pantheon.yml Sep 16, 2016

README.md

Pantheon Cloud Integration Examples

This repo contains example scripts for use with Quicksilver Platform Hooks. These will allow you to automate more of your workflow, and integrate better with other cloud services.

The current release of Quicksilver supports one utility operation: webphp. This invokes a PHP script via the same runtime environment as the website itself. php scripts are subject to the same limits as any code on the platform, like timeouts, and cannot be batched.

This initial release makes four platform workflows eligible for Quicksilver operations:

  • deploy: when code is deployed to Test or Live. webphp scripts run on the target environment.
  • sync_code: code is pushed via Git or committed in the Pantheon dashboard. webphp scripts run on the committed-to environment (dev or multidev).
  • clone_database: data is cloned between environments. webphp scripts run on the target (to_env) environment.
  • clear_cache: the most popular workflow of them all! webphp scripts run on the cleared environment.

Introducing pantheon.yml

Quicksilver is configured via a pantheon.yml file, which lives in the root of your repository (~/code/). When this file is first pushed to an environment, it will set up the workflow triggers.

The format for pantheon.yml is as follows:

# Always start with an API version. This will increment as Quicksilver evolves.
api_version: 1

# Now specify the workflows to which you want to hook operations.
workflows:
  deploy:
    # Each workflow can have a before and after operation.
    after:
      # For now, the only "type" available is webphp.
      - type: webphp
        # This will show up in output to help you keep track of your operations.
        description: Log to New Relic
        # This is (obviously) the path to the script.
        script: private/scripts/new_relic_deploy.php

Note that if you want to hook onto deploy workflows, you'll need to deploy your pantheon.yml into an environment first. Likewise, if you are adding new operations or changing the script an operation will target, the deploy which contains those adjustments to pantheon.yml will not self-referentially exhibit the new behavior. Only subsequent deploys will be affected.

When Updating: pantheon.yml: Updates will fire on the next sequential workflow, not post-deploy. scripts: Updates will fire post-deploy. script location: Updates will fire on next sequential workflow, not post-deploy.

When Adding: pantheon.yml: Updates will fire on the next sequential workflow, not post-deploy. scripts: Updates will fire on the next sequential workflow.

Security

When getting started with Quicksilver scripts, you'll want to first create two private directories on your website instance.

The first private directory should be created in your ~/files/ directory via SFTP (e.g. ~/files/private/). This directory is not included in your source code and is used to store a secrets.json file where you can confidently store sensitive information like API keys and credentials. You will need to create a separate private directory (and subsequent secrets.json) for each environment as this directory isn't included in source and will not propagate during deployments. You can easily manage the key-value pairs in the secrets.json file per environment (after initially creating the file via SFTP) using Terminus after installing the Terminus Secrets Plugin. The Slack notification example uses this pattern. For high-security keys, we recommend a third party secrets lockbox like Lockr.

The second private directory should be created in your project's web root (e.g. ~/code/private/ OR ~/code/web/private/ depending on the web_docroot setting in your pantheon.yml file). This private directory is part of your repository, so it should not hold any sensitive information like API keys or credentials. Once you've created the private directory, we recommend creating a scripts directory within it to store all of your Quicksilver scripts.

Pantheon automatically limits public access to both of these private directories, so no special configuration in pantheon.yml is required. Scripts stored here can only be executed by the Pantheon platform.

Terminus Commands

Developers making use of Quicksilver will want to make sure they are Terminus savvy. Get the latest release, and a few new commands are included:

$ terminus help workflows
##NAME
    terminus workflows

##DESCRIPTION
    Actions to be taken on an individual site

##SYNOPSIS
    <command>

##SUBCOMMANDS
    list
        List workflows for a site
    show
        Show operation details for a workflow
    watch
        Streams new and finished workflows to the console

The list and show commands will allow you to explore previous workflows and their Quicksilver operations. The watch command is a developers best friend: it will set up Terminus to automatically "follow" the workflow activity of your site, dumping back any Quicksilver output along with them.

Environment variables

To discover what environment variables are available to your scripts then take a look at the debugging_example script and instructions.

Troubleshooting

  • While your scripts can live anywhere, we recommend private since that will prevent the contents from ever being directly accessed via the public internet.
  • You'll know pantheon.yml has been added correctly, and your quicksilver actions are registered when you see a message like the following on git push:
    remote: PANTHEON NOTICE:
    remote:
    remote: Changes to `pantheon.yml` detected.
    remote:
    remote: Successfully applied `pantheon.yml` to the 'dev' environment.
    
You can’t perform that action at this time.