Shippable CI

     Shippable is a continuous integration (CI) service that provides support for building, testing and deploying projects from many web-based hosting services for version control, like GitHub, GitLab and Bitbucket. Shippable is available as a Hosted SaaS as well as a Server. In the case of CogniCrypt, it is used as a Hosted SaaS; it operates using a cloud platform and provides a web-based interface to the developer for signing into and configuring their service. The main interest with a CI system like Shippable are regular builds of CogniCrypt. Therefore, a nightly build of CogniCrypt is set up in Shippable.

How to configure the continuous integration (CI)

    The Shippable build process is configured via multiple .yml files. The main file has to be named shippable.yml and needs to be placed at the root of the source code repo, in our case that would be at the root of CogniCrypt repo. Here we can first define the environment, such as the language version, before setting up a pre-ci, ci and post-ci phase. At the end of the build, we are able to trigger certain behavior on success or failure in the aptly-named on success and on failure phases, as seen in the code demo below:

language: #language version like java, javascript, etc

jdk:
  - #specify the JDK version in the case when language is java

build:
  pre_ci:

  pre_ci_boot:
    
  ci:
    - #command1
    - #command2
  post_ci:
    - #command1
    - #command2
  on_success:
    - #command1
    - #command2
  on_failure:
    - #command1
    - #command2

resources:

integrations: 

     The shippable.yml file configures the steps that runCI job will take when building the project. Jobs describe the resources and tasks of a specific build process. We can further configure the runCI job by making use of the two other .yml files, shippable.resources.yml and shippable.jobs.yml.

    The shippable.resources.yml file defines additional resources to be used, such as additional repositories or triggers. These resources can be used as in- or output by the other jobs. In CogniCrypt, the resources YAML that is shown in the code excerpt below is used to define the resource called "nightly-trigger" which triggers the nightly build:

language: java

jdk:
  - oraclejdk8
  
resources:
  - name: nightly-trigger
    type: time
    seed:
      interval: "1 0 * * *"

    The shippable.jobs.yml file defines additional jobs or adds configuration to the runCI job. Here you can define the in- and output of the runCI job and make use of the triggers, such as a time-based trigger for our nightly builds, as an input to start the job. In CogniCrypt, the "nightly-trigger" resource in resources YAML above, is used as input to start the runCI job called "CogniCrypt_runCI" as shown in the code excerpt below of jobs YAML:

language: java

jdk:
  - oraclejdk8
  
jobs:
  - name: CogniCrypt_runCI      # required
    type: runCI                 # required
    steps:                      # required
      - IN: nightly-trigger

How to navigate and work with Shippable

The Shippable homepage shows basic information about the latest builds and the resources used by Shippable. This overview is an important navigation tool, which can be used to access all kinds of information, depending on the task.

An image of the homepage is shown above and the explanation of the most important sections of it are summarized below:

• Jobs: The Jobs section can be considered the most important in the Shippable homepage. This shows the latest builds for the different projects that have been enabled for this subscription, as well as the repository used for the jobs and resources .yml files. This section will be covered in detail later.

• SPOG: This is a real-time, interactive, visual representation of all pipelines across our subscription. Certain resources serve as in- or outputs to these jobs, which in turn can trigger new jobs. Such a chain of resources and jobs is called a pipeline. Pipelines enable Shippable to chain multiple processes such as build and deploy on build success. An image of the SPOG section is shown below:
  
  

• Resources: In this section are the resources that have been defined in the shippable.resources.yml file and the SyncRepo. Here it is possible to see specific information about each resource without having to inspect the YAML. An image of the Resources section is shown below:
  
  

• Orphaned: In the next tab we find the Orphaned section which shows objects that are defined in the shippable.resources.yml, but currently not in use. That means they’re not incorporated into any of the currently defined jobs. The information displayed is similar to the information shown in the regular resource tab.

• Deleted: The next section is called Deleted which shows an overview of the objects that have been soft-deleted. This means that these resources are no longer defined in the shippable.resources.yml. It is possible to completely delete these resources by using the delete button to the far right.

• Insights: The last tab opens the Insights section which is quite descriptive by its name. In here we can query a lot of things like the Total number of Jobs, Total Job Build Duration, and so on. By scrolling down, we can have a more detailed overview as shown by many charts and graphics. An image of this section is shown below:
  
  

The Jobs section

This section takes a closer look at the latest status and the jobs that have been executed. Inspecting the jobs is probably the most important thing when trying to figure out what went wrong with a recent build or if a recently added feature works. The image provided in figure 1 only shows the surface information regarding the completion of jobs and their context. This section will, therefore, elaborate on how to access additional information, such as test reports, coverage reports or build logs. Let's have another view of the Jobs section below:

As mentioned before, all the latest build are shown in this section. Their information is formatted in a table format, as we see above. Each section of this table is summarized below:

• Job #: When selecting the number of an individual build, a summary of that build will be opened, as shown in the image below. This summary is split into 4 different tabs called Console, Tests, Coverage, and Scripts.
  
  

  • Console: The tab containing the Console information displays the output of every action performed during the build. A log of the build can also be downloaded in any tab by selecting the button in the top right of the summary. At first, the individual steps of the build process are collapsed in the console view and can be expanded by clicking the plus icon next to them. To determine the parts in which an error has occurred Shippable provides its user with check marks and crosses to signal passing and failure of an individual step. This way only the faulty step has to be checked for the error that occurred and not the complete log. Probably the most important part of the Console log is the Build CI step, which contains the Maven execution. Expanding it will display the Maven output, which can be used to track down errors in either the code or the build process itself. Since this Maven part contains a lot of information it is advised to speed up the search by first scrolling to the bottom to inspect Maven's summary as shown in the image below:
    
    

  • Tests: The Tests tab, which can be seen in the image below, breaks down the individual tests in a more visually pleasing way and lists the report for failed tests. In our example, there are no failed tests and this hints to the build being successful.
    
    

  • Coverage: The Coverage tab, as shown in the image below, shows which parts of our code are being exercised by tests, and which are not. This is a very important measure, since a program with high test coverage, has had more of its source code executed during testing, which suggests it has a lower chance of containing undetected software bugs compared to a program with low test coverage.
    
    

• Version: This is the next column in the Job section. By selecting the version number, will directly open the Github page (or another platform that is used) containing the respective changes, as seen in the image below:
  
  

• Name: Next, clicking in the Name column, shows a summary page. This page will initially show all the latest builds that were made in this repository from all the branches available. In the next tab called "History", all the builds from the selected repository are sorted from earliest to latest.
  
  

The Account Navigation section

This section covers the functionalities provided by the account navigation bar found on the left of the image shown below. These include managing the accounts integrations and profiles, as well as allowing the user to navigate between the enabled projects and to visit the homepage.

Furthermore, all the tabs of this section are showed in detail:

• Views: Using the View icon gives access to the Home view shown in the picture below. This view allows the user to get an overview of the status of all enabled projects.
  
  

• History: The History page as shown in the picture below, can be accessed using the History icon on the Account Navigation bar. It allows the user to search for specific jobs and resources over the different enabled projects.
  
  

• Profile: The user Profile, which can be seen in the picture below, is accessed using the Profile icon on the left bar. This site contains a button to manually synchronize the account with the source control. This usually happens every four hours, but if waiting is not an option, it can be initiated manually this way. In addition to that, it contains a table showing the user's identities. This page also gives information about the API keys which can be used and the linked payment methods such as credit cards. It is possible to delete a profile at the bottom of the page.
  
  

• Integrations: The picture shown below represents the Integrations page available from the Account Navigation bar. Firstly, a list containing all available integrations is displayed. These integrations contain the Account information necessary for Shippable to authenticate itself for that specific service. By clicking on the "github" shown in the table, opens a new page where we can edit our integration. These details can be changed for the value of the token, the name, and the scope. In addition to that, it is possible to delete an integration with the option found at the bottom of the page. Furthermore, new integrations can be added by using the plus icon, by clicking at the plus icon found in the right-top corner of the page.
  
  

The Subscription Navigation section

The Subscription Navigation bar is another is another important section in Shippable. It is mainly used to enable the user to make additional settings to the Continuous Integration outside of the YAML files. It can be used to add a SyncRepo, enable and disable certain projects and configure which webhooks are supposed to trigger a build. This bar is found in the top-right corner of the Homepage as shown in the picture below. Its main parts are covered in detail subsequently.

• Settings: Using the cogwheel icon, the user is able to alter the different Settings of the subscription. The first option, Node Pools, enables the user to configure the Server node used for the build. As seen in the image below, it is possible to select more powerful nodes, but the access to those depends on the payment plan used. The second option, Integrations, is explained more in detail below. The next one, Settings, the user can edit their contact information and look up the keys used for encryption or deployment.
  
  

  • Integrations: The Integrations option makes it possible to remove or add integrations depending on the need. This is used to add additional repositories that are necessary for the build process, since they store, for example, resources or other needed parts.
    
    

• Enable CI Project: The plus icon is used to enable or disable the projects of that specific subscription and to add SyncRepositories. This leads to the site seen in the image below. The enabling is done by a simple switch. Adding a SyncRepo is not visible in the image mentioned below, but it’s done simply by adding a specific repository branch from an integration.