Cirrus-ci-docs: Allow builds to be programmatically triggered using the GraphQL API

[dbolkensteyn]

The idea is to re-use Cirrus CI's backend capabilities (scheduling of tasks on multiple cloud providers, ability to fetch the logs, etc.) but programmatically. An example of use-case is a "Testing Framework SaaS" (bear with me 😄) that provides infrastructure intensive tests (e..g performance) services to several GitHub repositories within the same organization.

While it is easy to submit jobs or pods using Kubernetes APIs, relying on Cirrus CI comes with the advantage that it supports multiple backends, including GCE for Windows VMs. Moreover, it natively fetches and persists the logs. Finally, developers are already familiar with writing and maintaining .cirrus.yml files to describe how to launch

Today, builds can already be triggered by a bot by creating automated commits or branches on a Cirrus CI enabled GitHub repository. The drawback of this is that it pollutes the Git history. A possible way forward would be to allow to reload an existing .cirrus.yml file, allow it to be altered programmatically, and then submitted for creation.

[dbolkensteyn]

Another use-cases:

• A/B tests different environments (e.g. HDD vs SDD) and measure performances
• Rerun a build 100 times to pro-actively identify flakiness

[fkorotkov]

It's now possible for users (+ button on a repository page). There is a little bit of work left to allow to do it via API Access token to make sure such builds are not counted agains organization seats, etc.

[fkorotkov]

After a bit of refactoring now builds are not required to be associated with only a user and builds created though the API are not counted agains purchased seats in your organization (there is a limit of 60 builds created through the API per organization per hour).