Jekyll Continuous Deployment with Bitbucket Pipelines and Aerobatic
Hosting a Jekyll site with Aerobatic can be as easy as typing in a couple of commands using the Aerobatic CLI:
Version v1 deployment complete. View now at https://my-jekyll-site.aerobaticapp.com
In the example above, we compiled our site locally and deployed the
/_site directory to Aerobatic. However, using Bitbucket Pipelines, we can set things up such the site is automatically built and deployed with each push to a Bitbucket repository.
Step 1: Create a Bitbucket Repository
First, create a repository in Bitbucket, and then push your jekyll site to the newly created repository:
# initialize new git repository [$] git init # set up our .gitignore file [$] echo -e "/_site\naero-deploy.tar.gz" >> .gitignore # commit and push code to master branch [$] git add --all [$] git commit -m "Initial commit" [$] git remote add origin email@example.com:YourUsername/jekyll-pipelines.git [$] git push -u origin master
Step 2: Configure Bitbucket Pipelines
In your website's Bitbucket repo:
- Click the Pipelines link in the left nav menu of your Bitbucket repository.
- Click the Enable Pipelines button.
- On the next screen, leave the default template and click Next.
- In the editor, paste in the YAML contents below and click Commit.
image: aerobatic/jekyll pipelines: branches: master: - step: script: - '[ -f Gemfile ] && bundle install' - 'echo "url: https://www.aerobatic.com" >> _config.yml' - bundle exec jekyll build - aero deploy --directory _site
To make the build as steps as streamlined as possible, there's a ready-made docker image aerobatic/jekyll that already has Ruby, Bundler, Jekyll, aerobatic-cli, and other supporting software for building native plugin gems all ready to go.
https://!!baseurl!! is a special value that Aerobatic will substitute on the fly with the current website URL. This makes it so the same deployed version can be safely pushed to a different deploy stage and all absolute URLs will auto-correct themselves.
It's recommended that you include a Gemfile that includes the specific version of Jekyll you want to build your site with, along with any plugin gems. Here's the Gemfile that the
jekyll new command generates:
source "https://rubygems.org" ruby RUBY_VERSION # Hello! This is where you manage which Jekyll version is used to run. # When you want to use a different version, change it below, save the # file and run `bundle install`. Run Jekyll with `bundle exec`, like so: # # bundle exec jekyll serve # # This will help ensure the proper Jekyll version is running. # Happy Jekylling! gem "jekyll", "3.4.0" # This is the default theme for new Jekyll sites. You may change this to anything you like. gem 'minima', '2.1.0' # If you have any plugins, put them here! group :jekyll_plugins do gem "jekyll-feed", "~> 0.6" gem 'jekyll-tagging', '1.0.1' gem 'jekyll-paginate', '1.1.0' gem 'jekyll-sitemap', '1.0.0' end
It's also a good idea to run
bundle install to generate a
Gemfile.lock that should be committed to source control.
The code for this example can be found in this Bitbucket repository.
Step 3: Create environment variable
This step only needs to be done once per account. If you haven't already done this in Bitbucket, from the command line:
- Navigate to the Bitbucket account settings for the account that the website repo belongs to.
- Scroll down to the bottom of the left nav and click the Environment variables link in the PIPELINES section.
- Create a new environment variable called
AEROBATIC_API_KEYwith the value you got by running the
aero apikeycommand. Be sure to click the Secured checkbox.
Step 4: Edit and Commit Code
Now that we've got Bitbucket Pipelines set up, we're now ready to test that everything is working smoothly. Push a commit to your repo and Pipelines will provision a Docker container, clone your code, and run your build script which builds your site and deploys it to Aerobatic.
Aerobatic deploy stages makes it trivially easy to deploy your site to a test URL by passing the
--stage option to the
deploy CLI command. This plays nicely with Pipelines mechanism for running different build steps per branch.
image: aerobatic/jekyll pipelines: branches: master: - step: script: - '[ -f Gemfile ] && bundle install' - 'echo "url: https://www.aerobatic.com" >> _config.yml' - bundle exec jekyll build - aero deploy --directory _site develop: - step: script: - '[ -f Gemfile ] && bundle install' - 'echo "url: https://www.aerobatic.com" >> _config.yml' - bundle exec jekyll build - aero deploy --directory _site --stage staging
With this configuration, any push to the
master branch will deploy to
https://jekyll-pipelines.aerobaticapp.com and pushes to the
develop branch will deploy to
https://jekyll-pipelines--staging.aerobaticapp.com. This of course works with custom domains as well.
- The code for this example can be found in this Bitbucket repository.
- Learn how to use declare plugins in your
aerobatic.ymlto extend the capabilities of your static Jekyll site.
- How to Password Protect a Jekyll site
Jekyll seems to be very particular when running in the Docker container about the format of the
Gemfile. If you get the error below, look at the files in the sample repo for guidance. Some users have reported they needed a line break at the end of the
jekyll 3.4.2 | Error: (/opt/atlassian/pipelines/agent/build/_config.yml): mapping values are not allowed in this context