Codebase API Documentation

Merge Requests

You can use the merge requests API to create and manipulate merge requests on a repository. You should be able to perform any interaction using the API that a user can from the web interface.

API URLs

Data Method URL
List all merge requests GET /project/repository/merge_requests
Create a merge request POST /project/repository/merge_requests
Show a single merge request GET /project/repository/merge_requests/merge_request_id
Comment on a merge request POST /project/repository/merge_requests/merge_request_id/comment
Close a merge request POST /project/repository/merge_requests/merge_request_id/close
Reopen a merge request POST /project/repository/merge_requests/merge_request_id/reopen
Perform automatic merge POST /project/repository/merge_requests/merge_request_id/merge
Assign the merge request to a new user POST /project/repository/merge_requests/merge_request_id/reassign

Object Properties

GET /project/repository/merge_requests/merge_request_id

Example is taken from a Show request, a List request will not return the can-merge or comments attributes for performance reasons.

<merge-request>
    <id type="integer">2</id>
    <source-ref>feature-spike</source-ref>
    <target-ref>master</target-ref>
    <subject>Merge Feature Spike</subject>
    <status>new</status>
    <user-id type="integer">5</user-id>
    <created-at type="datetime">2016-09-22T14:06:56Z</created-at>
    <updated-at type="datetime">2016-09-23T11:19:27Z</updated-at>
    <can-merge type="boolean">false</can-merge>
    <comments type="array">
        <comment>
            <content>I'd like to say something</content>
            <user-id type="integer">1</user-id>
            <action nil="true"/>
            <created-at type="datetime">2016-09-22T14:28:41Z</created-at>
        </comment>
        <comment>
            <content>Closing Merge Request</content>
            <user-id type="integer">1</user-id>
            <action>closed</action>
            <created-at type="datetime">2016-09-22T14:33:19Z</created-at>
        </comment>
        <comment>
            <content>Reopening Merge Request</content>
            <user-id type="integer">1</user-id>
            <action>reopen</action>
            <created-at type="datetime">2016-09-22T14:33:59Z</created-at>
        </comment>
        <comment>
            <content>Reopening</content>
            <user-id type="integer">1</user-id>
            <action>reopened</action>
            <created-at type="datetime">2016-09-22T14:34:53Z</created-at>
        </comment>
        <comment>
            <content type="integer">5</content>
            <user-id type="integer">1</user-id>
            <action>reassigned</action>
            <created-at type="datetime">2016-09-23T11:19:27Z</created-at>
        </comment>
    </comments>
</merge-request>
  • source-ref the branch we're merging from
  • target-ref the branch we're merging into
  • subject a brief line explaining the purpose of the merge
  • status the current status of the merge request. One of:
    • new merge request is pending
    • merge branches are currently being merged
    • done branch merged and closed successfully
    • failed branch could not be merged for some reason.
  • user-id user responsible for this merge request
  • can-merge can the branches be automatically merged?
  • comments history of the merge request with any comments that may have been entered with the changes
    • content text content of the comment, or in the case of a reassignment the ID of the user who was assigned
    • user-id user who made the comment
    • action The change that came with this comment (if any). One of reassigned, closed, reopened, merged

Note: When viewing a list of merge requests, comments and can-merge are not included for performance reasons.

Creating a merge request

POST /project/repository/merge_requests

<merge-request>
  <source-ref>feature-spike</source-ref>
  <target-ref>master</target-ref>
  <subject>Feature branch ready for deployment</subject>
</merge-request>

Add a comment:

POST /project/repository/merge_requests/merge_request_id/comment

<comment>
  <content>This looks like a sensible feature to add</content>
</comment>

Mark a request as closed

Optionally pass a comment object to include a comment with the close action.

POST /project/repository/merge_requests/merge_request_id/close

<comment>
  <content>We have merged this manually</content>
</comment>

Reopen a request

Optionally pass a comment object to include a comment with the reopen action.

POST /project/repository/merge_requests/merge_request_id/reopen

<comment>
  <content>We have reopened this merge after some consideration</content>
</comment>

Automatically perform a merge

Optionally pass a comment object to include a comment with the merge.

POST /project/repository/merge_requests/merge_request_id/merge

<comment>
  <content>All looks good. Automerging.</content>
</comment>

Assign the merge request to a new user

POST /project/repository/merge_requests/merge_request_id/merge

<merge-request>
  <user-id>5</user-id>
</merge-request>