docs: record the pull request commit instead of the merge commit [ENG-934]

dashboard/runs/commit-information.md

@@ -48,6 +48,27 @@ Currents automatically detects PR information, including PR title and the target
 
 You can change this behavior in [project-settings.md](../projects/project-settings.md "mention").
 
+### Merge Commits in Pull Request Runs
+
+On pull request runs, some CI providers check out a merge commit that they create by merging the pull request into the target branch, for example `Merge <sha> into <sha>` in GitHub Actions. `@currents/playwright` `2.5.1` and `@currents/cmd` `1.11.0` record the last commit of the pull request instead. They read its SHA from:
+
+| CI provider                          | Pull request commit SHA                                      |
+| ------------------------------------ | ------------------------------------------------------------ |
+| GitHub Actions                       | `pull_request.head.sha` in the event file (`GITHUB_EVENT_PATH`) |
+| GitLab CI, merged results pipelines  | `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA`                         |
+| Azure Pipelines                      | `SYSTEM_PULLREQUEST_SOURCECOMMITID`                          |
+| Travis CI                            | `TRAVIS_PULL_REQUEST_SHA`                                    |
+| Semaphore                            | `SEMAPHORE_GIT_PR_SHA`                                       |
+| Buildkite                            | `BUILDKITE_PULL_REQUEST_HEAD_COMMIT`                         |
+| Bitbucket Pipelines                  | `BITBUCKET_COMMIT`                                           |
+
+The reporter uses the commit only when it is a parent of the checked-out merge commit. When a shallow clone doesn't have the commit, the reporter fetches it with `git fetch --depth=1 origin <sha>`, with a 3 second timeout. If the fetch fails, the run shows the merge commit's message and author. In GitHub Actions, the commit SHA and branch still come from the pull request.
+
+* Set `CURRENTS_DISABLE_HEAD_COMMIT_FETCH=true` to turn the fetch off.
+* Set `COMMIT_INFO_SHA` to record a specific commit. The reporter then skips this step.
+
+Jenkins sets no variable with the pull request commit, so Currents records the merge commit that Jenkins creates.
+
 ### Overriding Commit Info
 
 You can override the commit info by manually setting environment variables:

getting-started/ci-setup/github-actions/commit-data-for-github-actions.md

@@ -20,36 +20,38 @@ The recent (Jan 30, 2024) releases of `@currents/playwright@0.12.0` and `cypress
 
 <figure><img src="../../../.gitbook/assets/currents-2024-01-30-14.57.07@2x.png" alt=""><figcaption><p>Capturing GitHub PR data</p></figcaption></figure>
 
-### Temporary commit in GitHub Pull Requests
+### Merge commit in pull request runs
 
-Running tests using GitHub Actions can generate confusing git information. For example, instead of the last commit message (or pull request title), one can see something like:
+{% hint style="info" %}
+`@currents/playwright@2.5.1` and `@currents/cmd@1.11.0` record the last commit of the pull request when GitHub Actions checks out a merge commit.
+{% endhint %}
+
+On [`pull_request`](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request) events, `actions/checkout` checks out a merge commit that GitHub creates by merging the pull request into the base branch. Its message looks like this:
 
 ```
 Merge de7282540ac30ee4e32a0b1fede4f6391b4cc321 into fa58941d8a807b83ec5a3e5bfb83418ce12173c7
 ```
 
-Also, the branch name becomes `refs/pull/12/merge` instead of the expected branch name. Why is that happening?
+The reporter detects the merge commit and records the last commit of the pull request instead: its SHA, message, author and timestamp.
 
-That happens when your GitHub Actions workflow is triggered by [`pull_request`](https://docs.github.com/en/github-ae@latest/actions/using-workflows/events-that-trigger-workflows#pull_request).
+With the default `actions/checkout` settings, the clone has only the merge commit, so the reporter fetches the pull request commit:
 
-It changes the behaviour of `@actions/checkout` - it creates a **new merge commit,** which is created from merging the base to the head.
+```
+git fetch --depth=1 --no-tags origin <pull request commit SHA>
+```
 
-Specifically:
+The fetch uses the credentials that `actions/checkout` stores in the clone, and times out after 3 seconds. If it fails, the run shows the merge commit's message and author, as with earlier versions. For example, the fetch fails in a private repository checked out with `persist-credentials: false`. The commit SHA and branch still come from the pull request, so PR comments and commit statuses are not affected.
 
-* it performs `git checkout` to `github.ref` environment variable
-* it sets the git `ref` to `refs/remotes/pull/##/merge`
-* it sets the commit SHA to an arbitrary value that is different from the commit that triggered the workflow
+To turn the fetch off, set `CURRENTS_DISABLE_HEAD_COMMIT_FETCH=true`. See [commit-information.md](../../../dashboard/runs/commit-information.md "mention") for other CI providers.
 
-For example, a developer creates a pull request from the `feat/login` branch to be merged into the `main` branch with the title "_Add new login feature_". When the GitHub Actions workflow is triggered, instead of checking out the `feat/login` branch, the action creates a merge commit. In the GitHub Actions log, the commit message appears as "_Merge de7282540ac30ee4e32a0b1fede4f6391b4cc321 into fa58941d8a807b83ec5a3e5bfb83418ce12173c7_", which is a merge of the `feat/login` branch into the `main` branch. Consequently, the branch name in the CI environment shows as `refs/pull/12/merge`, not the expected `feat/login`.
+#### Earlier versions and Cypress
 
-To change the default behaviour and checkout the triggering commit, use the following `@actions/checkout` configuration
+With `cypress-cloud` and earlier versions of the reporters, runs show the merge commit's message and author. To record the last commit of the pull request, check out that commit:
 
 ```yaml
-- uses: actions/checkout@v2
+- uses: actions/checkout@v4
   with:
     ref: ${{ github.event.pull_request.head.sha }}
 ```
 
-The workflow will check out the last commit from the **head** branch of the pull request that triggered the workflow. Beware, that this approach might not detect issues that could arise when the pull request is eventually merged into the base branch. If the base branch has been updated since the pull request was created, there might be merge conflicts or integration issues that won't be detected with this configuration.
-
-Read more about [GitHub Actions and `pull_request`](https://frontside.com/blog/2020-05-26-github-actions-pull_request/) (by frontside.com).
+The workflow then tests the last commit of the pull request, not the result of merging it into the base branch. It does not catch conflicts or failures that appear only after the merge.

getting-started/ci-setup/github-actions/playwright-github-actions.md

@@ -25,8 +25,6 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-        with:
-          ref: ${{ github.event.pull_request.head.sha }}
 
       # https://github.com/actions/runner-images/issues/6775
       - run: |