API to set up a new project



I would like an API for hooking up a repository to CI.

I use a scaffolding tool to create new projects, saving me a lot of time writing boilerplate.

One thing it is able to do is speak to GitHub’s API to set up a repository.

The next logical step is to hook up that repository to CI, but there doesn’t seem to be an API to do so.

What I am looking for is akin to the “Build project” button at circleci.com/add-projects which seems to do this behind the scenes. Although for this particular use case I don’t need to build right away (I leave committing to a manual step, so there are no commits, but the repo is initialized).

In the response I would like at least the URL to the project on Circle.


Hey! Looks like you never got a response here…

We have a internal tool that does exactly what you describe, so I can confirm it’s possible.

We do this by hitting the “follow” endpoint in the CircleCI API
(POST: /project/:vcs-type/:username/:project/follow). To bootstrap a new repo in CircleCI, you’ll need to use a CircleCI token for a user that has Github “admin” permissions for that repo.

As you pointed out, calling “follow” kicks off an initial build (I think there might be a flag you can configure to skip that, but we haven’t done so).


I think we’re actually using the v1.0 CircleCI API, since we’re calling follow via this library https://github.com/jszwedko/go-circleci/blob/master/circleci.go#L215-L224


I just tried it and it does actually work. However, it doesn’t look like it works, at least in my use case, because the API returns a 400 Bad Request when the repo exists but has no commits. That is confusing behavior.

But it turns out that it actually succeeds, in that it will properly run once commits have been pushed. Still, my scaffolding tool will crash because of the 400 unless I wrap it in a try / catch.


Chasing this up, seems like a pretty standard feature. We’re building tooling to migrate some 400 projects over and we don’t plan on going through the web UI to do this.

Any plans to have something out the box for this?