I’ve already posted about the general issues I’ve found with the API docs, but the detailed issues regarding doing this ‘simple’ task provide a more detailed example of the complications that can arise from the current docs and API structure.
-
If you start searching for a solution using the term ‘job’ rather than ‘pipeline’ you are likely to end up at
https://circleci.com/docs/2.0/api-job-trigger/
The header message here is of little help as the link to Pipline endpoints is somewhat broken - see note below. I’m not even sure that this API endpoint will work as there have been other posts stating that this interface was dropped in 2020, which if true should be clearly indicated in the docs.
https://circleci.com/blog/a-deprecation-notice-on-job-triggering-with-api-v1-1/
-
Once you work out all of the above you have to go off and start searching on the term ‘pipelines’, with most hits landing within the robo docs of the API, which do not contain any detail or links to detail. With more searching you can find a few blog posts, comments here and a snippet example in the API docs
https://circleci.com/docs/2.0/api-developers-guide/
What you can not find is any reference to this endpoint within the robo docs of the API under the Project subsection! Instead due to a misreading of the project_slug someone has managed to place this project API into the Pipeline subsection rather than the Project subsection.
- The security of the API is something of a mess at the moment as it requires a Personal API Token, so anyone who can start a pipeline also gains the ability to rather a lot more on the system. This can be managed within a developed application but leaves the Token as plan text within any config.yml jobs.
Please can you
- Tidy up the general docs so that the old API clear states that it is EOL and points users to clear documentation on the new API
- Fix the robo API docs so that the endpoint is placed In the correct subsection.
- Consider providing a command within the config.yml language to start a workflow and an API/GUI interface that simply expresses the concept that workflow A can be started by workflow B.
- Support environment variables in at least some parts of the config.yml language command set with the command requested above being one example, so that parameters can be passed around.
There are a lot of powerful features within the CircleCI platform, but it can be painful to find them and even more painful to get to the point where you can deploy them at the moment.
The security issue of having a visible Personal API Token impacts our ability to isolate developers from certain aspects of our build system. Currently, our best solution seems to be that Workflow B makes a change to a branch in a Bitbucket repository that then causes Workflow A to start. While this provides full isolation it is a daft thing to implement.