README

Tarragon

Tarragon executes Codefresh script files (Codefresh YAMLs) locally and autonomously, to produce artifacts and metadata streams.

Demo

Installation

npm install tarragon -g

You can also run tarragon without pre-installing it, by using npx: npx tarragon ...

Usage

Output formats

Tarragon can output reports in two formats: colorful and metalog. It can be specified using the --output option.

colorful - A textual color interface
metalog - Stream of JSON lines (useful for automation clients)

Example: tarragon my.yaml --output=metalog

Volume

Tarraon provides a local volume (aka "Codefresh Volume") that is shared across all execution steps of the Codefresh YAML. This volume is available through the built-in Codefresh argument named CF_VOLUME_PATH. Everything you store under in path will persist during execution.

Example: You can store your cloned repo in CF's volume /repos/demochat folder by writing the following step:

    clone:
        type: git-clone
        title: Clone Demochat Repo
        description: Clones Demochat repository into local volume
        working_directory: ${{CF_VOLUME_PATH}}/repos/demochat
        repo: https://github.com/codefresh-io/demochat.git
        revision: ${{CF_BRANCH}}
        credentials:
          username: myusername
          password: supersecretpassword
        fail_fast: false

The contents of this volume can, for example, later be accessed through the subsequent "freestyle" step:

 type: freestyle
    title: Install NPM dependencies
    working_directory: ${{CF_VOLUME_PATH}}/repos/demochat
    image: node
    commands:
      - npm install

Using your local context as Volume

Your Codefresh Volume can be pre-populated with content from your local filesystem. To do so, use the import-volume-from option.

Example: tarragon my.yaml --import-volume-from=.

Instructs Tarragon to use your current folder as a Codefresh volume.

Examples

You can use Tarragon to test your locally-available Codefresh YAML files. Here are a few examples:

tarragon my-yaml.yaml --args CF_BRANCH=master

Executes my-yaml.yaml, and set the run-time arguments "CF_BRANCH" used within it.

cat my-yaml.yaml | tarragon - --args CF_BRANCH=master CF_CUSTOM=something

Executes my-yaml.yaml, provided through stdin, and set two run-time arguments: "CF_BRANCH" and "CF_CUSTOM"

Dependencies

The steps "freestyle", "freestyle-combo", "git-clone", "build" and "composition" requires Tarragon to connect to a Docker engine. If your codefresh.yaml depends on one of these, make sure to pass either

docker-engine-socker-path
Or docker-engine-url + docker-engine-tls-folder (the folder where key/ca/cert .pem files are located)

To Tarragon:

tarragon mycodefresh.yaml --docker-engine-socket-path=/var/run/docker.sock

Or have the following environment variables set respectively: DOCKER_ENGINE_SOCKET_PATH, DOCKER_ENGINE_URL, DOCKER_ENGINE_TLS_FOLDER

If you have the set of env vars provided by docker-machine env, they will be automatically used for this purpose.
If no other settings were defined, Tarragon will also try to connect to Docker using the "/var/run/docker.sock" socket, unless you disable it by setting docker-socket-auto-connect to false.

The following examples assume these environment variables are set:

tarragon mycodefresh.yaml --arg CF_BRANCH=master

Executes mycodefresh.yaml, and passes CF_BRANCH as an argument. Arguments are merged into codefresh.yaml fields:

...
  version: '1.0'
  steps:
    clone_project:
      type: git-clone
      title: Clone UI
      description: v1.4.45
      working_directory: ${{CF_VOLUME_PATH}}/repos/alert_handler
      repo: https://github.com/codefresh-io/demochat.git
      fail_fast: false
      revision: ${{CF_BRANCH}}
...

Usage no npm install needed!