CI Tool Integration

Shipa supports integrations with the main CI tools used by organizations today and can be leveraged by users to deploy existing applications and code directly on Shipa.

CI integrations are performed using Shipa's CI utility, called shipa-ci, which can be called and run from any standard CI tool available today.

The utility, shipa-ci, can be installed through PIP, the standard package manager for Python, as described below:

$ pip install shipa-ci

Today, shipa-ci is divided into two main sub-components, app and framework, through which users can create, move and update applications and create and update frameworks directly from their CI/CD pipeline.
Below are some of the commands available through shipa-ci

app createCreates an application on Shipa utilizing an existing framework
app moveMoves an existing application between different frameworks
app deployDeploys the application code into an existing Shipa application.

When performing Canary deployments, the following arguments are also available:

--steps: how many steps for the canary deployment
--step-interval: single step duration. Supported min: m, hour:h, second:s. ex. 1m, 60s, 1h
--step-weight: step weight
app removeRemoves an application from Shipa
framework addAdds a framework to Shipa. Users can pass a framework template YAML file with the framework configuration to be added. More information can be found here
framework updateUpdates an existing framework on Shipa

When leveraging shipa-ci, the following arguments are available to authenticate the shipa-ci component inside the CI/CD pipeline with the target Shipa instance:

--serverShipa target server (for example
--emailShipa user email
--passwordShipa user password
--tokenShipa user token
--verboseVerbose output
--caShipa certificate created for your user, which can be found on ~/.shipa/certificates

If the goal is to utilize a token instead of a user and password for authentication, the user token should be created beforehand by running the command token create command. More information can be found on the Tokens page of this manual.

Below you can find some examples when using shipa-ci:

Creating an application:

shipa-ci --server=$SHIPASERVER --email=$SHIPAEMAIL --password=$SHIPAPASSWORD --ca="$CA" app create <app-name> <platform> --team=<team-name> --framework=<framework-name>

Deploying an application (no canary):

shipa-ci --server=$SHIPASERVER --email=$SHIPAEMAIL --password=$SHIPAPASSWORD --ca="$CA" app deploy --app=<app-name>

Canary Deployment

Through shipa-ci, users can take advantage of Canary Deployments, as per the example below:

shipa-ci --server=$SHIPASERVER --email=$SHIPAEMAIL --password=$SHIPAPASSWORD --ca="$CA" app deploy --app=<app-name> --steps=5 --step-interval=1m --step-weight=20

The line above should be included inside your CI/CD pipeline.

More examples are described in the following section.

CI Integration Examples

Below are a couple of examples of integrating Shipa with industry-standard CI tools.

Travis CI:

When integrating Shipa with Travis CI, users should create a .travis.yml file in the code repository of your choice, such as Git. Users can then leverage the .travis.yml file to direct Travis CI to deploy the application to Shipa once the build is confirmed successfully.

Below is an example of a .travis.yml file:

language: python
  - "2.7"

    - stage: build
      script: 'pip install -r requirements.txt && python -m unittest discover'

    - stage: deploy
      script: 'pip install shipa-ci && shipa-ci --server=$SHIPASERVER --email=$SHIPAEMAIL --password=$SHIPAPASSWORD --ca="$CA" app deploy --app=$APP'


Another example of integration is CircleCI. When integrating Shipa with CircleCI, users should create a folder named .circleci in the root directory of their existing Git repositories. Inside this folder, a file called config.yml should be placed, where the integration with Shipa will be described.

Below is an example of a config.yml file for CircleCI:

version: 2 # use CircleCI 2.0
jobs: # A basic unit of work in a run
  build: # runs not using Workflows must have a `build` job as entry point 
    # directory where steps are run
    working_directory: ~/sample
    docker: # run the steps with Docker
      # CircleCI Python images available at:
      - image: circleci/python:3.6.4
    steps: # steps that comprise the `build` job
      - checkout # check out source code to working directory
      - run: sudo chown -R circleci:circleci /usr/local/bin
      - run: sudo chown -R circleci:circleci /usr/local/lib/python3.6/site-packages
      - run: sudo chown -R circleci:circleci ~/sample
      - run: sudo pip install -r requirements.txt && python -m unittest discover
      - run:
          command: |
            sudo pip install shipa-ci
      - run:
          command: |
            sudo shipa-ci --server=$SHIPASERVER --email=$SHIPAEMAIL --password=$SHIPAPASSWORD --ca="$CA" app deploy --app=$APP
      - store_test_results: # Upload test results for display in Test Summary:
          path: test-results
      - store_artifacts: # Upload test summary for display in Artifacts:
          path: test-results
          destination: tr1