Our merge request API hasn't been updated to support our merge trains feature and public API support is lacking in Merge Train. This means, users cannot automate their workflow via API. Today, users can control via UI, which is manual operation.
We also support merge when pipeline succeeds using the same API mentioned above with an additional merge_when_pipeline_succeeds: true parameter.
In its current state, making a request to the Accept MR API endpoint with merge_when_pipeline_succeeds: true in a project that has merge trains enabled has the same effect as clicking the "Start merge train when pipeline succeeds" button in the UI. This is a bit confusing and not correct.
Proposal
Mirror the changes we made to our internal API in order to support merge trains: gitlab-foss!28595 (merged). Instead of sending a request to the /merge endpoint with merge_when_pipeline_succeeds: true, the endpoint would instead accept a auto_merge_strategy parameter with any of the following value:
merge_when_pipeline_succeeds
add_to_merge_train_when_pipeline_succeeds
If we go this route, we should also update the Get single MR endpoint with a new property, available_auto_merge_strategies, which indicates what auto merge strategies are available.
Permissions and Security
There are no special considerations from a permissions/security standpoint. Existing permissions for who can merge / add to merge train should be respected.
Documentation
The section of our documentation that would be most affected by this change would be the Accept MR API.
The Get single MR endpoint may also need to be updated, depending on our implementation.
This page may contain information related to upcoming products, features and functionality.
It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes.
Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.
I don't think these are the same things @ogolowinski@nfriend @dosuken123. This issue says it's for an API for merge trains, but I think it actually means that when an MR is merged via API it doesn't get added to the merge trains. The other issue Shinya linked to is the one that actually adds an API for interacting with merge trains.
As I think about this a bit more, I think the current behavior actually makes sense. When merge trains are enabled, we always give the user the option to skip the merge train check and merge immediately:
Clicking the "Merge immediately" button shown above is effectively the same as hitting the /merge endpoint through the API. So we're not allowing anything through the API that we don't already allow through the UI.
Because of this I think this issue can be closed. Does that make sense to you all?
The one piece that is still a little odd is that sending merge_when_pipeline_succeeds: true with the API request is interpreted as "add to merge train when pipeline succeeds" if merge trains are enabled. The verbage doesn't line up. @dosuken123 What are your thoughts on this? Is this the correct behavior?
Currently, Public API support is lacking in Merge Train. This means, users cannot automate their workflow via API. Today, users can control via UI, which is manual operation.
The end goal is essentially the same in this issue and #13993 (closed). We want to let users control merge train via API.
@nfriend I think your proposal in the issue description makes sense. We don't currently support add_to_merge_train_when_pipeline_succeeds and merge_train in the /merge MR API, which should be supported as well as an internal endpoint does.
We should extend this endpoint by adding auto_merge_strategy parameter (also return available_auto_merge_strategies too).
FYI, we have a similar problem on Git Push Options (Issue), we'd need to support merge train in this path as well. (Edit: created issue at #32732)
@nfriend I don't mind to keep using this issue as it gets more participants. Feel free to close #13993 (closed) and move some descriptions to this issue.
@dosuken123 Sounds good. Looks like most the information was already ported from the other issue, but I made a few updates to describe our current situation and the changes we want to make.
Would API enablement of merge trains for a project be in scope for this issue as well? I haven't been able to find another issue about API control of merge trains other than this. Right now a it is a manual action to set a project to do pipelines on post merge results.
@ogolowinski this issue has the direction label and %12.7 milestone so is showing up on the kickoff page (https://about.gitlab.com/direction/kickoff/). It doesn't have the Deliverable label, though, so my assumption is this did not make planning. Can you please double check, and either add the Deliverable if it did make planning, or change the milestone if it did not?
@lienvdsteen just told me that people ops engineering is an internal customer for www-gitlab-com. They create automatic MRs onboarding/offboarding people and a human has to intervene.
Added the internal customer label. Could we rethink scheduling this one?
@thaoyeager@v_mishra I removed the weight and workflowready for development as it was reviewed by a different team previously. I think it's something for us to consider on CI and perhaps revisit the proposal. Maybe we can also consider a smaller iteration of this so that we can be more iterative if we wanted to make progress on exploring an API for merge trains.
@cheryl.li you make a good point with planning the iterations for this. IMO this would break into 2 backend issues(but I'm no expert). We should create a separate issue for:
Additional public API support for Merge Train. Here are the proposed endpoints.
GET api/v4/:id/merge_requests/merge_trains ... Get all merge trains in the project
GET api/v4/:id/merge_requests/:merge_request_iid/merge_train ... Get the detail of the merge train
DELETE api/v4/:id/merge_requests/:merge_request_iid/merge_train ... Remove a merge request from a train
@alexkalderimis@cheryl.li I think for "adding a MR to the train" we could extend the existing /merge endpoint to take in input add_to_merge_train_when_pipeline_succeeds:true
For "Add to merge train" (after the pipeline as succeeded), on the UI we use MergeRequestsController#merge! where merge_train is passed as auto_merge_strategy param. We could use the same mechanism as above, but using add_to_merge_train: true or have a dedicated endpoint for Merge Trains API.
These are implementation details but we agree that we need this capability on the API side.
we could extend the existing /merge endpoint to take in input add_to_merge_train_when_pipeline_succeeds:true
My two cents on this is I would prefer an enum over a growing collection of boolean flags (i.e. the way the controller does this seems correct to me). Having flags means dealing with their combinations, and it's just easier to have a single sum-type
I took some time to draft out how this would look in GraphQL, using the MR controller as a guide. It seems fairly straitforward and a working POC can be see at !54758 (merged)
@jreporter What do you think about my proposal to turn this issue into an epic per #32665 (comment 510633678)? We could add 1 more endpoint from the list in the description to also allow us to add an MR to the Merge Train
@cheryl.li - I created the Epic &5864 and added the issues to this splitting them from this proposal. I updated this issue title to reflect a single end point of merging when pipeline succeeds
Why interested: This customer would like to be able to do this programmatically. This is a critical requirement for their long term strategy with GitLab.
Current solution for this problem: The customer is currently using a modified GitHub Gist.
@cupini Thanks for the ping! We do not have plans in H1-FY22 to deliver any merge train features or enhancements but good to know of customer interest in this for future planning.
I just tried the merge_when_pipeline_succeeds: true mentioned in the description and it does NOT have the same effect as clicking "Start merge train when pipeline succeeds". Even though merge trains are enabled, the effect is to either merge immediately if a pipeline has already completed or to set the state to "merged automatically when the pipeline succeeds”. I did not find a way to get a merge train pipeline started by passing merge_when_pipeline_succeeds: true.
We use an automated dependency management tool to keep our dependencies up to date.
We would like to enable the tool to automatically merge MRs if they pass tests, but we utilize merge trains and there is no way to programmatically add an MR to a merge train.
This GitLab.org issue (#32665) describes a potential solution. We would like to strongly request the work outlined in that issue is prioritized ASAP.
~400 seat silver customer here. When is this going to be scheduled? We just discovered this limitation and it's blocking important automation we need to implement.
Will check @alexkalderimis. AFAIK we've never used the GraphQL API before. It's unfortunate to have to an entirely different API for this one missing feature of the REST API.
Happy to help if you need pointers @arcesium-george . GraphQL is just a normal HTTP POST request, so it is fairly simple to make single requests using the same tools you use to call REST endpoints, so hopefully it will not be too onerous to make use of
Is the GraphQL API only permitted to be accessed via Personal Access Token and not via Project Access Token? From the docs, it's unclear if access via Project Access Token is permitted or not?
Excerpt from the docs; emphasis mine.
A GraphQL request can be made as a POST request to /api/graphql with the query as the payload. You can authorize your request by generating a personal access token to use as a bearer token.
My Project Access Token has read_api, api, read_repository and write_repository permission(s). I'm only able to perform query / mutation as my user using GraphQL Explorer. But, trying to use Project Access Token via both Authorization: Bearer <> and PRIVATE-TOKEN : <> is not working.
I would need to confirm, but my understanding is that GraphQL does not support project access tokens yet. Please see #255354 (closed) for discussion of this limitation.
Is using the GraphQL API an acceptable alternative workaround for you, @arcesium-george ?
No, not if GraphQL does not support project tokens.
It's a bit disappointing to me that many Gitlab features are only partially implemented. I can understand a gap between the release of an MVP and full support for a new feature, but I'd expect that gap to be limited in duration, and I'd expect the MVP to be marketed as an MVP (rather than a feature offering). This ticket has been open since September 2019, which is way too long for something as simple and important as API support.
We are gold seat customers and I'm really unhappy we cannot automate merge trains by adding some auto-merge concept because we cannot trigger a merge train using the API. Bitbucket/Jenkins can easily run pipelines that have all the approvals and merge the pull request but with Gitlab that is impossible.
When this feature is planned to be added to the mainline?
No, not if GraphQL does not support project tokens.
I just wanted to mention here that support for project access tokens has been added in the GraphQL API in 16913601 as part of !82316 (merged) , and is available in %14.9