Add tests and documentation for the mergeUpstream method

Author: DAGpro

doc/repos.md

@@ -223,6 +223,15 @@ $repository = $client->api('repo')->forks()->create('ornicar', 'php-github-api')
 
 Creates a fork of the 'php-github-api' owned by 'ornicar' and returns the newly created repository.
 
+### Merge upstream repository
+
+> Requires [authentication](security.md).
+
+```php
+$repository = $client->api('repo')->mergeUpstream('ornicar', 'php-github-api', 'branchName');
+```
+Merge upstream a branch of a forked repository to keep it up-to-date with the upstream repository.
+
 ### Get the tags of a repository
 
 ```php

test/Github/Tests/Api/RepoTest.php

@@ -240,6 +240,26 @@ public function shouldGetRepositoryBranch()
         $this->assertEquals($expectedArray, $api->branches('KnpLabs', 'php-github-api', 'master'));
     }
 
+    /**
+     * @test
+     */
+    public function shouldMergeUpstreamRepository()
+    {
+        $expectedArray = [
+            'message' => 'Successfully fetched and fast-forwarded from upstream upstreamRepo:main',
+            'merge_type' => 'fast-forward',
+            'merge_branch' => 'upstreamRepo:main',
+        ];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('post')
+            ->with('/repos/KnpLabs/php-github-api/merge-upstream', ['branch' => 'main'])
+            ->will($this->returnValue($expectedArray));
+
+        $this->assertEquals($expectedArray, $api->mergeUpstream('KnpLabs', 'php-github-api', 'main'));
+    }
+
     /**
      * @test
      */