Skip to content

[API] Allowing easier discovery of builds through environments, and thus re-deployment through the API

Description

I'm currently trying to write an external overview page which allows deployment of single environments, all environments and all environments of all projects in a certain group. Accessing the necessary data, i.e. the latest build for any given environment, has been much more difficult then I had hoped, which is why I'm writing this issue. Here are the problems I faced:

  • Environments are somehow missing from the API docs website
  • The /projects/:id/environments endpoint does not provide any of the information one would need to re-deploy a project (most recent pipeline, most recent build). It does, however, provide one with the entire project record in every environment returned by the API, which seems unnecessary given the fact that I can only get the environments from a single project anyway.
  • Accessing the latest build for a stage currently seems possible (through /projects/:id/builds) by relying on the ordering of the results, which seems to be descending by id. Since this isn't documented, I'd be relying on an implementation detail though.
  • The build itself does not have any knowledge of the environment it belongs to. It does know which pipeline it belongs to, but the pipeline does not now the environment either.
  • /projects/:id/builds and /projects/:id/pipelines are sorted descending by ID, /projects/:id/deployments is sorted ascending by ID. No way to change the behavior.

In summary, I currently don't see a way to access the most recent build for a given environment, making it impossible to re-deploy an environment through the API. If there is such a way, it appears to be well hidden. Of course there is the possibility that I've fundamentally misunderstood something, in which case I apologize and kindly request a nudge in the right direction.

Proposal

  1. There could be a /projects/:id/environments/:id/redeploy endpoint
  2. The /projects/:id/environments could return the latest build (id) for that environment,
  3. The /projects/:id/environments/:eid/builds endpoint could return all builds for the given environment (by ID, descending), which would be somewhat consistent with the already existing /projects/:id/repository/commits/:sha/builds endpoint.

All three of these solutions would solve my immediate problem. I personally think that 2 is far inferior to number 3. Number 1 is essentially an API convenience method.

I'd be willing to implement this too, I just didn't want to jump in without discussing possible solutions first 👋🏼