CircleCi Orb - cospirit/deploy

Main orb used to deploy CoSpirit applications. Build, test, and publish orbs automatically on CircleCI with Orb-Tools.

Orb Development Pipeline

This configuration file uses orb-tools orb version 10 to automatically pack, test, and publish CircleCI orbs using this project structure. View the comments within the config file for a full break down

Overview:

Imported Orbs

Both orb-tools and a development version of your orb will be imported into the config. On the first run, a dev:alpha development tag must exist on your orb, but will be handled automatically from there on.

Jobs

In the jobs key, you will define integration tests. These jobs will utilize the functionality of your orb at run-time and attempt to validate their usage with live examples. Integration tests can be an excellent way of determining issues with parameters and run-time execution.

Workflows

The default .circleci/config.yml file contains the configuration code needed to automatically pack, test, and deploy and changes made to the contents of the orb source in this directory.

@orb.yml

This is the entry point for our orb "tree", which becomes our orb.yml file later.

Within the @orb.yml we generally specify 4 configuration keys

Keys

1. version Specify version 2.1 for orb-compatible configuration version: 2.1
2. description Give your orb a description. Shown within the CLI and orb registry
3. display Specify the home_url referencing documentation or product URL, and source_url linking to the orb's source repository.
4. orbs (optional) Some orbs may depend on other orbs. Import them here.

There are two workflows which automate the pack, test, and publishing process.

test-pack

This is the first of the two workflows run. This workflow is responsible for any testing or prepping prior to integration tests. This is where linting occurs, shellchecking, BATS tests, or anything else that can be be tested without the need for further credentials.

This Workflow will be placed on hold prior to publishing a new development version of the orb (based on this commit), as this step requires access to specific publishing credentials.

This allows users to fork the orb repository and begin the pipeline, while the code-owners review that the code is safe to test in an environment where publishing keys will be present.

Once approved, the development version of the orb will publish and the trigger-integration-tests-workflow job will run, kicking off the next workflow

integration-test_deploy

The second and final workflow is manually triggered by the trigger-integration-tests-workflow job. In this run, the development version of the orb that was just published will be imported, and the integration tests will run.

When running on the master branch (after merging to master), the workflow will additionally publish your new production orb.

Resources

• Orb Author Intro
• Reusable Configuration
• CircleCI Orb Registry Page - The official registry page of this orb for all versions, executors, commands, and jobs described.
• CircleCI Orb Docs - Docs for using and creating CircleCI Orbs.

How to Contribute

We welcome issues to and pull requests against this repository!

How to Publish

• Create and push a branch with your new features.
• When ready to publish a new production version, create a Pull Request from feature branch to master.
• The title of the pull request must contain a special semver tag: [semver:<segement>] where <segment> is replaced by one of the following values.

Increment	Description
major	Issue a 1.0.0 incremented release
minor	Issue a x.1.0 incremented release
patch	Issue a x.x.1 incremented release
skip	Do not issue a release

Example: [semver:major]

• Squash and merge. Ensure the semver tag is preserved and entered as a part of the commit message.
• On merge, after manual approval, the orb will automatically be published to the Orb Registry.

For further questions/comments about this or other orbs, visit the Orb Category of CircleCI Discuss.

Executors

Easily author and add Parameterized Executors to the src/executors directory.

Each YAML file within this directory will be treated as an orb executor, with a name which matches its filename.

Executors can be used to parameterize the same environment across many jobs. Orbs nor jobs require executors, but may be helpful in some cases, such as: parameterizing the Node version for a testing job so that matrix testing may be used.

View the included hello.yml example.

description: >
  This is a sample executor using Docker and Node.
docker:
  - image: 'cimg/node:<<parameters.tag>>'
parameters:
  tag:
    default: lts
    description: >
      Pick a specific circleci/node image variant:
      https://hub.docker.com/r/cimg/node/tags
    type: string

See:

• Orb Author Intro
• How To Author Executors
• Node Orb Executor

Jobs

Easily author and add Parameterized Jobs to the src/jobs directory.

Each YAML file within this directory will be treated as an orb job, with a name which matches its filename.

Jobs may invoke orb commands and other steps to fully automate tasks with minimal user configuration.

View the included hello.yml example.

  # What will this job do?
  # Descriptions should be short, simple, and clear.
  Sample description
executor: default
parameters:
  greeting:
    type: string
    default: "Hello"
    description: "Select a proper greeting"
steps:
  - greet:
      greeting: << parameters.greeting >>

See:

• Orb Author Intro
• How To Author Commands
• Node Orb "test" Job

Commands

Easily add and author Reusable Commands to the src/commands directory.

Each YAML file within this directory will be treated as an orb command, with a name which matches its filename.

View the included greet.yml example.

description: >
  Replace this text with a description for this command.
  # What will this command do?
  # Descriptions should be short, simple, and clear.
parameters:
  greeting:
    type: string
    default: "Hello"
    description: "Select a proper greeting"
steps:
  - run:
      name: Hello World
      command: echo << parameters.greeting >> world

See:

• Orb Author Intro
• How to author commands

scripts/

This is where any scripts you wish to include in your orb can be kept. This is encouraged to ensure your orb can have all aspects tested, and is easier to author, since we sacrifice most features an editor offers when editing scripts as text in YAML.

As a part of keeping things seperate, it is encouraged to use environment variables to pass through parameters, rather than using the << parameter. >> syntax that CircleCI offers.

tests/

This is where your testing scripts for whichever language is embeded in your orb live, which can be executed locally and within a CircleCI pipeline prior to publishing.

Including Scripts

Utilizing the circleci orb pack CLI command, it is possible to import files (such as shell scripts), using the <<include(scripts/script_name.sh)>> syntax in place of any config key's value.

# commands/greet.yml
description: >
  This command echos "Hello World" using file inclusion.
parameters:
  to:
    type: string
    default: "World"
    description: "Hello to who?"
steps:
  - run:
      environment:
        PARAM_TO: <<parameters.to>
      name: Hello <<parameters.to>
      command: <<include(scripts/greet.sh)>>

# scripts/greet.sh
Greet() {
    echo Hello ${PARAM_TO}
}

# Will not run if sourced from another script. This is done so this script may be tested.
# View src/tests for more information.
if [[ "$_" == "$0" ]]; then
    Greet
fi

Testing Orbs

This orb is built using the circleci orb pack command, which allows the command logic to be separated out into separate shell script .sh files. Because the logic now sits in a known and executable language, it is possible to perform true unit testing using existing frameworks such a BATS-Core.

Example command.yml

description: A sample command

parameters:
  source:
    description: "source path parameter example"
    type: string
    default: src

steps:
  - run:
      name: "Ensure destination path"
      environment:
        ORB_SOURCE_PATH: <<parameters.source>>
      command: <<include(scripts/command.sh)>>

Example command.sh

CreatePackage() {
    cd "$ORB_SOURCE_PATH" && make
    # Build some application at the source location
    # In this example, let's assume given some
    # sample application and known inputs,
    # we expect a certain logfile would be generated.
}

# Will not run if sourced from another script.
# This is done so this script may be tested.
if [[ "$_" == "$0" ]]; then
    CreatePackage
fi

We want our script to execute when running in our CI environment or locally, but we don't want to execute our script if we are testing it. In the case of testing, we only want to source the functions within our script,t his allows us to mock inputs and test individual functions.

A POSIX Compliant Source Checking Method:

# Will not run if sourced for bats.
# View src/tests for more information.
TEST_ENV="bats-core"
if [ "${0#*$TEST_ENV}" == "$0" ]; then
    RUN CODE
fi

Example command_tests.bats

BATS-Core is a useful testing framework for shell scripts. Using the "source checking" methods above, we can source our shell scripts from within our BATS tests without executing any code. This allows us to call specific functions and test their output.

# Runs prior to every test.
setup() {
    # Load functions from our script file.
    # Ensure the script will not execute as
    # shown in the above script example.
    source ./src/scripts/command.sh
}

@test '1: Test Build Results' {
    # Mock environment variables or functions by exporting them (after the script has been sourced)
    export ORB_SOURCE_PATH="src/my-sample-app"
    CreatePackage
    # test the results
    grep -e 'RESULT="success"' log.txt
}

Tests can contain any valid shell code. Any error codes returned during a test will result in a test failure.

In this example, we grep the contents of log.txt. which should contain a success result if the CreatePackage function we had loaded executed successfully.

See:

• BATS Orb
• Orb Testing CircleCI Docs
• BATS-Core GitHub

Usage Examples

Easily author and add Usage Examples to the src/examples directory.

Each YAML file within this directory will be treated as an orb usage example, with a name which matches its filename.

View the included example.yml example.

Usage examples should contain clear use-case based example configurations for using the orb.

See:

• Providing Usage examples