You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: add git information docs reference and example (#1091)
* add git information docs reference and example
* better grouping for env vars used for the cloud
* better grouping for env vars used for the cloud
* Update README.md
Fix capitalization and expand abbreviations
Co-authored-by: Mike McCready <[email protected]>
* Update README.md
Fix capitalization and add commit-info link
Co-authored-by: Mike McCready <[email protected]>
* Update README.md
Fix capitalization
Co-authored-by: Mike McCready <[email protected]>
* Update README.md
Clarify projectID and recordKey instructions
---------
Co-authored-by: Mike McCready <[email protected]>
- Getting [PR and URL](#automatic-pr-number-and-url-detection) automatically
27
+
- Overwriting [Merge SHA into SHA](#merge-sha-into-sha) message
24
28
- Tag [recordings](#tag-recordings)
25
29
- Specify [auto cancel](#specify-auto-cancel-after-failures) after failures
26
30
- Store [test artifacts](#artifacts) on GitHub
@@ -342,6 +346,8 @@ For more information, visit [the Cypress command-line docs](https://on.cypress.i
342
346
343
347
By setting the parameter `record` to `true`, you can record your test results into the [Cypress Cloud](https://on.cypress.io/cloud). Read the [Cypress Cloud documentation](https://on.cypress.io/guides/cloud/introduction) to learn how to sign up and create a Cypress Cloud project.
344
348
349
+
We recommend passing the `GITHUB_TOKEN` secret (created by the GH Action automatically) as an environment variable. This will allow correctly identifying every build and avoid confusion when re-running a build.
350
+
345
351
```yml
346
352
name: Cypress tests
347
353
on: push
@@ -358,21 +364,17 @@ jobs:
358
364
with:
359
365
record: true
360
366
env:
361
-
# pass the Cypress Cloud record key as an environment variable
**Tip 1:** We recommend using the action with `on: push` instead of `on: pull_request` to get the most accurate information related to the commit on Cypress Cloud. With pull requests, the merge commit is created automatically and might not correspond to a meaningful commit in the repository.
373
+
### Project ID and Record Key
370
374
371
-
**Tip 2:** we recommend passing the `GITHUB_TOKEN` secret (created by the GH Action automatically) as an environment variable. This will allow correctly identifying every build and avoid confusion when re-running a build.
375
+
To record the project needs `projectId` and `recordKey`.
372
376
373
-
**Tip 3:** if running on `pull_request` event, the commit message is "merge SHA into SHA", which is not what you want probably. You can overwrite the commit message sent to Cypress Cloud by setting an environment variable. See [issue 124](https://github.com/cypress-io/github-action/issues/124#issuecomment-653180260) for details.
374
-
375
-
**Tip 4:** to record the project needs `projectId`. Typically this value is saved in the [Cypress Configuration File](https://docs.cypress.io/guides/references/configuration#Configuration-File). If you want to avoid this, pass the `projectId` using an environment variable:
377
+
Typically, the `projectId` is stored in the [Cypress Configuration File](https://docs.cypress.io/guides/references/configuration#Configuration-File), while the `recordKey` is set as a [CLI parameter](https://docs.cypress.io/guides/guides/command-line#cypress-run-record-key-lt-record-key-gt). If you want to avoid this, both the `projectId` and `recordKey` can be provided as environment variables using [GitHub secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
376
378
377
379
```yml
378
380
name: Cypress tests
@@ -392,12 +394,107 @@ jobs:
392
394
env:
393
395
# pass the Cypress Cloud record key as an environment variable
# pass GitHub token to allow accurately detecting a build vs a re-run build
396
-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
397
397
# pass the project ID from the secrets through environment variable
398
398
CYPRESS_PROJECT_ID: ${{ secrets.PROJECT_ID }}
399
399
```
400
400
401
+
### Git information
402
+
403
+
Cypress uses the [@cypress/commit-info](https://github.com/cypress-io/commit-info) package to associate Git details (branch, commit message, author) with each run. It typically uses Git commands, expecting a .git folder. In Docker or similar environments where .git is absent, or if you need different data in the Cypress Cloud, Git information can be passed via custom environment variables.
404
+
405
+
```yml
406
+
name: Cypress tests
407
+
on: push
408
+
jobs:
409
+
cypress-run:
410
+
name: Cypress run
411
+
runs-on: ubuntu-22.04
412
+
steps:
413
+
- name: Checkout
414
+
uses: actions/checkout@v4
415
+
416
+
- name: Cypress run
417
+
uses: cypress-io/github-action@v6
418
+
with:
419
+
record: true
420
+
env:
421
+
# Get the short ref name of the branch that triggered the workflow run
422
+
COMMIT_INFO_BRANCH: ${{ github.ref_name }}
423
+
```
424
+
425
+
Please refer to the [Cypress Cloud Git information environment variables](https://on.cypress.io/guides/continuous-integration/introduction#Git-information) section in our documentation for more examples.
426
+
427
+
Please refer to the [default GitHub environment variables](https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables) for additional GitHub examples.
428
+
429
+
### Automatic PR number and URL detection
430
+
431
+
When recording runs to Cypress Cloud, the PR number and URL can be automatically detected if you pass `GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}`
432
+
via the workflow `env`. When set, this value enables the Action to perform additional logic that grabs the related PR number and URL (if they
433
+
exist) and sets them in the environment variables `CYPRESS_PULL_REQUEST_ID` and `CYPRESS_PULL_REQUEST_URL`, respectively.
434
+
* See Cypress' documentation on [CI Build Information](https://on.cypress.io/guides/continuous-integration/introduction#CI-Build-Information)
435
+
436
+
Example workflow using the variables:
437
+
```yml
438
+
name: Example echo PR number and URL
439
+
on: push
440
+
jobs:
441
+
cypress-run:
442
+
runs-on: ubuntu-22.04
443
+
steps:
444
+
- name: Checkout
445
+
uses: actions/checkout@v4
446
+
- name: Cypress run
447
+
uses: cypress-io/github-action@v6
448
+
with:
449
+
record: true
450
+
- run: echo "PR number is $CYPRESS_PULL_REQUEST_ID"
For either of these events, we set `CYPRESS_PULL_REQUEST_ID` and `CYPRESS_PULL_REQUEST_URL` to that of the PR number and URL, respectively, of the
460
+
PR that triggered the workflow.
461
+
462
+
#### Triggering event: `push`
463
+
464
+
When a commit on a branch without a PR is made, the Cypress GitHub Action checks to see if the commit that triggered the workflow has a
465
+
related PR. If the commit exists in any other PRs, it's considered a related PR. When there are related PRs, we grab the first related PR
466
+
and use that PR's number and URL for `CYPRESS_PULL_REQUEST_ID` and `CYPRESS_PULL_REQUEST_URL`, respectively.
467
+
468
+
If no related PR is detected, `CYPRESS_PULL_REQUEST_ID` and `CYPRESS_PULL_REQUEST_URL` will be undefined.
469
+
470
+
### Merge SHA into SHA
471
+
472
+
We recommend using the action with `on: push` rather than `on: pull_request` or `on: merge_group` for more accurate commit information in Cypress Cloud. When running on pull_request or merge_group, the commit message defaults to "merge SHA into SHA". You can overwrite the commit message sent to Cypress Cloud by setting an environment variable.
0 commit comments