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.

• How does CICEE work?

What does CICEE require? What are its dependencies?

• bash: bash shell
• docker: Docker command-line interface
• dotnet: .NET SDK (6.x, 7.x, and 8.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

CICEE .NET Templates

.NET solution templates are available in the Cicee.Templates NuGet package. These templates provide easy templates for repository initialization which follow CICEE conventions.

To install/update, execute:

dotnet new install Cicee.Templates

As of Cicee.Templates version 0.2.0, the following templates are provided:

• cicee-classlib-package: A classlib-based Package Solution
  • This template provides a base for creating libraries, distributed as NuGet packages. It includes: a source project, based upon the classlib template, a unit test project, based upon the xunit template, and CI scripts.
• cicee-webapi-service: A webapi-based Service Solution
  • This template provides a base for creating web APIs, distributed as Docker images. It includes: a source project, based upon the webapi template, unit test and integration test projects, based upon the xunit template, and CI scripts.

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.

dotnet new tool-manifest && dotnet tool install --local cicee && dotnet cicee init repository

This adds:

• a .NET local tool installation of CICEE
• 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.

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.

dotnet 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 init repository). 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. (Use the cicee meta cienv var commands to easily view and modify this configuration.)
• Set up the continuous integration workflow.

Workflow Recipes

Validate Workflow Recipes

• create-react-app Node.js React
• .NET (applies to all currently-supported .NET languages and project types)

Compose Workflow Recipes

Some projects may require only a single recipe, e.g., .NET NuGet packages. Other projects may require multiple, e.g., a React SPA hosted by an ASP.NET application which is distributed as a Docker image.

• AWS CDK cloud assembly
• create-react-app Node.js React
• Docker image
• .NET executable (e.g., ASP.NET application)
• .NET NuGet package
• Zip archive (compress other composed artifacts in preparation for distribution)

Publish Workflow Recipes

• Copy zip archive to AWS S3
• Publish .NET NuGet package
• Push Docker image to AWS ECR
• Push Docker image to Docker Hub

Project Environment Initialization Recipes

• Customize or override build version
• Generate NuGet.config for private NuGet source (e.g., to enable private package sources for dotnet restore)
• Import (bash source) custom environment scripts
• Login to AWS ECR (e.g., to use private images which are hosted in AWS ECR for base image in ci/Dockerfile)

Example Combined Recipes

• NuGet Library / .NET Tool
  • Combines:
    • Validate
      • .NET
    • Compose
      • .NET NuGet package
    • Publish
      • Publish .NET NuGet package
• ASP.NET Docker Image / Self-contained Command Line Tool Docker Image
  • Combines:
    • Validate
      • .NET
    • Compose
      • .NET executable (e.g., ASP.NET application)
      • Docker image
    • Publish
      • Push Docker image to Docker Hub
• AWS CDK application hosting create-react-app SPA
  • Combines:
    • Validate
      • create-react-app Node.js React
    • Compose
      • create-react-app Node.js React
      • AWS CDK cloud assembly
      • Zip archive (compress other composed artifacts in preparation for distribution)
    • Publish
      • Copy zip archive to AWS S3