Skip to content

Commit 90baf43

Browse files
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]>
1 parent f4d3a6b commit 90baf43

File tree

1 file changed

+106
-50
lines changed

1 file changed

+106
-50
lines changed

README.md

+106-50
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,10 @@
2121
- Run only some [spec files](#specs)
2222
- Test [project in subfolder](#project)
2323
- [Record results](#record-test-results-on-cypress-cloud) on Cypress Cloud
24+
- Storing the [Project ID and Record Key](#project-id-and-record-key)
25+
- Getting [Git information](#git-information) environment variables
26+
- Getting [PR and URL](#automatic-pr-number-and-url-detection) automatically
27+
- Overwriting [Merge SHA into SHA](#merge-sha-into-sha) message
2428
- Tag [recordings](#tag-recordings)
2529
- Specify [auto cancel](#specify-auto-cancel-after-failures) after failures
2630
- Store [test artifacts](#artifacts) on GitHub
@@ -342,6 +346,8 @@ For more information, visit [the Cypress command-line docs](https://on.cypress.i
342346

343347
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.
344348

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+
345351
```yml
346352
name: Cypress tests
347353
on: push
@@ -358,21 +364,17 @@ jobs:
358364
with:
359365
record: true
360366
env:
361-
# pass the Cypress Cloud record key as an environment variable
362-
CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
363367
# pass GitHub token to allow accurately detecting a build vs a re-run build
364368
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
365369
```
366370

367371
[![recording example](https://github.com/cypress-io/github-action/workflows/example-recording/badge.svg?branch=master)](.github/workflows/example-recording.yml)
368372

369-
**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
370374

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`.
372376

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).
376378

377379
```yml
378380
name: Cypress tests
@@ -392,12 +394,107 @@ jobs:
392394
env:
393395
# pass the Cypress Cloud record key as an environment variable
394396
CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
395-
# pass GitHub token to allow accurately detecting a build vs a re-run build
396-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
397397
# pass the project ID from the secrets through environment variable
398398
CYPRESS_PROJECT_ID: ${{ secrets.PROJECT_ID }}
399399
```
400400

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"
451+
- run: echo "PR URL is $CYPRESS_PULL_REQUEST_URL"
452+
env:
453+
CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
454+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
455+
```
456+
457+
#### Triggering event: `pull_request`/`pull_request_target`
458+
459+
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.
473+
474+
```yml
475+
name: Cypress tests
476+
on: push
477+
jobs:
478+
cypress-run:
479+
name: Cypress run
480+
runs-on: ubuntu-22.04
481+
steps:
482+
- name: Checkout
483+
uses: actions/checkout@v4
484+
485+
- name: Cypress run
486+
uses: cypress-io/github-action@v6
487+
with:
488+
record: true
489+
env:
490+
# overwrite commit message sent to Cypress Cloud
491+
COMMIT_INFO_MESSAGE: ${{github.event.pull_request.title}}
492+
# re-enable PR comment bot
493+
COMMIT_INFO_SHA: ${{github.event.pull_request.head.sha}}
494+
```
495+
496+
See [issue 124](https://github.com/cypress-io/github-action/issues/124#issuecomment-1076826988) for details.
497+
401498
### Tag recordings
402499

403500
You can pass a single or multiple tags when recording a run. For example
@@ -1505,47 +1602,6 @@ jobs:
15051602
publish-summary: false
15061603
```
15071604

1508-
### Automatic PR number & URL detection
1509-
1510-
When recording runs to Cypress Cloud, the PR number and URL can be automatically detected if you pass `GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}`
1511-
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
1512-
exist) and sets them in the environment variables `CYPRESS_PULL_REQUEST_ID` and `CYPRESS_PULL_REQUEST_URL`, respectively.
1513-
* See Cypress' documentation on [CI Build Information](https://on.cypress.io/guides/continuous-integration/introduction#CI-Build-Information)
1514-
1515-
Example workflow using the variables:
1516-
```yml
1517-
name: Example echo PR number and URL
1518-
on: push
1519-
jobs:
1520-
cypress-run:
1521-
runs-on: ubuntu-22.04
1522-
steps:
1523-
- name: Checkout
1524-
uses: actions/checkout@v4
1525-
- name: Cypress run
1526-
uses: cypress-io/github-action@v6
1527-
with:
1528-
record: true
1529-
- run: echo "PR number is $CYPRESS_PULL_REQUEST_ID"
1530-
- run: echo "PR URL is $CYPRESS_PULL_REQUEST_URL"
1531-
env:
1532-
CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
1533-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
1534-
```
1535-
1536-
#### Triggering event: `pull_request`/`pull_request_target`
1537-
1538-
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
1539-
PR that triggered the workflow.
1540-
1541-
#### Triggering event: `push`
1542-
1543-
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
1544-
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
1545-
and use that PR's number and URL for `CYPRESS_PULL_REQUEST_ID` and `CYPRESS_PULL_REQUEST_URL`, respectively.
1546-
1547-
If no related PR is detected, `CYPRESS_PULL_REQUEST_ID` and `CYPRESS_PULL_REQUEST_URL` will be undefined.
1548-
15491605
## Node.js
15501606

15511607
### Support

0 commit comments

Comments
 (0)