This is a workflow for deploying Jekyll sites with CodeShip Basic. It follows good practices by building once, and deploying a tested build to staging and live webservers based on Git branches and tags. It also allows deploying previews, for instance for building a specific feature branch.
-
SSH access: If you want to use SSH, for the fastest deployments, ensure you have SSH access to your preview, staging and live webservers. On some web hosts, SSH access must be requested and enabled by support. You may still need to do this for your domain. Otherwise, deployment will use FTP.
-
Add the scripts: Make sure your repo includes the
test.sh
anddeploy.sh
scripts here. They should be in the repo's root folder. In addition, our scripts assume that your repo includes an up-to-date_configs/_config.live.yml
file, containing any configuration settings for live builds. -
Add a CodeShip project: Add a project to CodeShip and connect your repo. Choose 'CodeShip Basic' for your project type, not 'Pro'.
-
Tests: In the CodeShip project settings, go to Tests. Choose 'Ruby' from the list of technology defaults. Note: if you are setting up a site that does not build with Jekyll, such as an Electric Book remote-media repo, you can leave the Setup Commands blank.
-
Under 'Setup commands' you may need to include commands that set up the environment (i.e. the machine that builds your site) correctly. By default, CodeShip will include
bundle install
here. For instance, if your site'sGemfile.lock
has been generated with Bundler 2 (see the end of theGemfile.lock
to check), you need to install Bundler 2. To do this, add these lines beforebundle install
:# Uninstall any local and global bundler installations gem uninstall -x -a bundler rvm @global do gem uninstall -x -a bundler # Install newer version of Bundler gem install bundler -v 2.2.19
You can change the version number there as appropriate for your project.
-
If your project uses the latest Electric Book Template, you also need CodeShip to install Node modules. To do this, add this line after
bundle install
:npm install
-
Then under 'Configure Test Pipelines', click 'Add Pipeline' and add a tab called 'Test Commands'. In that tab, add these lines:
# Give permission for the script to run chmod +x test.sh # Run the test script ./test.sh
Note that the test script here does not actually include any tests. You'll need to add those based on your project needs.
-
-
Deploy: In Deploy settings, create deploy settings for three 'branches':
- create one deployment for the
live
- one for branches that 'start with'
preview
- one for branches that 'start with'
release
.
For each one, choose Script Deployment and add these deploy commands:
# Give the script permission to run chmod +x deploy.sh # Run the deploy script ./deploy.sh
By default, this will build and deploy to the staging server any further changes committed/merged to the live branch.
- create one deployment for the
-
Build triggers: Next, set the Build Triggers. You want to run builds on the branch you're deploying (e.g.
live
), and on^preview.*$
and^release.*$
, which is any branch or tag that starts with 'preview' and 'release', respectively. (For Git purposes, a tag is a branch, but without any further commits). To do this, select 'Run builds for these branches only', and add these three lines to the 'Enter one branch per line' box:live ^preview.*$ ^release.*$
For the other settings:
- set to run only on commits, merges and tags
- set auto-supersede builds off (we want staging builds to complete before deploying to live).
-
Environment variables: In CodeShip project settings, you need to add several environment variables. These set exactly how you'll deploy and where to.
Key | Example value | Alt. example | Notes |
---|---|---|---|
DEPLOY_METHOD_LIVE | FTP | SSH | If you don't set this, FTP is default. SSH is much faster, but requires high-level server access. |
DEPLOY_METHOD_STAGING | FTP | SSH | If you don't set this, FTP is default. SSH is much faster, but requires high-level server access. |
DEPLOY_METHOD_PREVIEWS | FTP | SSH | If you don't set this, FTP is default. SSH is much faster, but requires high-level server access. |
DESTINATIONPATH_STAGING | public_html/mybooks | Required. If your SSH user connects directly to the destination folder, leave this value blank or don't set it. | |
DESTINATIONPATH_LIVE | public_html/mybooks | Required. If your SSH user connects directly to the destination folder, leave this value blank or don't set it. | |
DESTINATIONPATH_PREVIEWS | public_html | Required. If your SSH user connects directly to the destination folder, leave this value blank or don't set it. | |
SSH_STAGING | [email protected] | Not required if using FTP. | |
SSH_LIVE | [email protected] | Not required if using FTP. | |
SSH_PREVIEWS | [email protected] | Not required if using FTP. | |
SSH_STAGING_PORT | 2222 | Only required if your staging-site host uses a non-standard SSH port (i.e. not port 22) | |
SSH_LIVE_PORT | 2222 | Only required if your live-site host uses a non-standard SSH port (i.e. not port 22) | |
SSH_PREVIEWS_PORT | 2222 | Only required if your previews site host uses a non-standard SSH port (i.e. not port 22) | |
FTP_HOST_LIVE | example.com | 42.653.343.33 | Not required if using SSH. |
FTP_USER_LIVE | dkufh7fhrf | jo@mysite | Not required if using SSH. |
FTP_PASSWORD_LIVE | kfuh4i87f3ufhr7f743hf | Not required if using SSH. | |
FTP_HOST_PREVIEWS | previews.example.com | Not required if using SSH. | |
FTP_USER_PREVIEWS | hfiuhf7f | Not required if using SSH. | |
FTP_PASSWORD_PREVIEWS | ufhwfh8374fi4hf4fwuefiw | Not required if using SSH. | |
FTP_HOST_STAGING | staging.example.com | Not required if using SSH. | |
FTP_USER_STAGING | rufhi4ff | Not required if using SSH. | |
FTP_PASSWORD_STAGING | fiufuhr87ffeoifiw7f | Not required if using SSH. |
-
SSH key: If you are using SSH for deployments, get the project's CodeShip public key from the 'General' tab in project settings. Add this CodeShip key to both your staging and your live servers. On many webservers, you'll add this key as a line in the
~/.ssh/authorized_keys
file on the server. -
Done! At this point:
- Any commit to the
live
branch will be automatically deployed to staging. - Any commit on any branch with a tag that starts with
preview
will be deployed to staging, in a directory named after the tag. - Any commit on any branch with a tag that starts with
release
will be deployed to live. Never add arelease
tag to any branch other thanlive
. The scripts should protect you from releasing a non-live-branch build to live, but it's best not to take this chance.
- Any commit to the
To deploy a preview to the staging server, you'll use git tags that start with preview
. To do this, first make sure that your current local Git repo is in the state you want to preview. This process will build a preview of the most recent commit. Then:
-
If you are working in the original upstream repo (don't type the
#
comment lines):# Add a preview-* tag to the last commit # You need the -f (aka --force) if you're using a tag you've used before. # E.g. if you're updating the `more-potatoes` preview to a later commit. git tag -a preview-more-potatoes -f -m "A short description" # Push the tag. # Again, the -f forces git to update an existing tag on the remote. git push preview-more-potatoes -f
-
If you are working in a fork (don't type the
#
comment lines):# Make sure you have the latest version of the relevant branch from upstream # For most previews the relevant branch to pull from will be 'master' not 'more-potatoes' git pull upstream more-potatoes # Add a preview-* tag to the last commit # You need the -f (aka --force) if you're using a tag you've used before. # E.g. if you're updating the `more-potatoes` preview to a later commit. git tag -a preview-more-potatoes -f -m "A short description" # Push the tag. # Again, the -f forces git to update an existing tag on the remote. git push upstream preview-more-potatoes -f
CodeShip will spot your tag, build the site and run the tests, and then deploy the site to your staging server in a directory named for your tag, e.g. example.com/preview-more-potatoes/
.
Technical note: We're using annotated tags, not lightweight tags, hence the -a
and the -m
followed by a short message. This is because by default CodeShop does a shallow clone to reduce the time taken to fetch the repo, and shallow clones do not include lightweight tags.
When you merge a PR into the live
branch, CodeShip will deploy to the staging server automatically. If the staging website looks fine and is approved, you are ready to deploy to live.
To do this, you will tag the latest commit on the live
branch with a tag that starts with the word 'release', e.g. release-v1.8.6
. When you push that tag, CodeShip will deploy the latest build to the live webserver. The commands you use for this depend on whether you are working in the original, upstream repo, or your fork of it.
-
If you are working in the original upstream repo (don't type the
#
comment lines):# Checkout the live branch git checkout live # Get the latest changes git pull # Add a release-* tag to the last commit git tag -a release-v1.8.5 -f -m "A short description" # Push that tag git push --tags # Checkout master again for safety git checkout master
-
If you are working in a fork (don't type the
#
comment lines):# Make a new live branch if you don't yet have one... git checkout -b live # ...or just checkout if you already have a live branch git checkout live # Pull the upstream's live branch into your live branch git pull upstream live # Add a release-* tag to the last commit git tag -a release-v1.8.5 -f -m "A short description" # Push that tag to upstream's live branch git push upstream --tags # Checkout master again for safety git checkout master
Note that this deploys only the last build, and does not build and test again. This is to ensure that you deploy the exact same build that was deployed to staging. When CodeShip runs the test and deploy scripts, the scripts check the tag on the last commit. If it starts with 'release', they deploy the most recent build to the live server. If it doesn't, it builds and deploys to staging.