cicee 1.4.0

Continuous Integration Containerized Execution Environment (CICEE)

What is CICEE?

CICEE is an opinionated orchestrator of continuous integration processes. CICEE executes commands in a Docker container, using the files in your project repository, and provides a convention-based structure for fulfilling dependencies.

CICEE also provides a continuous integration shell function library to support the use of shell script-based continuous integration workflows.

What does CICEE require? What are its dependencies?

• bash: bash shell
• docker: Docker command-line interface
• docker-compose: Docker Compose command-line interface (compose file version 3.7 support required)
• dotnet: .NET runtime (6.x supported)

Why use CICEE?

CICEE users' most common use cases:

• Validating project code, e.g., during a pull request review, consistently on both developer workstations and continuous integration servers.
• Assembling distributable artifacts, e.g., Docker images or NPM packages.
• Running integration tests requiring dependencies, e.g., databases.
• Executing code cleanup, linting, reformatting, or other common development workflows, without prior tool installation.

How do you use CICEE?

• Installation or update
• What Files and Directories Does CICEE Require?
• Using cicee

Quickstart

Step 0: Install CICEE

dotnet tool install -g cicee

If you already have CICEE installed, but want to update to the latest release:

dotnet tool update -g cicee

Step 1: Add a Continuous Integration Containerized Execution Environment

Open a Bash terminal session in the root directory of the project.

Execute cicee init repository.

cicee init repository

This adds:

• a Dockerfile which will provide all the tools needed to perform the project's continuous integration tasks.
• docker-compose files which define the continuous integration containerized execution environment.
• a small, flexible continuous integration workflow template. Three initial workflows are provided:
  • compose: Create the project's distributable artifacts. For example, render SASS to CSS, compile source code, build docker images, compress zip archives, package for NPM, etc.
  • publish: Publish the project's distributable artifacts to their repositories. For example, push docker images, publish a package to NuGet, etc.
  • validate: Validate the current project for correctness, completeness, or other rules. Supports automated checks which should be executed during pull request review.

(Optional Alternative) Include CICEE Shell Library

CICEE's core runtime ability is cicee exec: executing a specified Docker entrypoint and command within the continuous integration containerized execution environment. However, that requires a cicee installation.

By installing the CICEE shell library, the same cicee exec process can be performed without installing cicee. For example, on a continuous integration build server.

Execute this alternative cicee init repository command, which uses the --ci-lib option to include the CICEE CI library.

cicee init repository --ci-lib

Step 2: Try It Out

Open a Bash terminal session in the root directory of the project.

Execute cicee exec and provide one of the CI workflow entry points.

cicee exec --entrypoint ci/bin/validate.sh

Next Step

• Update continuous integration configuration. This is normally done in project-metadata.json (which was created by cicee template init). However, if there is no project-metadata.json, CICEE will read NPM's package.json, if present.
  • Update the project's name and description, if needed.
  • Update the current Major.Minor.Patch version.
  • Configure required environment variables and defaults.
• Set up the continuous integration workflow.