One of the coolest, but probably the least understood features of Pantheon’s cloud based Drupal platform is “SFTP Mode”. This article is all about SFTP Mode and why it is so useful.
We use Pantheon for many (or all?) of our client sites and for community projects. The sites range from simple to complex and have been managed by a single developer or a team with multiple contributors. In that time, I’ve ramped up a gaggle of developers, freelancers, designers, clients, and community buddies on the Pantheon platform.
Every single person I’ve on boarded to the Pantheon development process has asked "WTF is SFTP Mode?". Each person has experienced a unique learning curve with SFTP Mode and their respective development workflow, even the GIT veterans! It is just a new thing to grock in a development workflow process.
This is a collection of questions, explanations, and insights surfaced through the applied use of SFTP Mode in our projects. I plan to use the article, in conjunction with Pantheon’s Getting Started documentation, to jump-start folks on the platform without repeating the same SFTP conversations. Thank you for your patience with the silly cloud development pun. :)
Setting expectations: SFTP Mode is odd. It is weird. It is powerful. It is beautiful. It can be dangerous. And this is why.
What the @#$% is SFTP Mode?!?!
SFTP Mode allows you to upload CODE to the Pantheon platform for testing without committing to the GIT repo.
When SFTP Mode is enabled, the code directory is made writable so pre-committed code can exist ON a Pantheon environment BEFORE it is committed to the Pantheon git repo. I think on the backend they switch the websevers to point to a writable directory instead of the GIT managed branch. But this is some special sauce that Josh and David could explain so much better and without speculation.
All you need to know that in SFTP Mode, the code directory on Pantheon is writable.
I call it the “grey area” of Pantheon because the uploaded CODE via SFTP mode isn’t yet checked into GIT until you commit it. The code is in a state of limbo.
Why is "code limbo" a good thing for Drupal development?
The code in limbo IS on a site on the Pantheon environment. Being on a Pantheon site, the limbo code can be tested within the overall platform with the content, database, file assets, Varnish, Solr, and Redis but before committing to GIT. This "pre-commit testing” on the platform is great and it cuts down development overhead time. Also, you don’t have to commit to the repo if things go dreadfully wrong!
SFTP Mode is used early within the site development workflow. It is a tool to allow the update of code between developer’s local system to the dev environment and their local system to a multidev environment.
We’ve discovered the following “Silver Linings" of SFTP Mode through our projects. The extended team has been converted from SFTP Mode skeptics to advocates of the tool.
Environment management:
- The web site’s files or database is too big to load locally (Zicasso.com) read the Drupal Migration Case Study
- Debugging configurations specific to Pantheon’s platform – Redis, Solr
- Your local environment isn’t working and site needs to get fixed NOW.
Research & Development:
- The SASS/Compass CSS compilation–upload–test development process for development.
- You are making tons of minor tweaks and don’t want to flood the git commit history. (CSS development on dev or multidev environment).
Development efficiency:
- You can regenerate Features directly to the platform and then commit them. This removes a ton of steps like downloading the Feature files to your computer, unzipping, checking in, deploying then testing again.
- Modules and themes can be downloaded directly to the platform using the Drupal interface. In GIT mode, the code directory isn't writeable.
- Modules and themes can be downloaded directly to the platform using Drush. This is another huge win for efficiency. Here's a sample drush command to download two modules that is executed directly to the a Pantheon dev environment named "sitename": drush @pantheon.sitename.dev dl --destination=sites/all/modules/novelty bad_judgement all_the_things drush @pantheon.sitename.dev en bad_judgement all_the_things
- You don’t have to check in your file changes. This has been a great help when doing rapid module and theme evaluations in an existing environment. Did that new module blow up the site? Did I actually just install Bad Judgement and All the Things? Just don’t commit the module code from SFTP mode. Switch to GIT Mode and those modules are gone! Clone a new DB from live or test and the footprint is gone. It never happened. ;)
- You can spin up and install complete sites with Drush. For our multilingual training at BADCamp, I spun up 20 environments with a full multilingual suite of modules prepared for the class with using a couple of drush commands, Terminus, and a little shell script. It took about a two hours, including the development and test of the drush make scripts. SUPER FAST and my office bandwidth and single computer were never a bottleneck for the parallel site creation. :)
Does it hurt to use SFTP? What should I NOT do?
Yes, SFTP Mode can hurt. It is a powerful tool, and with power comes responsibility. Think of a hammer. Hammers are great and powerful tools, but you can smash your thumb on accident or if using the tool carelessly.
- Do not keep SFTP mode enabled with code sitting in limbo for a long time. Since the files are never really in GIT yet, they are just hanging out. They haven't been officially checked in, so they don't get added to the schedule backup process. Also, dev and multidev environments “sleep” after some time of rest to reduce resource usage on Pantheon. I'm not sure if this affects the "grey area" but we have noticed that if code is left in STFP for a long time (many days to weeks with many sleeps) that switching to GIT or committing has hung.
- Do not have hundreds or thousands of changes in limbo. Check in frequently to ensure your development has some tracking and backups.
- Always look for uncommitted changes before an environment wipe OR turning GIT mode back on. If you aren’t careful, you can delete your code in “limbo”. Pantheon has put some protections on the dashboard, but make a habit of checking outstanding commits from "limbo".
- Be careful with the Terminus command line tools. If you are using Terminus, you have to be super careful to check for oustanding code commits.
- Configure your SFTP tools correctly. Make sure your SFTP client is set up to limit to one connection. :)
How does SFTP Mode integrate with my dev tools?
Many dev tools have an SFTP synchronization to speed up the copy-to-the-server process:
- Development program with enabled SFTP syncing (Coda, BBEdit, Sublime Text) A How-To for Coda a plugin extension for Sublime Text and How-To Information for Sublime Text and BBEdit
- IDE with enabled SFTP (PHPStorm, Eclipse) - A How-To for PHP Storm
You can find the SFTP connection strings on your dashboard on the "Connection Info" button. See detailed Pantheon documentation here: Enabling SFTP Mode, Connecting via SFTP Mode, and Committing SFTP Changes
SFTP Mode and Code Promotion - With More Detail
By design, SFTP Mode is special for “CODE” [files in git root / Pantheon code directory] and only works in environments that can be committed to via GIT: the dev environment [git master] or any multidev environments [git branches].
SFTP Mode [for code] does NOT work on test or live environments. But, you CAN use SFTP to upload files [in the Drupal files directory] to the test and live environments. Note the distinction between the two.
Pantheon uses a tagging method with GIT to promote code to test or live. There are no direct commits or file copies of code to test or live. This is a very good thing and is for your protection. Thank you nice people at Pantheon. You have saved us from ourselves. 
Since all code promotion is made via GIT and tagging, SFTP Mode follows all .gitignore rules. If you can’t commit a file via git within your .gitignore rules, you can’t commit it using SFTP Mode. See Pantheon's documentation for working with GIT and the Pantheon workflow documentation for a more detailed reference.
Sample Development Flows
Please note, the following flows are just an overview of working with SFTP mode in a couple of use cases. There are many mini-steps that are involved and subtly change for each environment. This post is getting long so I'm holding off on the micro-steps. :)
SFTP Mode + Local GIT clone + CSS development while testing on the Pantheon dev environment
This process can be used for dev and multidev, although multidev checks into an environment's branch, and there are more steps to properly merge into master while developers work in parallel. That is for another post later...
- Git clone to your local desktop from Pantheon's git, or if it exists, make sure it is updated: git fetch origin master; git checkout master; git pull;
- You need to change some CSS but you don't have a local dev environment setup, or it is broken.
- Change the Pantheon dev environment to SFTP mode via the Dashboard or Terminus.
- Browse to the dev-sitename.gotpantheon.com environment and do your in-browser inspection and CSS tweaks.
- Update the CSS file with the code changes in your editor on your local desktop, SFTP up to dev. Set up your local editor to sync to Pantheon to decrease the amount manual updates. See earlier in the article.
- Lather, rinse, repeat until the CSS is tidy. It is tidy? Did you test it? Good. ;)
- At this point, its time to check things in and commit the CSS through the Pantheon Dashboard.
- Go to the dashboard for the dev environment, code tab, make sure the outstanding changes are what you expect, then Commit and add a comment. Yay! Your work is now in GIT.
- BUT - we have to make sure your local repo is in sync with master. Do a git pull; from master, then your local copy of the repo is up to date.
- Take the site out of SFTP mode so you, others, and automated processes can use GIT.
SFTP Mode + Feature Creation (2.x) directly on Pantheon dev environment
- You don't need to GIT clone to a local desktop to make feature updates from the browser!
- First, make sure the dev or multidev site is updated with the most recent live or, if you are in the middle of a bunch of dev changes, back it up. Do this through the Pantheon Dashboard or Terminus.
- Check if SFTP Mode is already enabled. If it is, make sure there is no "limbo code". If there is, make sure it is either checked in or remove the kruft.
- Now you are ready to make or update your feature. Enable SFTP Mode in your Dashboard or Terminus.
- Open Drupal, make some changes - a view or some fields. Something fun like that. :) Test your work, confirm it is good and ready to check in.
- Yikes! Since these are DB configs, we have to make a feature do deploy to test and live.
- Go to the Features admin page /admin/structure/features and either create or update an existing feature. Name it, add your newly added configuration elements.
- Once you are ready to generate the feature to code, open the Advanced field group on the lower left hand side of the Feature Recreate / Create interface. You will see awesomeness!
- There is a button to "Generate Feature". Put a sane path to store your new feature, like sites/all/modules/features or sites/all/modules/custom and PRESS THE GENERATE BUTTON!
- Now you have all the generated feature code sitting in SFTP Mode limbo, ready to check it in.
- Check it in with a commit message that is descriptive.
- Deploy the new feature it to the test environment via the Dashboard, revert or enable the feature within Drupal on test, and see if everything is working. Miss a setting? Go back and add it to your feature in dev with SFTP mode, check it in again, deploy to test, and test.*
- Take the site out of SFTP Mode when you are done, leave it in GIT mode by default.
* Really all this feature stuff should be on a multidev and tested BEFORE checking into master, but this is just a quick checklist.
** If you are really l33t, you can do all the above stuff with drush commands against the Pantheon environment; e.g. drush @pantheon.sitename.dev fu awesome_feature
What's next?
Please contact us if you have a questions, need a clarification of terms, or have some other awesome use of SFTP Mode that we should add to this page!
This information is not a replacement for the helpful Pantheon documentation on SFTP Mode and actually testing it out. You can get a free developer account here.