Samvera Connect 2019 - CircleCI Workshop

samvera-connect-2019-circleci-workshop.md

Samvera Connect 2019 - CircleCI Workshop

We're going to run through converting a simple ruby gem from a Travis CI build to a CircleCI build using the Samvera orb.

Setup Code

1. Fork ruby-rdf/linkeddata to your personal github space
2. Checkout your fork locally: git clone https://github.com/<username>/linkeddata.git
3. Enter checkout directory: cd linkeddata
4. Run bundle install: bundle install
5. Verify the tests pass: bundle exec rspec

Setup Repository in CircleCI

1. Login to CircleCI
2. Select your personal github space in the dropdown at the top of the page.
3. Go to Add Projects in the left navigation bar.
4. Use the filter box to find your fork and click "Set Up Project"
5. Make sure Linux is selected for OS and Ruby for Language. Next we'll follow their directions.
6. Make the CircleCI directory: mkdir .circleci
7. Paste the sample config into .circleci/config.yml
8. We'll remove the DB related pieces the config.
9. Push changes up to github: git add .circleci; git commit -m "Initial circleci config"; git push origin develop
10. Click "Start building"

Exploring the CircleCI interface

We start at the Workflows index view and can zoom into a single running workflow by clicking on it. This gives us a flow chart view of the jobs within this workflow. We only have one right now. Clicking on that job gives us details about the steps the build takes. Notice how each step can be expanded for more details and show pass/fail and timings. You should have two failing steps: Restoring Cache and run tests.

Fixing the build

1. Edit linkeddata.gemspec by adding gem.add_development_dependency "rspec_junit_formatter"
2. bundle install
3. Push it: git add linkeddata.gemspec ; git commit -m "Add rspec_junit_formatter"; git push origin develop
4. In CircleCI, click on "develop" in the breadcrumbs to get back to the workflows index view.
5. Go into the new workflow and now the overall build should pass.
6. Note that the Restore Cache step is still failing because this project doesn't have a Gemfile.lock.

Using the Samvera Orb

1. Enable Third-Party Orbs by clicking "Settings" in the left navigation menu then "Security". Make sure "Allow Uncertified Orbs" is set to "Yes".
2. Replace .circleci/config.yml:

   version: 2.1
   orbs:
     samvera: samvera/circleci-orb@0
   jobs:
     build:
       executor:
         name: 'samvera/ruby'
         ruby_version: "2.5.7"
   
       steps:
         - samvera/cached_checkout
         - samvera/bundle_for_gem:
             ruby_version: "2.5.7"
             project: linkeddata
         - samvera/parallel_rspec
   

   This config changes the CircleCI config version to 2.1, adds the samvera orb, uses the samvera/ruby executor, and switches to the orb's steps for checkout, bundling, and running rspec.
3. Push it: git add .circleci; git commit -m "Use Samvera Orb"; git push origin master
4. Navigate to the new build and look at the new steps.
5. Restart the workflow using the button in the upper right corner. Notice that the jobs run in less than half the time because the bundle step was cached.

Test multiple configurations using a workflow

1. Open .circleci/config.yml for editing.
2. Replace the hard-coded ruby version in the executor with a parameter:

   build:
     parameters:
       ruby_version:
         type: string
         
     executor:
       name: 'samvera/ruby'
       ruby_version: << parameters.ruby_version >>
   

3. Do the same thing in the samvera/bundle_for_gem step.
4. Now add a workflow that tests current rubies to the bottom of the file:

   workflows:
     version: 2
     ci:
       jobs:
         - build:
             name: "ruby2-4"
             ruby_version: "2.4.9"
         - build:
             name: "ruby2-5"
             ruby_version: "2.5.7"
         - build:
             name: "ruby2-6"
             ruby_version: "2.6.5"
   

5. Push it: git add .circleci; git commit -m "Test multiple rubies"; git push origin master
6. In your browser, look at the workflows index page and click into the new workflow build. Notice that there are now three parallel jobs for each ruby being tested.