Collaborative Development with an External Repository
Use GitHub to collaborate with the team members on your Pantheon site.Discuss in our Forum Discuss in Slack
Pantheon provides Git repositories for all sites on the platform. However, some teams might need an external repository hosted by a provider, like GitHub or Bitbucket, to function as the canonical version of the site's codebase. This section shows you how to use Pantheon with an external repository. The example below uses a GitHub account. However, the steps should be similar for any provider.
Git Repositories on Pantheon
The codebase for your site is stored in a Git repository. This includes your versions of Drupal or WordPress core, and all of the custom and contributed modules, plugins, and themes that work together to power your site. It doesn’t include the
/wp-content/uploads/ directories, or your database.
This repository will be a clone of one of the upstreams running on the platform, usually Drupal or WordPress, or one of their forks that our users manage as Custom Upstreams. Your site’s repository on the Pantheon platform will track one of these upstream repositories as a Git remote.
These repositories control the common codebase for several sites. The most common change to an upstream is the release of a new core version. These changes to the upstream repository become available to the sites running them within a day. For individual sites, using GitHub to collaborate on custom code is often a requirement for teams. In order to do so, you’ll need a quick and efficient way to keep your Pantheon repository in sync with GitHub.
The sections below will show you the basics for collaborating with others if your site:
- Is only on Pantheon and you’re moving development to GitHub
- Exists on GitHub and you want to deploy to Pantheon
- Isn’t using Git
- Doesn’t yet exist
Synchronizing Existing Pantheon Sites to GitHub
Log in to Pantheon and load the Site Dashboard for the site you want to work on.
Click the Dev tab, set the Development Mode to Git, and then click Clone with Git:
Your local copy will now track the Pantheon repository as the origin.
git clone <ssh://codeserver.dev.UUID@codeserver.dev.UUID.drush.in:2222/~/repository.git d7-ci> Cloning into 'd7-ci'... remote: Counting objects: 298630, done. remote: Compressing objects: 100% (59210/59210), done. remote: Total 298630 (delta 208616), reused 298143 (delta 208186) Receiving objects: 100% (298630/298630), 67.23 MiB | 479.00 KiB/s, done. Resolving deltas: 100% (208616/208616), done. Checking connectivity... done.
Change directory into the site repository and verify your connection to the Pantheon server:
cd d7-ci git remote -v origin ssh://codeserver.dev.UUID@codeserver.dev.UUID.drush.in:2222/~/repository.git (fetch) origin ssh://codeserver.dev.UUID@codeserver.dev.UUID.drush.in:2222/~/repository.git (push)
The output lists "origin" as the remote with Pantheon SSH Git clone connection information as it's address.
Create a Repository on GitHub
Follow the steps below to configure your GitHub repository.
Click the Owner drop-down menu to set the owner to your GitHub user or organization (wherever you want the GitHub repository to live).
- Only members of one or more GitHub organization have the option to change the owner. GitHub users that aren't part of an organization are not given the option to change the owner and will not have an Owner drop-down menu.
Enter the Repository name (the examples on this page use d7-ci).
Keep Initialize this repository with a README unchecked if you want the option to add code to your repository.
Select the Add .gitignore checkbox and set the .gitignore template drop-down to none.
Select the Choose a license checkbox and set the License drop-down to none.
Click Create Repository.
Add the GitHub Repository as a Remote
Replace the word
origin with the name you want for your remote to add the GitHub repository as a remote.
The remote, in this case, cannot be named
originbecause your local clone is already tracking the Pantheon site repository as
In the example below, the remote is named
git remote add github email@example.com:pantheon-learning/d7-ci.git git remote -v github firstname.lastname@example.org:pantheon-learning/d7-ci.git (fetch) github email@example.com:pantheon-learning/d7-ci.git (push) origin ssh://codeserver.dev.UUID@codeserver.dev.UUID.drush.in:2222/~/repository.git (fetch) origin ssh://codeserver.dev.UUID@codeserver.dev.UUID.drush.in:2222/~/repository.git (push)
Configure Origin as a Multi-Remote Destination (Optional)
You can also add another push URL for origin by adding a push URL within
[remote "origin"] url = ssh://codeserver.dev.
@codeserver.dev. .drush.in:2222/~/repository.git url = firstname.lastname@example.org:systemseed/example.git
Commits will be pushed to both remote destinations automatically on
git push origin. Enforce this configuration with all team members when working collaboratively. Thanks to Tom Kirkpatrick for contributing this tip in the Pantheon Community.
Push the Pantheon Site's Codebase to GitHub
Run the command below in your terminal:
git push -u github master Writing objects: 100% (120046/120046), 31.88 MiB | 3.26 MiB/s, done. Total 120046 (delta 89679), reused 120039 (delta 89679) To email@example.com:pantheon-learning/d7-ci.git
The repository on GitHub now has all of the same code as the existing site.
Migrate Existing Site Repositories to Pantheon
The Pantheon Dashboard provides a guided path for migrating existing sites to the platform. Follow the steps in the Migrate Existing Sites document.
Developing in Sync
You must create the
settings.php file to develop in sync.
Change directory into
sites/defaultand create the file:
cd sites/default touch settings.php
Add the file to version control and push to both remotes:
git status On branch master Your branch is up-to-date with 'github/master'. Untracked files: (use "git add <file>..." to include in what will be committed) settings.php nothing added to commit but untracked files present (use "git add" to track) git add . git status On branch master Your branch is up-to-date with 'github/master'. Changes to be committed: (use "git reset HEAD <file>..." to unstage) new file: settings.php git commit -m “Create settings.php” master b802550] Create settings.php 1 file changed, 577 insertions(+) create mode 100644 sites/default/settings.php
Push the change to GitHub and Pantheon:
git push github master Counting objects: 4, done. Delta compression using up to 4 threads. Compressing objects: 100% (4/4), done. Writing objects: 100% (4/4), 384 bytes | 0 bytes/s, done. Total 4 (delta 2), reused 0 (delta 0) To firstname.lastname@example.org:pantheon-learning/d7-ci.git fe267cb..b802550 master -> master
git push origin master Counting objects: 4, done. Delta compression using up to 4 threads. Compressing objects: 100% (4/4), done. Writing objects: 100% (4/4), 384 bytes | 0 bytes/s, done. Total 4 (delta 2), reused 0 (delta 0) remote: remote: PANTHEON NOTICE: remote: remote: Environment 'dev' (branch: master) is currently in SFTP mode. remote: It cannot receive git pushes until you disable this via the Pantheon dashboard. remote: If you are trying to push changes to a different branch or environment, try: remote: git push origin [branch-name] remote: To ssh://email@example.com:2222/~/repository.git ! [remote rejected] master -> master (pre-receive hook declined) error: failed to push some refs to 'ssh://firstname.lastname@example.org:2222/~/repository.git'
This push to Pantheon failed, because the Development environment was in SFTP mode.
Set the Development Mode to Git by clicking on the toggle, or enter the code below in the command line:
terminus connection:set <site>.<env> git
Push to Pantheon:
git push origin master Counting objects: 4, done. Delta compression using up to 4 threads. Compressing objects: 100% (4/4), done. Writing objects: 100% (4/4), 384 bytes | 0 bytes/s, done. Total 4 (delta 2), reused 0 (delta 0) To ssh://email@example.com:2222/~/repository.git fe267cb..b802550 master -> master
The GitHub repository and Pantheon site both now have a
settings.phpfile. This will allow for environment-specific configuration to enable modules through remote Drush calls and other essential functionality.
We recommend renaming the remote repository to something more specific than
origin, such as
Rename the remote repository:
git remote rename origin pantheon git remote -v github firstname.lastname@example.org:pantheon-learning/d7-ci.git (fetch) github email@example.com:pantheon-learning/d7-ci.git (push) pantheon ssh://firstname.lastname@example.org:2222/~/repository.git (fetch) pantheon ssh://email@example.com:2222/~/repository.git (push)
Working with teams on GitHub requires a branching strategy. You must add your colleagues to the site you're developing, both on GitHub and on Pantheon.
Locally, your codebase is in sync with both repositories.
Checkout a branch to start working on a new feature:
Since the site is associated with a supporting organization that has a Multidev environment, you can test out any feature. These environments have an 11-character limit for branch names, so you should use short branch names for your feature branches.
git checkout -b configs Switched to a new branch 'configs']
Download the module and its dependencies in your local environment.
composer require drupal/xautoload
Enable the module > test and verify that the module is working.
Add, commit, and push to branches on Pantheon and GitHub:
git status On branch configs Untracked files: (use "git add <file>..." to include in what will be committed) sites/all/modules/configuration/ sites/all/modules/xautoload/ nothing added to commit but untracked files present (use "git add" to track) Brians-Pantheon-Mac-2:d7-ci brian$ git add . Brians-Pantheon-Mac-2:d7-ci brian$ git commit -m "install configuration and xautoload" [configs 0f85fbd] install configuration and xautoload 284 files changed, 25781 insertions(+)
git push pantheon configs Counting objects: 365, done. Delta compression using up to 4 threads. Compressing objects: 100% (325/325), done. Writing objects: 100% (365/365), 199.00 KiB | 0 bytes/s, done. Total 365 (delta 70), reused 0 (delta 0) remote: remote: PANTHEON NOTICE: remote: remote: Skipping code sync, no multidev environments were found for branch "configs". remote: To ssh://firstname.lastname@example.org:2222/~/repository.git
The platform found no Multidev environments associated with the Git branch.
Continue with the steps below to create a Multidev environment.
Create a Multidev environment in Terminus:
terminus multidev:create <site>.dev <to_env>
The module will now be available to activate and test on Pantheon for your colleagues to experience.
Add a link to the module's configuration page on the Multidev environment in your GitHub pull request.
Create Pull Request
You are now ready to create a pull request on GitHub. The pull request can include:
Links to the Multidev environment where the team can view the effects of the commits
@-mentions of team members
A list of tasks for team members to perform before merging
Timani completed the tasks, we discussed a bit in person, and he merged the PR.
Deploy to Pantheon
Checkout the master branch on your local.
Pull from github master > push to pantheon master:
git checkout master git pull github master git push pantheon master
Optional Tools to Optimize Workflows
There are other options to further optimize workflows now that you have the basic setup.
Pantheon's Build Tools
A continuous integration server like Jenkins, Travis CI, Bamboo, or CircleCI
A suite of automated acceptance tests using Behat or PHPUnit
These tools allow your team to fully implement continuous delivery with automated testing and continuous integration.