# CircleCI Convert

A quick and dirty conversion tool for CircleCI 1.0 to CircleCI 2.0 configurations.

## Introduction

This tool will **help** with the conversion of CircleCI 1.0 configurations to CircleCI 2.0.

What this tool will *not* do is create workflows.  This is left at the discression of the user.

## Requirements

* **ruby 2.3.7p456** - tested with the built-in ruby on **macOS** Mojave (10.14.2)
* **circle.rb** - the ruby code for the conversion tool some place you can reference it
* **circle.yml** - a CircleCI 1.0 yaml configuration
* an editor to look at and validate the resulting `config.yml` file

## Quick Start

Assuming you have a project in ./project with the following typical structure:

```
./circle.rb            - The circleci-convert.rb code
./project              - Your Project Directory
./project/circle.yml   - The original circle.yml file
./project/...          - The rest of your project code
```

To convert this project, we need to do a couple things.

First, create a directory `.circleci` in your project;

```
# cd project
# mkdir -p ./circleci
```

Lets move the existing circleci config to something that circle won't try to read;

```
# mv circle.yml old-circle.yml
```

And now, give the conversion tool a run with;

```
# ruby ../circle.rb old-circle.yml > .circle/config.yml
```

At this point, you will have modified your project to a CircleCI 2.0 acceptable configuration.  Now would be a good time to use your prefered code editor and review the changes of `old-circle.yml` compared to `.cirlceci/config.yml` and start to look through for some of the possible issues that the conversion tool doesn't account for.

For the most part, you could check in your code in a branch and see that the CircleCI tests will run as 2.0.

## Common Issues

### ENV Variables with interpolation

In some configurations you will have something like the following in your original `circle.yml`

```
machine:
  node:
    version: 6.9.1
  environment:
    PROJECT_VERSION: ${CIRCLE_SHA1}
    DOCKER_NAME: myproject-container
    DEPLOY_NAME: myproject-app
    SSH_KEY: -i ${HOME}/.ssh/mysecretkey_id_rsa.pub
  services:
    - docker

**[- snip -]**
```

running the conversion tool will result in the following yaml:

```
---
version: 2
jobs:
  build:
    docker:
    - image: circleci/node:6.9.1
      environment:
        PROJECT_VERSION: "${CIRCLE_SHA1}"
        DOCKER_NAME: myproject-container
        DEPLOY_NAME: myproject-app
        SSH_KEY: "-i ${HOME}/.ssh/mysecretkey_id_rsa.pub"
    steps:
    - setup_remote_docker
    - add_ssh_keys
    - checkout
    - run:
        command: 'echo FIXME: please add some command for dependency resolution'
    - run:
        command: 'echo FIXME: please add some command for compilation'
    - run:
        command: 'echo FIXME: please add some command for testing'
```

Unfortunatly, CircleCI 2.0 does not support interpolation of job environment variables.  For example, `PROJECT_VERSION` in the job shell steps will actually contain `"${CIRCLE_SHA1}"` and **NOT** contain the contents of the `CIRCLE_SHA1` environment variable.

The fix for this is to edit the `.config.yml` to the following:

```
---
version: 2
jobs:
  build:
    docker:
    - image: circleci/node:6.9.1
      environment:
        DOCKER_NAME: myproject-container
        DEPLOY_NAME: myproject-app
    steps:
    - setup_remote_docker
    - add_ssh_keys
    - run:
        name: Setup Environment Variables - From CircleCI docs
        command: |-
          echo 'export PROJECT_VERSION="$CIRCLE_SHA1"' >> $BASH_ENV
          echo 'export SSH_KEY="-i ${HOME}/.ssh/mysecretkey_id_rsa.pub"' >> $BASH_ENV
    - checkout
    - run:
        command: 'echo FIXME: please add some command for dependency resolution'
    - run:
        command: 'echo FIXME: please add some command for compilation'
    - run:
        command: 'echo FIXME: please add some command for testing'

```

Key things to notice here;

 - I've moved the two environment variables `PROJECT_VERSION` and `SSH_KEY` to an "early" run step where I `echo` the assignments into an environment script that is executed before each run step which is contained in the ENV var `$BASH_ENV`.
 - I've also removed the references to those variables in the build - environment section.


### SSH Keys

In some cases, project deployments require SSH keys that have been added to the CircleCI project environments.  The convert script detects the most simple usage of SSH keys, however, if your project fails to deploy with complaints about missing keys, you may need to add the build step `add_ssh_keys` early in the build job.

### GCloud docker push - `/var/run/docker.sock` doesn't exist

In the case where your project is using GCLOUD to push a DOCKER image to the GCloud Container Respository, you may find that the `gcloud docker -- push` step in circleci will error complainging that `/var/run/docker.sock` doesn't exist.  This is because CircleCI 2.0 is building your project inside of a docker container and connects to a remote docker host.  You will need to fix with the following:

In your original `circle.yml`, this step probably looks like this:
```
    - sudo gcloud docker -- push gcr.io/myorg/${DOCKER_NAME}:${PROJECT_VERSION}-${CIRCLE_BRANCH}
    - sudo gcloud docker -- push gcr.io/myorg/${DOCKER_NAME}:latest-${CIRCLE_BRANCH}
```

The conversion tool will convert that to the following:

```
    - run:
        command: sudo /opt/google-cloud-sdk/bin/gcloud docker -- push gcr.io/myorg/${DOCKER_NAME}:${PROJECT_VERSION}-${CIRCLE_BRANCH}
    - run:
        command: sudo /opt/google-cloud-sdk/bin/gcloud docker -- push gcr.io/myorg/${DOCKER_NAME}:latest-${CIRCLE_BRANCH}
```

You will need to EDIT that to the following:

```
    - run:
        command: sudo /opt/google-cloud-sdk/bin/gcloud docker --docker-host=$DOCKER_HOST -- --tlsverify --tlscacert $DOCKER_CERT_PATH/ca.pem --tlscert $DOCKER_CERT_PATH/cert.pem --tlskey $DOCKER_CERT_PATH/key.pem push gcr.io/myorg/${DOCKER_NAME}:${PROJECT_VERSION}-${CIRCLE_BRANCH}
    - run:
        command: sudo /opt/google-cloud-sdk/bin/gcloud docker --docker-host=$DOCKER_HOST -- --tlsverify --tlscacert $DOCKER_CERT_PATH/ca.pem --tlscert $DOCKER_CERT_PATH/cert.pem --tlskey $DOCKER_CERT_PATH/key.pem push gcr.io/myorg/${DOCKER_NAME}:latest-${CIRCLE_BRANCH}
```

If you want to go one step further and change this to a single runstep, you can do the following:

```
    - run:
        command: |-
          sudo /opt/google-cloud-sdk/bin/gcloud docker --docker-host=$DOCKER_HOST -- --tlsverify --tlscacert $DOCKER_CERT_PATH/ca.pem --tlscert $DOCKER_CERT_PATH/cert.pem --tlskey $DOCKER_CERT_PATH/key.pem push gcr.io/myorg/${DOCKER_NAME}:${PROJECT_VERSION}-${CIRCLE_BRANCH}
          sudo /opt/google-cloud-sdk/bin/gcloud docker --docker-host=$DOCKER_HOST -- --tlsverify --tlscacert $DOCKER_CERT_PATH/ca.pem --tlscert $DOCKER_CERT_PATH/cert.pem --tlskey $DOCKER_CERT_PATH/key.pem push gcr.io/myorg/${DOCKER_NAME}:latest-${CIRCLE_BRANCH}
```

## CAVEATS

1. Messy, hard to read `config.yml`
Very messy but it is a good starting place for your new circleci workflow.
2. Does not create Workflows
We may fix this in future revisions.  Technically, it creates a workflow with one job and no workflow definition.
3. Deployment step is a big IF ELSE
We may fix this in future revisions.