CircleCI API follow a new project

According to the V1 API documentation (CircleCI API Reference), following a new project API will be deprecated soon and I can’t see the equal API in V2.
Any plan to add this API endpoint V2?


Please vote and subscribe to the CircleCI feature request on this issue which will be updated with the relevant information when available: Add follow project endpoint to v2 API | API | CircleCI Ideas

1 Like

I love Circle, but the whole way “following” projects works seems (to me) very suboptimal. As someone who does infra work (and the recent security incidents are a good example), I often need to do bulk operations on lots of repos. With the current setup:

  • A project won’t build unless it has at least one follower (projects can stop building unexpectedly)
  • The get_projects API endpoint only returns projects that you follow
  • If you’ve ever pushed to a branch in a project you follow, you can’t stop getting notifications about it unless you disable notifications of failed builds for all projects and all branches (also, the notifications settings page where you can do this doesn’t seem to work at all on mobile).

I started working on a simple tool (using GitHub - alpinweis/pycircleci: Python client for CircleCI API) to autofollow projects, both for my own account and for a bot / machine account. But, then found out:

  • If you run follow_project on a project not setup for Circle, it will implicitly start building it (oops)

Ok, so we can get a list of all our github repos, then run get_project for each (non-archived) repo name, but now:

  • If you’d accidentally first done the above for all your projects, but then run “stop building” and remove webhooks / deploy keys, then the get_project API endpoint stops working properly (i.e., it will return data even though the project is no longer setup). I’ve contacted support to delete projects to try and fix this, but that hasn’t worked so far either, even after they confirmed deletion.

High level, IMO, Circle should stop coupling “repos I can see / manage from the API” with “repos I ‘follow’”


Two more ideas to vote for

Actually, found out from support this won’t work either… even if the project has never been built, going to it once will create a db record for it…

i.e, if you go to for a project that’s not setup, reload it at least once, it’ll now be setup, and get_project will now have a record.

they did point me to
which should show all the repos you have the ability to see, at which point you can use "has_followers" : false to infer whether a repo is setup or not.

Hi @wyardley,

Using the "has_followers" : false as an identifier of actual projects is indeed a good idea.

However, it has two caveats:

  • A project could be set up but find itself with no followers at some point (for example, if all followers leave the org)
  • A project that has stopped building remains in CircleCI (unless you explicitly request deletion), even if you delete the related repository in the VCS. And unless you manually removed them, secrets and other configuration settings will still be present.

I found that one way to identify repositories that correspond to actual CircleCI projects (current or past) is to check if CircleCI has knowledge of any branch in the repository.

This info can be found by querying the<project_slug>/settings endpoint, and checking the length of the branches object in the JSON response.

curl "<project_slug>/settings" \
-H "Circle-Token: <api_token> | jq '.branches|length'

If the above command returns a non-zero result, then the repository corresponds to a current or past CircleCI project.

Let me know what you think. Would really appreciate your feedback on this.

N.B: The endpoint will the first page of repos (up to 100) so if the number of repos is indeed number you’ll need to fetch the following page until the page contains less than 100 repos.

@yannCI thanks

Yes, aware of the “not following will stop building” issue - actually, the reason I’m writing this tool is exactly that - to follow repos that we’re “building” under a predictable bot user. So, assuming my script works, as long as it’s run periodically, should not run into that condition.

A project that has stopped building remains in CircleCI

Yeah, that’s what I discovered, and also, even if you’ve never built it, get_repo will show it once someone’s hit it once via a specific page in the Circle UI :disappointed:

so if the number of repos is indeed number you’ll need to fetch the following page until the page contains less than 100 repos

I PRed support for this endpoint upstream to the library I’m using, so should be good on pagination.

High level, I guess I wish Circle would rework how you all think about returning and “building” repos based on API requests; kind of summarized my thoughts in the first “ideas” link above.

Thanks for the other suggestion - I’ll see if it’s trivial to add that as an extra check / guard, though I think using the endpoint above should work for my purposes for now.

1 Like

I’d like to double down on @wyardley’s comments above.
The need to follow a project for CircleCI to start building it coupled with the absence of a “follow a project” API endpoint in v2 is bewildering to me.

How are CircleCI users expected to built automation on top of their CI (e.g. automate creation) in the absence of such APIs?

Also, I had the same issues around a year ago and was coming back now hoping something had been developed in that aread. Alas :confused:

1 Like

Hi all, we have released new API v2 endpoints to create/follow and configure projects programmatically through our API. Let me know what you think!