Getting Started

Using the 1.0 to 2.0 config-translation Endpoint

This document provides instructions for using the config-translation endpoint to generate a basic working CircleCI 2.0 configuration from your existing CircleCI 1.0 project for a limited set of languages:

  • Ruby
  • PHP
  • Node.js
  • iOS (partial: 1.0 code signing is not supported - use Fastlane instead)
  • Java (partial)

The generated config-translation file includes comments to help you understand how to modify the configuration for use as the .circleci/config.yml in your CircleCI 2.0 project.

Warning: Do not use the generated configuration file in production without testing. There are structures in 1.0 that cannot be reconciled in the 2.0 configuration, so it is important to put the generated configuration file on a branch, test it, and modify it before going to production. Results may vary significantly from your 1.0 results with the draft configuration generated with config-translation.

Overview

The config-translation endpoint will help you generate a draft 2.0 configuration file from your CircleCI 1.0 project. Major differences exist between CircleCI 1.0 and 2.0 as follows:

  • All configuration must be explicitly declared in a .circleci/config.yml file in your repository.
  • CircleCI 2.0 introduces Workflows to orchestrate builds that are comprised of multiple jobs with steps. Workflows enable you to find failures faster by breaking up a build into multiple jobs. You must add a new stanza to your config.yml file to enable Workflows (a workflows stanza is not generated by config-translation). See Orchestrating Workflows for instructions and examples.

The config-translator endpoint does not currently support translation of the deploy step of 1.0 builds, so you must also add a new job for deployment. See the Deployment Integrations documentation for CircleCI 2.0 for details and examples.

Using config-translation

  1. To use the config-translation, use the following API endpoint passing the name of your CircleCI project building on 1.0.

    GET: /project/:vcs-type/:username/:project/config-translation

    The above endpoint uses the build history of your 1.0 project to generate a config-translation file.

  2. To use the config-translation from your browser when you are authenticated in circleci.com for a repository called foo in a GitHub org named bar, request this URL in your browser:

    https://circleci.com/api/v1.1/project/github/bar/foo/config-translation

  3. To use the config-translation from your browser when you are not authenticated in circleci.com for a repository called foo in a GitHub org named bar, request the following URL and pass your circle-token directly in the query string. The following example calls this with curl, passes the branch to translate, and assumes your CircleCI API token is in an environment variable called CIRCLE_TOKEN.

      curl -H "Circle-Token: $CIRCLE_TOKEN" "https://circleci.com/api/v1.1/project/github/bar/foo/config-translation?branch=develop"

    The default is to use the default branch that is set in your VCS, typically master.

See also

Tips For Migrating from 1.0 to 2.0