Collaborative Development with an External Repository

Use GitHub to collaborate with the team members on your Pantheon site.

Edit this page on GitHub Report an issue with this doc

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 /sites/default/files/ or /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

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://[email protected]: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://[email protected]:2222/~/repository.git (fetch)
origin  ssh://[email protected]: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).
Select Public.
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 origin because your local clone is already tracking the Pantheon site repository as origin.

In the example below, the remote is named github.

git remote add github [email protected]:pantheon-learning/d7-ci.git
git remote -v
github  [email protected]:pantheon-learning/d7-ci.git (fetch)
github  [email protected]:pantheon-learning/d7-ci.git (push)
origin  ssh://[email protected]:2222/~/repository.git (fetch)
origin  ssh://[email protected]: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 .git/config:

.git/config

[remote "origin"]
  url = ssh://codeserver.dev.@codeserver.dev..drush.in:2222/~/repository.git
  url = [email protected]: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 protected]:pantheon-learning/d7-ci.git

The repository on GitHub now has all of the same code as the existing site.

GitHub repo same as 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/default and 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 [email protected]: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://codeserver.dev.59b2dd69-2305-4ca2-a745-4f00e4100c88@codeserver.dev.59b2dd69-2305-4ca2-a745-4f00e4100c88.drush.in:2222/~/repository.git
! [remote rejected] master -> master (pre-receive hook declined)
error: failed to push some refs to 'ssh://codeserver.dev.59b2dd69-2305-4ca2-a745-4f00e4100c88@codeserver.dev.59b2dd69-2305-4ca2-a745-4f00e4100c88.drush.in:2222/~/repository.git'

This push to Pantheon failed, because the Development environment was in SFTP mode.

Connection Mode set to SFTP

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://codeserver.dev.59b2dd69-2305-4ca2-a745-4f00e4100c88@codeserver.dev.59b2dd69-2305-4ca2-a745-4f00e4100c88.drush.in:2222/~/repository.git
  fe267cb..b802550  master -> master

The GitHub repository and Pantheon site both now have a settings.php file. 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 pantheon.

Rename the remote repository:

git remote rename origin pantheon
git remote -v
github  [email protected]:pantheon-learning/d7-ci.git (fetch)
github  [email protected]:pantheon-learning/d7-ci.git (push)
pantheon  ssh://codeserver.dev.59b2dd69-2305-4ca2-a745-4f00e4100c88@codeserver.dev.59b2dd69-2305-4ca2-a745-4f00e4100c88.drush.in:2222/~/repository.git (fetch)
pantheon  ssh://codeserver.dev.59b2dd69-2305-4ca2-a745-4f00e4100c88@codeserver.dev.59b2dd69-2305-4ca2-a745-4f00e4100c88.drush.in:2222/~/repository.git (push)

Feature Branching

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://codeserver.dev.59b2dd69-2305-4ca2-a745-4f00e4100c88@codeserver.dev.59b2dd69-2305-4ca2-a745-4f00e4100c88.drush.in: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

Merged PR commit in the Pantheon dashboard

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.