Run builds on CircleCI using a local config file

Have you ever wanted to try out new changes to your CI configuration without the tedium of pushing new commits and polluting your git history? Here’s a simple technique you can use with CircleCI to quickly try out new iterations of your configuration file. Kicking off builds from your command line using a temporary config file that you can quickly update, test, and iterate. This will keep your git history cleaner, and help you test your CircleCI config faster.

We’ll be using curl to instruct the CircleCI API to kick off a new build using a config file that we provide to it. The command looks like:

curl --user ${CIRCLE_TOKEN}: \
  --request POST \
  --form revision=fa6a8ab9992345e16bbe0515dfb3b56f16f7ce55 \
  --form config=@config.yml \
  --form notify=false \

Four important pieces to making this command work.

  • You need an API key from your CircleCI account. You can create an API token for your account by clicking here. If you want to keep this command saved in a script it’s safest to export your API key to an environment variable export CIRCLE_TOKEN=<API_KEY>, instead of saving it in the script.
  • A git commit hash from your repo that CircleCI can find and pull the code from. You can get this from git log if your local repository has the latest remote changes.
  • A local file in the same working directory as where you’re running the command, with a valid CircleCI configuration in that file.
  • The API URL with the correct username/organization, project name, and branch to run the build under.

If successful when you run this command you’ll get a json response back containing some information about the new build, such as its build number.

Here’s a video tutorial with more details to help you get started:


This should definitely also be a blog post :slight_smile:


Hi @fernfernfern,

Thanks for sharing this. I had no idea that we could ship over the config in the POST request. That is super useful.

Is it possible for that config to include workflows? I.e. will this solution work for CircleCI 2.0 workflows?

Oh, I guess i’m also curious if this way of triggering builds respects all the other features of the platform, e.g. do github status messages get posted on the commit?

Thanks again for sharing.

We don’t have an API to trigger workflows yet, so this won’t work for workflows. Since this totally bypasses Github a lot of our functionality based off their webhooks will be missing. You should only see commit status messages for the builds that were triggered by pushing a commit.

Nothing about testing workflows yet?


I don’t think the API supports that yet. You can see the supported API calls here.


@fernfernfern I’ve used the API with a local config.yml alot in the past days for developing a new pipeline setup and testing individual jobs w/o triggering workflows. was working quite well so far.

however, I now face a weird problem: The local config.yml doesnt seem to be used anymore but the one thats in the git repo I checkout.
No matter what I change in the local config.yml, the API calls response JSON shows me the config in circle_yml key with the content of whats in git.

so I cannot test anymore w/o doing commits all the time.
any idea whats happening here?

A classic, shortly after posting coz you spent some time trying, you find the answer: it was a invalid config.yml

discovered by running the Circle CLIs validate command on it

@nico it would really help if Circle would error out when posting a local config.yml thats invalid instead of silently picking the one thats in repo !! (feature request)


This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.


Reviving this post to share that we’ve introduced a much easier way to run pipelines (yes, entire pipelines, not only individual jobs) based on your local config file.

Full details here: