stevector / circleci-orb-1

Use CircleCI to push code to Pantheon Dev and Multidev Environments

Pantheon CircleCI Orb

This reposistory contains the source code for Pantheon's CircleCI Orb. Orbs are a way of encapsulating sharable CircleCI jobs and commands.

This repository provides a job to push code from GitHub or BitBucket to Pantheon through CircleCI.

Use this Orb if you want to progressively introduce continuous integration into a new or pre-existing project on Pantheon. If you're instead looking to start a new Composer-based site with multiple CI steps pre-configured, please start from our example-drops-8-composer or example-wordpress-composer repositories. Those can be copied in one command using the Terminus Build Tools Plugin.

Setting Up an Existing Pantheon Site To Use the push Job From This Orb

0. First, make sure your Pantheon site has an initialized Live environment. If you are making a brand-new site, only the Dev environment will be present. Make the Test and Live environments because this Orb will copy the database and files from the Live environment to newly created Multidev environment (or the Dev environment when building on the master branch).
1. Make a GitHub repo with the code from your Pantheon site.
   • Make a new repo on GitHub if you do not have one yet.
   • Add the new GitHub repo as a remote to a local clone of your Pantheon site: `git remote add github [email protected]:YOUR_USERNAME/YOUR_REPO.git
   • Push the master branch (the code currently on your Pantheon Dev environment) to the newly created GitHub repo: git push github master:master
2. Configure CircleCI for your repository.
   • Sign in to CircleCI and set up the repo for Circle builds.
   • Set up can be done at the URL https://circleci.com/setup-project/gh/YOUR_USERNAME/YOUR_REPO
   • In your local checkout of your code, create a file at .circleci/config.yml.
   • Copy this example into the .circleci/config.yml file.

     version: 2.1
     workflows:
       version: 2
       just_push:
           jobs:
           - pantheon/push
     orbs:
       pantheon: pantheon-systems/[email protected]

   • Commit and push the file to GitHub. CircleCI will build attempt to run the workflow but it will return an error message because the steps below have not yet been completed. Turning failing red builds into passing green builds is part of the joy of CI.
   • Until this Orb is released as a 1.0.0, you will need to set the "Allow Uncertified Orbs" option. For GitHub users this can be done at https://circleci.com/gh/organizations/YOUR_USERNAME_OR_ORGNAME/settings#security
3. Set up SSH keys and environment variables.
   • Pantheon requires SSH keys for performing git interactions. CircleCI needs a private key that matches a public key connected to your Pantheon account (or another account with access to the Pantheon site in question).
     • Create a new SSH key on your local machine in a tmp directory with ssh-keygen -m PEM -t rsa -b 4096 -f /tmp/new_key_for_ci -N ''.
       • pbcopy is a command installed by default on MacOS systems. If you use a different operating system you may need to copy and paste the SSH key values manually. See the Pantheon SSH key documentation for more information on SSH key generation.
     • Copy the newly created public key (cat /tmp/new_key_for_ci.pub | pbcopy) and add it to your Pantheon account.
     • Copy the private key (cat /tmp/new_key_for_ci | pbcopy) and add it to your CircleCI configuration by using the "SSH Permissions" settings. Set the hostname as drush.in and paste your private key into the text box.
   • Under Environment Variables in your CircleCI settings add a variable for TERMINUS_SITE set to the machine name of your Pantheon site.
   • The machine name of your site is simply the site name in all lowercase with spaces replaced by dashes. For example, My CircleCI Orb Test would be my-circleci-orb-test.
   • Create a Terminus machine token using the Pantheon Dashboard. Add it as another environment variable in CircleCI named TERMINUS_TOKEN.
   • Retrigger a build in CircleCI either by pushing a whitespace (or otherwise inocuous) change to your code on GitHub. This time, the build should pass.
4. (Optional) Under "Advanced Settings" in your CircleCI repository settings turn on "Only build pull requests." While not necessary, this setting prevents separate Pantheon Multidev environment from being created for each commit. With this setting on, all created Multidevs will be named by pull request number and subsequent pushes to an open pull request will reuse the same Multidev environment.

Examples

Here is the simplest possible usage of this orb in a .circleci/config.yml file.

version: 2.1
workflows:
  version: 2
  just_push:
    jobs:
    - pantheon/push
orbs:
  pantheon: pantheon-systems/[email protected]

Here is an example that compiles Sass in a separate job before pushing to Pantheon.

# See this example in use at https://github.com/stevector/wordpress-orb-demo
version: 2.1
workflows:
  version: 2
  compile_sass_and_push:
    jobs:
    - npmbuild_and_persist
    - pantheon/push:
        # This "requires" section tells CircleCI the order in which
        # jobs must be run.
        requires:
          - npmbuild_and_persist
        # Because the checkout command is called from pre-steps, it should
        # not be run inside the orb-defined steps.
        checkout: false
        # Commands to run before the orb-defined steps.
        pre-steps:
          # Perform a git checkout of the code from GitHub/Bitbucket so that
          # custom commands (the rm below) can alter the code before it is
          # pushed to Pantheon.
          - checkout
          # Attach this dist directory created in npmbuild_and_persist
          # which contains the compiled css.
          - attach_workspace:
              at: .
          # The dist directory that holds the compiled Sass is git ignored.
          # It needs to be committed on Pantheon.
          # Removing this .gitignore file makes it available for committing.
          # Pantheon's Composer examples use a more complicated
          # technique of "cutting" the top level .gitignore
          # file so that lines specifying build artifact directories are removed.
          # https://github.com/pantheon-systems/example-drops-8-composer/blob/670ae310c601dabbb7b35411ff3e08e4b1fac7a3/composer.json#L67
          - run: rm wp-content/themes/may2019/.gitignore

orbs:
  pantheon: pantheon-systems/[email protected]
jobs:
  # This job compiles Sass and then saves (persists) the directory
  # containing the compiled css for reuse in the pantheon/push job.
  npmbuild_and_persist:
    docker:
    - image: node:10.15.3
    steps:
    - checkout
    - run:
        name: install npm dependencies in a custom WordPress child theme
        command: cd wp-content/themes/may2019 && npm ci
    - run:
        name: Compile Sass
        command: cd wp-content/themes/may2019 && npm run build
    - persist_to_workspace:
        root: .
        paths:
        - wp-content/themes/may2019/dist

Parameters

Jobs from CircleCI Orbs can take parameters (variables) that alter the behavior of the job. At this time the push job takes only one parameter.

parameter name	type	default value	required	description
checkout	boolean	true	no	Determines whether a git checkout will be the first command called by the job. Set to false if you have already called "checkout" in the pre-steps section.

Assumptions and Intended Audience

The initial release of the Pantheon Orb is intended to be most helpful to existing Pantheon customers who have been interested in, but reluctant to adopt continuous integration. This Orb should help you take an existing site on Pantheon and start managing the code on GitHub (or BitBucket) and begin to introduce additional build steps like the compilation of Sass or the running of tests.

If you already have a mature CI discipline within your team this Orb may not provide significant additional value at this time. If you are starting a fresh site and want a complete Composer-based workflow with CI, then you are better off making a copy of example-Drops-8-composer or example-wordpress-composer.

Related Projects

• Terminus is the Pantheon command line tool. This Orb uses Terminus in order to do things like authenticate with Pantheon. As is mentioned in the set up steps above, you will need to supply a TERMINUS_TOKEN environment variable to CircleCI for authentication to work.
• Terminus Build Tools is a plugin for Terminus that encapsulates many Continuous Integration tasks. It relies on you setting the machine name of your site as a TERMINUS_SITE environment variable in CircleCI for certain commands to function.
• Example Drops 8 Composer is an example repository that shows a Composer-based Drupal 8 workflow that goes from GitHub to CircleCI to Pantheon. It may soon incorporate this Orb.
• Example WordPress Composer is the WordPress twin to Example Drops 8 Composer.

Support

This project is under active development and you may find bugs or have questions. Please use the issue queue for this project.