Cameo-cicd NPM

cameo-cicd

Resource for reusable CI/CD utilities

Usage

This project is designed to be used in other projects as a library, and also as a stand-alone project.

Usage as a library

To access cameo-cicd functionality in a separate project, you will have to install it as a dependency. To do that, you can navigate to your project directory and run:

npm i --save-dev https://github.com/baronapp/cameo-cicd.git

NOTE: This will require you to have permissions to the Cameo org in GiHub.

Usage as a project

To use cameo-cicd as a stand-alone project, you will want to clone this repository.

It is recommended that you clone this project as a sibling to any other projects that are using it. If not, you may need to set the CAMEO_CICD_PATH environment variable on your machine before utilizing the local/development functionality of this project.

Local development

To run your local cameo-cicd code from another project, you can link your local repository to the other project using the cameo-cicd-version binary.

Coordinating CI/CD changes with feature branches in other repos

Oftentimes, you'll have CI/CD changes that are dependent on work being done in an external feature branch - for example, a new test written for a new feature. In these cases, you'll need to coordinate the releases in both repos to ensure that your code is being tested safely and successfully. Here's a quick run through of a workflow you can use to achieve that:

Step 1: Write your tests

First off, you'll want to prepare your tests in this repo. Create a branch off of master and do your work there - you can validate it by linking and running your tests locally (see Local Development above). Once you've got your tests in good shape, move on to the next step.

Step 2: Connect your CI/CD branch to the feature branch

With your CI/CD branch ready and pushed to GitHub, you can set up your feature branch to point to it directly. This ensures that the appropriate tests (the new ones you just wrote) are running on Circle as you finish up feature work. To do this, get the latest commit hash from your branch, and insert it into the package.json of the feature branch, like so:

# inside package.json, under "devDependencies"

"cameo-cicd": "git+https://cameo-robot:886066b87ac811f8a2eacaf23e6ee4ab9950aff4@github.com/baronapp/cameo-cicd.git#[COMMIT HASH GOES HERE]",

# will look like:
"cameo-cicd": "git+https://cameo-robot:886066b87ac811f8a2eacaf23e6ee4ab9950aff4@github.com/baronapp/cameo-cicd.git#2df9c4d0250327baa5d0999cd0a7631b9faf15d4",

Run npm install to update your package.lock, then push that up to your feature branch. That branch should now be set up to use your new tests.

Step 3: Get everything reviewed

Now that your branches are linked, follow the normal process and have all your work reviewed, in both CI/CD and the feature branch. Once everything is approved, do not merge right away - you need to do a couple more things.

Step 4: Merge your cameo-cicd branch

The next two steps must be done quickly, one after another. You'll be leaving the CI/CD repo in a faulty state for a very short time, so it's important to make sure everything is ready to go before starting.

Once you have all your code reviewed and ready to ship, you'll want to merge your CI/CD branch first. Once the branch is merged to master, follow the standard process for generating a new version (npm run publish). This new version should be all set to test your feature branch.

If someone were to update the original repo to the latest cameo-cicd at that moment, without the changes from your feature branch, they'd start experiencing unexpected failures when cameo-cicd tries to test a feature that isn't there. So it's important to merge the feature ASAP!

Step 5: Update and merge your feature branch

Now that CI/CD has been updated, you need to update the cameo-cicd dependency in your feature branch to point at the new version, and not the commit hash from your merged branch. Do this, then push up the updated package.json and package.lock.json.

Once that's finished and tests are passing, merge your feature branch in to its repo. Congratulations! Your code is shipped, and both repos should be versioned correctly, with the latest code.

Binaries

Because the this project contains functionality that is intended to work on remote CI/CD servers, it exposes its functionality through binaries.

These binaries can be mapped to their source using the "bin" field in package.json.

Usage when cameo-cicd is installed as a library

When you install cameo-cicd as a dependency (or devDependency) to your project, its binaries will be placed in the your-project/node_modules/.bin directory.

You can run these binaries directly using their path, example:

cd my-project && ./node_modules/.bin/my-binary my-command --my-flag

Better yet, you can run them using the NPX library:

cd my-project && npx my-binary my-command --my-flag

When calling an installed binary from within an NPM script, you do not need to provide a path or use NPX. Example:

my-project/package.json

{
  ...
  "scripts": {
    "myscript": "my-binary my-command --my-flag"
  }
}

Manual for a specific binary or command

The binaries in this project are exposed using Yargs, so you can always see documentation on a specific binary or command by using the --help flag.

Examples:

# Executing binary directly
./node_modules/.bin/my-binary --help

# Using NPX to execute binary
npx my-binary my-command --help
npx my-binary --help

# Passing flags to an NPM script
npm run myscript -- --help

Programmatic usage of this project's utilities

A small subset of the functionality of this project is exported for programatic usage.

You can access them from the library's entry:

import { cache, utils } from 'cameo-cicd';

Documentation

The documentation for specific binaries lives in the docs directory.

Contributing to this library

All Cameo developers are encouraged to make contributions to this library!

It is important to remember that this is a versioned library.

After pushing changes to master, you must publish a new version (using npm run publish) before it is available for use in dependent projects.

After publishing your changes, you must also make sure that you update the version of this library that is being used in all dependent projects. At the time of writing this, the dependenct projects of this library are cameoapp and cameoweb.

To manage your cameo-cicd version in dependent projects, use the cameo-cicd-version binary.

If you make any significant changes to the binaries that this library is exporting, make sure you document all new/changed/removed features in the appropriate README!