Push Site to Pantheon (GitHub Action)

This GitHub Action pushes your site's code from GitHub to the Pantheon Dev environment or Multidev environment.

It is designed to be used in GitHub Actions workflows that are triggered by Pull Requests and pushes to the main branch of your repository.

When running workflow triggered by a pull request, this action will create a Multidev environment and deploy code to it.

When running on workflows triggered by merges/pushes to the main branch this action will deploy code to the Pantheon Dev environment.

Early Access

As a publicly available GitHub Action, there is no gating mechanism preventing any Pantheon customer from using the code in this repository. However, this reposistory is in active development and behaviors may change between versions. Only teams with pre-existing Continuous Integration pipelines that they could fall back to, should try this repository at this time. See our documentation for more information about software maturity and support.

Basic Usage

This action provides a step that can be used as the only step within a job. More complex examples further below show additional steps and jobs used in conjunction with this action.

Here is the beginning of a jobs section of a site's .github/workflows/deploy-pr.yml file that deploys a site to Pantheon when triggered by a Pull Request.

jobs:
  push:
    permissions:
      deployments: write
      contents: read
      pull-requests: read
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Push to Pantheon
      uses: pantheon-systems/push-to-pantheon@0.5.0
      with:
        ssh_key: ${{ secrets.PANTHEON_SSH_KEY }}
        machine_token: ${{ secrets.TERMINUS_MACHINE_TOKEN }}
        site: ${{ vars.PANTHEON_SITE }}

Parameters

In order to use the step supplied by this Action, the GitHub Workflow must have access to a token for authenticating with Pantheon's command line and a private key that will allow Git pushes to Pantheon and other operations. Both of those values should be treated sensitively and stored as GitHub Secrets.

The only other required argument is the machine name of the Pantheon site to which the code will be pushed.

The optional argument likely to be most commonly used is delete_old_environments which will delete Multidev environments associated with closed pull requests after the deployment completes. Setting delete_old_environments: true is recommended for workflows that run after merges to the main branch to avoid accumulating Multidev environments that are no longer needed.

Required Arguments

ssh_key

A private key that corresponds to a public key on Pantheon.

machine_token

A token for authenticating with Pantheon's command line.

site

The machine name of your Pantheon site.

Optional Arguments

delete_old_environments

If set to true, Multidev environments associated with closed pull requests will be deleted after deployment completes. It is recommended to set this parameter to true for workflows that run after merges to the main branch.

   default: false
   type: boolean

target_env

The Pantheon environment to which the deployment will be made. If left blank, the value used will be automatically derived. Pull requests will deploy to environments named pr-${NUMBER} and main/master branch commits will deploy to the Pantheon "dev" environment.

   default: ""

source_env

The environment from which the database and uploaded files will be copied.

   default: "live"

clone_content

If set to true, the database and files directory will be re-cloned from the source environment. When set to false, this data is only copied upon Multidev creations. Setting this variable to true ensures fresh content but adds time to the build process that can be prohibitive for sites with large databases.

   default: false
   type: boolean

git_user_name

The name to be used with the Git commit that will be pushed to Pantheon. This value is not used on newer 'eVCS' sites for which there is no Pantheon-provided Git repo.

   default: "GitHub Action Automation"

git_user_email

The email address to be used with the Git commit that will be pushed to Pantheon. This value is not used on newer 'eVCS' sites for which there is no Pantheon-provided Git repo.

   default: "GitHubAction@example.com"

git_commit_message

A custom commit message to be used with the Git commit that will be pushed to Pantheon. Leaving this Action parameter blank will result in a generic commit message being used. This value is not used on newer 'eVCS' sites for which there is no Pantheon-provided Git repo.

   default: ""

Additional recommendations

Pin exact version of this action prior to the release of version 1.0.0

Prior to the release of version 1.0.0, it is recommended to pin the version of this action to a specific version in your workflow file. This will prevent breaking changes from being introduced to your workflow without your knowledge. The most likely breaking change would be a change to the name of the action or the name of the inputs. For instance is delete_old_environments the best name for that parameter? We might change it.

To pin the version of this action to a specific version, use the @ symbol followed by the version number in the uses key of the step that uses this action. For example, to use version 0.4.1 of this action, the step would look like this:

- name: Push to Pantheon
  uses: pantheon-systems/push-to-pantheon@0.4.1
  with:
    ssh_key: ${{ secrets.PANTHEON_SSH_KEY }}
    machine_token: ${{ secrets.TERMINUS_MACHINE_TOKEN }}
    site: ${{ vars.PANTHEON_SITE }}

Additional build steps like composer install and npm build

By default this action will check out the code from the GitHub repository and push it to Pantheon. For many WordPress sites and Drupal sites, this is all that is needed. By setting build_step: true in the pantheon.yml, Pantheon will execute composer install and eventually npm build for compilation of CSS and JS assets needed for a theme.

However, some teams prefer to do these build steps in GitHub Actions before pushing to Pantheon.

That use case can be accommodated by adding additional steps to the workflow before the step that uses this action.

Here's an example from a real site that uses Tailwind to prepare CSS in the site's custom theme.

  push-to-pantheon:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    # The custom theme for this site uses Tailwind to build the
    # appropriate CSS file.
    - run: "cd web/themes/my_custom_theme && npm ci && npm run build"
    # Deleting this small .gitignore that ignores compiled CSS
    # from the GitHub repo will allow it to be committed and pushed
    # to Pantheon in the later "push-to-pantheon" step.
    - run: "cd web/themes/my_custom_theme/css && rm .gitignore"
    - name: Push to Pantheon
      uses: pantheon-systems/push-to-pantheon@0.5.0
      with:
        ssh_key: ${{ secrets.PANTHEON_SSH_KEY }}
        machine_token: ${{ secrets.TERMINUS_MACHINE_TOKEN }}
        site: ${{ vars.PANTHEON_SITE }}

By calling npm run build and modifying gitignore prior to calling push-to-pantheon, the Tailwind-generated CSS (which is not wanted in the GitHub repo) is available to be committed (and pushed) inside the push-to-pantheon step.

Permissions

This action needs permission to perform its work. Set the following permissions either at the level of the workflow or at the level of the job that uses this action.

    permissions:
      deployments: write
      contents: read
      pull-requests: read

The deployments: write permission is required to notify GitHub that the deployment has been made (to a Pantheon Multidev usually). This is required for the GitHub UI to show the deployment status of the pull request:

The contents: read permission is required for the job to check out the code from the GitHub repository. Even though this action does not checkout of the code itself, the code must be checked out prior to this step in order for the action to work.

The pull-requests: read permission is required to delete old Multidev environments associated with closed pull requests.

See the GitHub Actions documentation for more information on permissions.

Concurrency

Sometimes in the course of development it is normal to push one commit to a branch with a pull request and then push another commit a minute later and then another. Similarly, a team might merge five pull requests in quick succession. Depending on the nature of the project, the team might want relevant Workflows to be processed for every single commit.

However, for most WordPress and Drupal teams deploying to Pantheon we recommend running no more than one workflow on a branch at a time because this GitHub Action presumes (though does not strictly enforce) that all workflow runs on a given branch will deploy code to the same Pantheon environment. Multiple workflows each attempting to deploy code to the same environment at the same time could result in confusing error states or failing automated tests that follow deployment.

To ensure that only one build runs at a time for a pull request, include this concurrency section in your workflow's yml file:

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
  cancel-in-progress: false

For a workflow that handles only the main branch, that section could be altered to:

concurrency:
  group: ${{ github.workflow }}-main
  cancel-in-progress: false

Using additional jobs to test your code and the deployed site

Unit tests and code sniffing/linting generally do not need a fully functioning site in order to execute. Therefore you can run them in parallel with the job that pushes the site to Pantheon. End to end tests that depend on a fully functioning site should wait for the job that pushes to complete so that the tests can run against the deployed site.

In this example, coding standards checks are run in parallel with the push-to-pantheon job and tests written in Playwright which check customized CMS functionality run after the deployment completes.

Here is an example from a real site that runs a coding standards check in parallel to the push-to-pantheon job.

Here is how those jobs are defined in an example site's .github/workflows/deploy-pr.yml file:

jobs:
  push-to-pantheon:
    runs-on: ubuntu-latest
    steps:
    - name: Deploy to Pantheon
      uses: pantheon-systems/push-to-pantheon@0.5.0
      with:
        ssh_key: ${{ secrets.PANTHEON_SSH_KEY }}
        machine_token: ${{ secrets.TERMINUS_MACHINE_TOKEN }}
        site: ${{ vars.PANTHEON_SITE }}

  code_standards_check:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Composer install
      run: composer install
    - name: Check coding standards
      run: composer run cs

  playwright:
    needs: push-to-pantheon
    runs-on: ubuntu-latest
    steps:
    - name: Check out the repository
      uses: actions/checkout@v2
    - uses: ./.github/actions/playwright-against-pantheon
      with:
        pantheon_ssh_key: ${{ secrets.PANTHEON_SSH_KEY }}
        terminus_machine_token: ${{ secrets.TERMINUS_MACHINE_TOKEN }}
        pantheon_site: ${{ vars.PANTHEON_SITE }}