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 (aworkflows
stanza is not generated byconfig-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
-
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. -
To use the
config-translation
from your browser when you are authenticated incircleci.com
for a repository calledfoo
in a GitHub org namedbar
, request this URL in your browser:https://circleci.com/api/v1.1/project/github/bar/foo/config-translation
-
To use the
config-translation
from your browser when you are not authenticated in circleci.com for a repository calledfoo
in a GitHub org namedbar
, request the following URL and pass yourcircle-token
directly in the query string. The following example calls this withcurl
, passes thebranch
to translate, and assumes your CircleCI API token is in an environment variable calledCIRCLE_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
.