# Merge a branch

From **GitHub v3 REST API**.

`POST /repos/{owner}/{repo}/merges`

Merge a branch

## Parameters

### `owner`

- Location: path
- Required: true
- Type: `string`

### `repo`

- Location: path
- Required: true
- Type: `string`

## Request body

- Required: true
### `application/json`

- Type: `object`

```json
{
  "base": "master",
  "commit_message": "Shipped cool_feature!",
  "head": "cool_feature"
}
```

```json
{"properties":{"base":{"description":"The name of the base branch that the head will be merged into.","type":"string"},"commit_message":{"description":"Commit message to use for the merge commit. If omitted, a default message will be used.","type":"string"},"head":{"description":"The head to merge. This can be a branch name or a commit SHA1.","type":"string"}},"required":["base","head"],"type":"object"}
```

## Responses

### `201`

Successful Response (The resulting merge commit)

### `application/json`

- Type: `object`

Commit

```json
{
  "author": {
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "gravatar_id": "",
    "html_url": "https://github.com/octocat",
    "id": 1,
    "login": "octocat",
    "node_id": "MDQ6VXNlcjE=",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "site_admin": false,
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "type": "User",
    "url": "https://api.github.com/users/octocat"
  },
  "comments_url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e/comments",
  "commit": {
    "author": {
      "date": "2011-04-14T16:00:49Z",
      "email": "mona@github.com",
      "name": "Monalisa Octocat"
    },
    "comment_count": 0,
    "committer": {
      "date": "2011-04-14T16:00:49Z",
      "email": "mona@github.com",
      "name": "Monalisa Octocat"
    },
    "message": "Fix all the bugs",
    "tree": {
      "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "url": "https://api.github.com/repos/octocat/Hello-World/tree/6dcb09b5b57875f334f61aebed695e2e4193db5e"
    },
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "verification": {
      "payload": null,
      "reason": "unsigned",
      "signature": null,
      "verified": false
    }
  },
  "committer": {
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "gravatar_id": "",
    "html_url": "https://github.com/octocat",
    "id": 1,
    "login": "octocat",
    "node_id": "MDQ6VXNlcjE=",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "site_admin": false,
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "type": "User",
    "url": "https://api.github.com/users/octocat"
  },
  "files": [
    {
      "additions": 10,
      "blob_url": "https://github.com/octocat/Hello-World/blob/7ca483543807a51b6079e54ac4cc392bc29ae284/file1.txt",
      "changes": 12,
      "deletions": 2,
      "filename": "file1.txt",
      "patch": "@@ -29,7 +29,7 @@\n.....",
      "raw_url": "https://github.com/octocat/Hello-World/raw/7ca483543807a51b6079e54ac4cc392bc29ae284/file1.txt",
      "status": "modified"
    }
  ],
  "html_url": "https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "node_id": "MDY6Q29tbWl0NmRjYjA5YjViNTc4NzVmMzM0ZjYxYWViZWQ2OTVlMmU0MTkzZGI1ZQ==",
  "parents": [
    {
      "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e"
    }
  ],
  "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "stats": {
    "additions": 104,
    "deletions": 4,
    "total": 108
  },
  "url": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e"
}
```

```json
{"description":"Commit","properties":{"author":{"$ref":"#/components/schemas/nullable-simple-user"},"comments_url":{"example":"https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e/comments","format":"uri","type":"string"},"commit":{"properties":{"author":{"$ref":"#/components/schemas/nullable-git-user"},"comment_count":{"example":0,"type":"integer"},"committer":{"$ref":"#/components/schemas/nullable-git-user"},"message":{"example":"Fix all the bugs","type":"string"},"tree":{"properties":{"sha":{"example":"827efc6d56897b048c772eb4087f854f46256132","type":"string"},"url":{"example":"https://api.github.com/repos/octocat/Hello-World/tree/827efc6d56897b048c772eb4087f854f46256132","format":"uri","type":"string"}},"required":["sha","url"],"type":"object"},"url":{"example":"https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e","format":"uri","type":"string"},"verification":{"$ref":"#/components/schemas/verification"}},"required":["author","committer","comment_count","message","tree","url"],"type":"object"},"committer":{"$ref":"#/components/schemas/nullable-simple-user"},"files":{"items":{"$ref":"#/components/schemas/diff-entry"},"type":"array"},"html_url":{"example":"https://github.com/octocat/Hello-World/commit/6dcb09b5b57875f334f61aebed695e2e4193db5e","format":"uri","type":"string"},"node_id":{"example":"MDY6Q29tbWl0NmRjYjA5YjViNTc4NzVmMzM0ZjYxYWViZWQ2OTVlMmU0MTkzZGI1ZQ==","type":"string"},"parents":{"items":{"properties":{"html_url":{"example":"https://github.com/octocat/Hello-World/commit/7638417db6d59f3c431d3e1f261cc637155684cd","format":"uri","type":"string"},"sha":{"example":"7638417db6d59f3c431d3e1f261cc637155684cd","type":"string"},"url":{"example":"https://api.github.com/repos/octocat/Hello-World/commits/7638417db6d59f3c431d3e1f261cc637155684cd","format":"uri","type":"string"}},"required":["sha","url"],"type":"object"},"type":"array"},"sha":{"example":"6dcb09b5b57875f334f61aebed695e2e4193db5e","type":"string"},"stats":{"properties":{"additions":{"type":"integer"},"deletions":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"url":{"example":"https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e","format":"uri","type":"string"}},"required":["url","sha","node_id","html_url","comments_url","commit","author","committer","parents"],"title":"Commit","type":"object"}
```

### `204`

Response when already merged

### `403`

Forbidden

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

### `404`

Not Found when the base or head does not exist

### `409`

Conflict when there is a merge conflict

### `422`

Validation failed

### `application/json`

- Type: `object`

Validation Error

```json
{"description":"Validation Error","properties":{"documentation_url":{"type":"string"},"errors":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"index":{"type":"integer"},"message":{"type":"string"},"resource":{"type":"string"},"value":{"oneOf":[{"nullable":true,"type":"string"},{"nullable":true,"type":"integer"},{"items":{"type":"string"},"nullable":true,"type":"array"}]}},"required":["code"],"type":"object"},"type":"array"},"message":{"type":"string"}},"required":["message","documentation_url"],"title":"Validation Error","type":"object"}
```

## Request examples

### cURL

```shell
curl --request POST \
  --url {protocol}://{hostname}/api/v3/repos/{owner}/{repo}/merges \
  --header 'content-type: application/json' \
  --data '{
  "base": "master",
  "commit_message": "Shipped cool_feature!",
  "head": "cool_feature"
}'
```