# 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` behaves identically, just against Python 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`
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 with Approve All
If a newly-published package must be merged immediately (for example, a critical security patch published yesterday), you can override the cooldown check:
* Open the StepSecurity dashboard and go to the recent GitHub check run.
* Click Approve All
* The check passes immediately on the next run
### **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: 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:
```
GET https://docs.stepsecurity.io/github-checks.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.
