Activate new branch on generic VCS repo

[seignovert]

Based on the docs, it is possible to active automatically new branch from a pull request with github and gitlab.com repositories (which works great!).

For generic VCS repo, it should be possible to create a generic API integration and automation rules to achieve the same thing.

Automation Rule

Description: Activate and hide new branches Match: Custom match Custom match: .* Version type: Branch Action: Hide version

Current issue

When a new branch is created on the repo and the CI trigger a webhook for that new branch:

curl \
    -X POST \
    -d "token=<token>" \
    -d "branches=<branch_slug>" \
    https://readthedocs.org/api/v2/webhook/<project_slug>/1/

RTD returns an empty versions array and does not trigger a new build:

{
  "build_triggered": false,
  "project": "<project_slug>",
  "versions": []
}

Workaround

If you send a webhook on the latest branch (or any already activated branch), RTD will realize that there is a new branch and will activate and build it (thanks to the automation rule above). Unfortunately this approach trigger an unnecessary build of the latest branch. As soon as the new branch is activated, the webhook works as intended and versions response contains the branch_slug.

Possible solution

Would it be possible to check the repo when an unknown branches is provided (rather than only looking at the versions already available on RTD which don't contain the new branch)?

API approach

I also tried to manually update the list of versions with the API:

curl \
    -X PATCH \
    -H "Authorization: Token <token>" \
    https://readthedocs.org/api/v3/projects/<project_slug>/versions/<branch_slug>/ \
    -d '{"activate": true, "hidden": true}'

but I get:

{"detail":"Not found."}

when the branch is unknown.

[stsewd]

Looks like what we are missing is a webhook where users can notify that a project needs to re-sync its versions, we could re-use the current one, but passing the "event" (create/delete/updated).