feature #1084 Add sync a fork branch with the upstream repository (DA…

…Gpro)

This PR was squashed before being merged into the 3.9.x-dev branch.

Discussion
----------

| Q             | A
| ------------- | ---
| New feature?  |  ✔️
| Fixed issues  | #1083 

Commits
-------

184826b Add sync a fork branch with the upstream repository
c6b2d39 Mark the default branch
06e6c9b Add tests and documentation for the mergeUpstream method
0de3d78 Make parameter required
d5d9aff Add typings to the mergeUpstream method

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

lib/Github/Api/Repo.php

@@ -535,6 +535,21 @@ public function branches($username, $repository, $branch = null, array $paramete
         return $this->get($url, $parameters);
     }
 
+    /**
+     * Sync a fork branch with the upstream repository.
+     *
+     * @link https://docs.github.com/en/rest/branches/branches#sync-a-fork-branch-with-the-upstream-repository
+     *
+     * @return array|string
+     */
+    public function mergeUpstream(string $username, string $repository, string $branchName)
+    {
+        return $this->post(
+            '/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/merge-upstream',
+            ['branch' => $branchName]
+        );
+    }
+
     /**
      * Manage the protection of a repository branch.
      *

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
      */