> For the complete documentation index, see [llms.txt](https://docs.stepsecurity.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stepsecurity.io/github/github-checks.md).
# GitHub Checks
{% hint style="warning" %}
**Available for Enterprise Tier Only**
{% endhint %}
{% hint style="info" %}
**Permissions required:** GitHub Checks requires the `pull_requests: read` and `checks: write` permissions on the StepSecurity Actions Security GitHub App. If you installed the app before these permissions were introduced, accept them to enable GitHub Checks.
{% endhint %}
GitHub Checks is a powerful feature that helps you monitor and improve the quality of your code by running automated checks on your repositories.
By enabling this feature, you can gain better insights into your code’s performance, security, and compliance directly within your GitHub workflow.
## Types Of GitHub Checks
* Harden Runner Baseline Check
* StepSecurity Required Checks
* StepSecurity Optional Checks
### Harden Runner Baseline Check
This check integrates Harden-Runner insights into the GitHub Checks UI, providing developers with immediate feedback on outbound network activity.
With this integration, developers no longer need to rely on email or Slack notifications or visit the StepSecurity dashboard to monitor anomalous network calls.
### StepSecurity Required Checks
These are blocking status checks. When enabled, a pull request cannot be merged until all Required Checks pass. Use this to bucket StepSecurity controls (e.g., the StepSecurity GitHub Check) into the “required” set so merges are blocked on them.
To ensure StepSecurity Required Checks work for your organization:
* Go to your Organization Settings
* Navigate to Code, planning and automation → Repository → RuleSets
* Create a new ruleset
* Enable the rule “Require status checks to pass” and include StepSecurity Required Checks in the list of required checks.
### StepSecurity Optional Checks
These provide developers with security and quality insights without blocking pull requests. They surface issues for visibility but allow merges to proceed even if they fail.
### How it Works
**Step 1:** Navigate to Configuration under GitHub Checks in your StepSecurity dashboard
**Step 2:** Select the Controls you want to enable and choose the check type (Required or Optional)
**Step 3:** Set the cooldown period (between 1–30 days). You can also define exemption packages if your team publishes packages that should not be subject to the cooldown
**Step 4:** Select the repositories you want this to apply to, then click Save Changes
## **Example: a failing cooldown check**
The walkthrough below uses the `npm Package Cooldown` check as an example. `PyPI Package Cooldown`, `Maven Package Cooldown`, and `NuGet Package Cooldown` behave identically against Python, Java, and .NET dependencies.
**When a check fails.** A developer or bot opens a pull request that adds a `package.json` entry referencing a newly-published npm package. The `npm Package Cooldown` check fails because the package was published within the configured cooldown window (by default, 2 days).
**Seeing the failure in GitHub.** On the PR, click **StepSecurity Required Checks** or **StepSecurity Optional Checks** (depending on how the control is configured)
You'll see the full set of checks that ran, which may include:
* `Script Injection`
* `PWN Request`
* `npm Package Compromised Updates`
* `npm Package Cooldown`
* `PyPI Package Compromised Updates`
* `PyPI Package Cooldown`
* `Maven Package Compromised Updates`
* `Maven Package Cooldown`
* `NuGet Package Compromised Updates`
* `NuGet Package Cooldown`
Click the failing `npm Package Cooldown` check to see details, including the package name, the version, its publish date, and when it will pass the cooldown.
**What happens next.** Once the package version ages beyond the configured cooldown window, the check passes automatically on the next run. No manual intervention is required.
## Emergency Overrides for the Cooldown Check
If a newly published package must be merged immediately (for example, a critical security patch published yesterday), you can override the cooldown check in two ways:
* **Approve the check**: a one-time approval for that check run. Best for a one-off urgent merge.
* **Exempt the package**: adds the package to the cooldown control's Exempted Packages list, so it bypasses the cooldown check in every pull request until you remove it. Best when the package is one your team publishes internally, or a vetted version that multiple repositories need right away.
If the merge can wait, no override is needed. Once the package version ages beyond the configured cooldown window, the check passes automatically on the next run.
Before overriding, review the failing check details (package name, version, and publish date) and confirm the version is one your team trusts. Both overrides are an explicit opt-out of the cooldown's zero-day protection for that package.
#### Option 1: Approve the check
* Open the StepSecurity dashboard and go to the recent GitHub check run.
* Click Approve All.
* The check passes immediately on the next run.
#### Option 2: Add the package to the Exempted Packages list
* In the StepSecurity dashboard, go to **GitHub Checks → Configuration**.
* Click the gear icon next to the relevant **Package Cooldown** control (npm, PyPI, Maven, or NuGet). The configuration panel opens with the Cooldown Period and Exempted Packages settings.
* In the **Exempted Packages** field, type a pattern and press **Enter**. Patterns are matched as regular expressions:
| Pattern | What it exempts |
| ------------- | ------------------------------- |
| `react@2.3.4` | A single version of one package |
| `lodash@*` | All versions of one package |
| `@company/*` | All packages under a scope |
Exempt the narrowest pattern that solves the problem. For an urgent merge, that is usually a single version.
* Click **Save Changes**.
* Re-run the checks on the pull request by commenting in the PR thread:
```
@stepsecurity-app checks re-run
```
The cooldown check re-evaluates with the exemption applied and passes for the exempted package.
Exempted packages skip only the cooldown check. Every other enabled control, including Package Compromised Updates, still evaluates them. Review your exempted list periodically and remove entries that are no longer needed.
### **Filtering checks by pull request**
You can filter check runs by pull request number. When you view a check in the StepSecurity dashboard, the associated PR number appears as a clickable link. Clicking the PR number shows all checks related to that pull request, with one check run per commit.
Clicking the PR number shows all checks related to that pull request, with one check run per commit.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.stepsecurity.io/github/github-checks.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.