How to Add Cypress Test Status Badges to a GitHub README

To show Cypress test status in a GitHub README, choose the badge that matches where your tests run: use a Cypress Cloud README badge for Cypress project status or test counts, or a GitHub Actions workflow badge for the status of the workflow that runs Cypress. These badges are related, but they report different things. A README badge displays information; it does not run tests or act as a merge gate.

1. Choose the badge source

Badge	What it reports	Best fit	Visibility constraint
Cypress Cloud README badge	Simple pass/fail status, detailed passed/failed/skipped counts, or project test count	You want Cypress project information in the README	Cypress documents README badges for public projects
GitHub Actions workflow badge	Status of a selected GitHub Actions workflow	You want readers to see whether the CI workflow running Cypress passed	Badges in private repositories are not externally accessible

Cypress Cloud can also report commit and pull request status checks through its GitHub integration. Those checks are separate from the README badge and can help prevent merging until recorded tests pass. A badge image itself is not a merge rule. See Cypress GitHub integration documentation.

2. Add a Cypress Cloud README badge

In Cypress Cloud, select the organization and project.
Open the project Settings, find README Badges, and select Configure Badge.
Confirm the prefilled project ID. Select a branch, or leave the branch unset to use the latest build in the project.
Choose a badge style. Cypress documents five styles; Flat is the default and most commonly used.
Choose a badge type: Simple status for passing/failing, Detailed status for passed, failed, and skipped counts, or Test count for the number of tests in the project.
Review the preview, copy the generated Markdown, and paste it where you want the badge in your README.

![Cypress test status](PASTE_THE_MARKDOWN_COPIED_FROM_CYPRESS_CLOUD_HERE)

Use the exact Markdown generated by Cypress Cloud rather than constructing a Cypress badge URL yourself. Cypress currently limits these README badges to public projects. The badge needs a corresponding project build to show useful status.

For commit or pull request checks, the project must be set up to record runs to Cypress Cloud, and the user enabling the GitHub integration must be a GitHub admin. Review Cypress’s current plan documentation before relying on GitHub Enterprise integration, which Cypress describes as included in Business and Enterprise plans.

3. Add a GitHub Actions badge for Cypress CI

First make sure a GitHub Actions workflow actually runs Cypress. Cypress documents its official GitHub Action for setting up a workflow. The badge only reports that workflow’s status; it does not create the workflow. Check the action’s documentation for the current recommended version when setting up a new workflow.

To get a badge for an existing workflow:

Open the repository’s Actions tab.
Select the workflow that runs Cypress.
Choose Create status badge. Optionally select a branch or event.
Copy the Markdown and add it to README.md.

You can also construct the documented badge Markdown using the repository owner, repository name, and workflow filename:

![Cypress Tests](https://github.com/OWNER/REPOSITORY/actions/workflows/WORKFLOW-FILE/badge.svg)

Replace all three placeholders. For example, if the workflow file is cypress.yml, use that filename in the URL. To filter the badge, add a branch or event query parameter:

![Cypress Tests](https://github.com/OWNER/REPOSITORY/actions/workflows/WORKFLOW-FILE/badge.svg?branch=main)
![Cypress Tests](https://github.com/OWNER/REPOSITORY/actions/workflows/WORKFLOW-FILE/badge.svg?event=push)

GitHub’s documented parameters are branch=BRANCH-NAME and event=push. By default, the badge reflects the default branch. If there are no runs on that branch, GitHub shows the most recent run across branches. A badge from a private repository is not externally accessible, so readers outside the repository may not be able to see it.

4. Verify that the badge answers the right question

For Cypress Cloud status or test counts, use the Cypress Cloud project badge.
For the pass/fail state of a GitHub Actions workflow, use the workflow badge.
For pull request or commit enforcement, configure Cypress Cloud’s GitHub integration and the repository’s checks or protection rules; do not rely on a README badge.
Run the relevant project or workflow at least once. A badge cannot show meaningful test status when there is no build or workflow run to report.

5. Troubleshooting

Symptom	Likely cause	Fix
Cypress Cloud does not offer a README badge	The project is private, or you are looking in a different organization or project	Confirm the selected project and its visibility. Cypress documents README badges for public projects.
The Cloud badge shows unexpected status or counts	The badge is set to another branch, or the project does not have a newer recorded build	Reopen the badge configurator, check its branch selection, and confirm a build was recorded for that project.
The Actions badge shows the wrong workflow	The URL’s workflow filename or repository coordinates are wrong	Copy the badge from that workflow’s Actions page or verify owner, repository, and workflow filename.
The Actions badge does not reflect the branch you expect	No branch filter was supplied, so it uses the default branch; a missing default-branch run can lead GitHub to show the latest run across branches	Add `?branch=BRANCH-NAME` and make sure that workflow has a run for the selected branch.
The badge is invisible to external visitors	The repository is private	GitHub warns that private repository badges are not externally accessible. Choose a visibility approach that suits the repository, or show status in a place accessible to the intended readers.
The README shows the Markdown as text	The Markdown is malformed, escaped, or placed in a code block	Use the generated Markdown or the documented image-link syntax, and place it outside fenced code blocks.
The badge loads but has no useful test status	The Cypress project has no relevant recorded build or the GitHub workflow has not run	Run tests and confirm they are recorded to the intended Cypress Cloud project or Actions workflow.

6. Performance, reliability, and maintenance

Badges are small remote images loaded when GitHub renders the README. They do not run Cypress and add no test execution work to your CI job. Their information is only as current as the build or workflow they report, so use CI checks for decisions that must block a merge.

Keep the badge URL or generated Markdown in the README aligned with the intended project, branch, and workflow filename. If you rename a workflow file, update the badge URL. If you change the default branch or want status for a release branch, review the branch filter. For a private repository, consider whether the badge needs to be visible to people who cannot access the repository.

Or skip the browser setup

If your documentation also needs screenshots of test results or application pages, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Responses identify the page verdict and billing status in headers.
An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots.

FAQ

Can I use both badges in one README?

Yes. They answer different questions: one reports Cypress Cloud project status or counts, while the other reports a GitHub Actions workflow’s status.

Does adding a badge run Cypress tests?

No. A badge displays the result of an existing Cypress Cloud build or Actions workflow run.

Can a README badge stop a pull request from merging?

No. Configure status checks and repository rules for merge enforcement. The README badge is a display element.

Which badge should I use for a private repository?

Cypress documents its README badges for public projects, and GitHub says private-repository workflow badges are not externally accessible. Check what your intended viewers can access before choosing.