Skip to main content

GitHub integration

This page covers connecting GitHub to the RunSafe Platform with the RunSafe GitHub App, check runs, and GitHub Actions workflow steps for build-time SBOMs. Self-hosted GitHub Enterprise Server uses the same flow with extra App and Actions sync steps.

Official Actions live in github-actions. Prefer this page for Platform behavior; use that repository for action names, inputs, and release tags.

Install the App and enable projects​

  1. Install the RunSafe GitHub App on your GitHub organization (or account) from Settings → Integrations → GitHub in the Platform.
  2. Select repositories and enable RunSafe features (Identify, Protect containers/source, Monitor) for each project.
  3. Push or run a workflow on a connected repository (scheduled workflows are ignored for non-buildtime SBOM scans and do not create check runs).

No merge request is required for GitHub. Workflow integration is driven by the App, check runs, and any Actions steps you add for build-time SBOMs.

If App or workflow changes that RunSafe relies on are later removed, reintroduce them by reconfiguring the project or following the manual steps below.

Check runs​

When a GitHub repository is configured with Identify, the Platform reports progress back to GitHub as check runs on the relevant commit:

  • RunSafe SBOMs — SBOM generation progress and links to the project-scoped Platform SBOM list and reports for that git ref. The check details page, each listed report, and the overflow “view all” link when many SBOMs were generated all open the matching Platform views.
  • RunSafe License Compliance Check — Waits for the SBOM data it needs, then evaluates the project's effective license compliance policy.
  • RunSafe Vulnerability Compliance Check — Waits for the SBOM data it needs, then evaluates the project's effective vulnerability thresholds.

Compliance checks stay in progress until SBOMs and reports finish. When they complete, their result reflects the organization defaults or the project's override when one is active.

Build-time SBOMs on the same check​

Repositories that use RunSafe GitHub Actions add build-time SBOMs (C/C++, Docker, .NET, and similar) to the same RunSafe SBOMs check. The Platform tracks those workflow runs separately from non-buildtime SBOM scans and updates the check as each SBOM and report finishes.

If a workflow is re-run, the Platform refreshes the build-time SBOM state for the new attempt so stale rows from the previous attempt do not remain in the GitHub check.

Setup issue​

When a GitHub project is first configured, the Platform opens an issue titled Integrate RunSafe into your C/C++ builds with links to finish CI setup (including when primary CI is Jenkins or another supported platform).

  • If the repository does not need build-time SBOMs from Actions, close the issue after confirming check runs appear on commits.
  • If it does need build-time SBOMs (C/C++, Docker, .NET, and similar), follow C and C++ workflow jobs and the Docker / .NET notes below, then close the issue.

C and C++ workflow jobs​

C/C++ builds require manual workflow changes. Each job that compiles C or C++ needs RunSafe setup immediately before the compile step and cleanup immediately after.

License key secret​

Add a GitHub Actions secret named RUNSAFE_LICENSE_KEY with your organization license key (Account → License key). Configure it at the organization or repository level (GitHub secrets documentation).

Workflow steps​

- uses: runsafesecurity/github-actions/setup@v1
  with:
    license_key: ${{ secrets.RUNSAFE_LICENSE_KEY }}
# ... your C/C++ build steps ...
- uses: runsafesecurity/github-actions/cleanup@v1

Every job that compiles C/C++ must include both steps. Repeat for each such job in .github/workflows/*.yml.

Examples use @v1 (latest v1.x). Pin a full release tag such as @v1.2.3 when you need a fixed revision.

Example​

jobs:
  cpp-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: runsafesecurity/github-actions/setup@v1
        with:
          license_key: ${{ secrets.RUNSAFE_LICENSE_KEY }}
      - name: Build
        run: make hello_world
      - uses: runsafesecurity/github-actions/cleanup@v1

Docker and .NET​

Docker and .NET build-time SBOM paths use the same setup/cleanup pattern as C/C++. Use the github-actions repository for the action names and inputs for each build type.

GitHub Enterprise​

Self-hosted GitHub Enterprise Server uses the same Platform GitHub integration (check runs, setup issues, and Actions workflow steps above). Extra steps are required so Actions and the App are available on your instance.

Sync RunSafe GitHub Actions​

The github-actions repository must be available to workflows on your Enterprise instance. Clone or sync it with either:

Then use the synced action references in your workflows (same setup/cleanup pattern as C and C++ workflow jobs).

Create the GitHub App on Enterprise​

Create a GitHub App on your Enterprise instance with these settings:

Create GitHub App​

  1. GitHub App name: RunSafe Platform
  2. Homepage URL: https://runsafesecurity.com

Post installation​

  1. Setup URL: https://app.runsafesecurity.com/projects/github/setup
  2. Check Redirect on update

Webhook​

  1. Check Active
  2. Webhook URL: https://app.runsafesecurity.com/webhooks/github

Repository permissions​

PermissionAccess
ActionsRead-only
ChecksRead and write
ContentsRead-only
IssuesRead and write
MetadataRead-only
Pull requestsRead-only

Subscribe to events​

  • Installation target
  • Check suite
  • Repository
  • Workflow run

Create the App, then collect the App ID, a generated private key, and the webhook secret from the App’s General page.

Connect Enterprise in the Platform​

On Settings → Integrations → GitHub, open the GitHub Enterprise tab and supply:

  1. GitHub Enterprise URL — Your Enterprise instance URL (protocol included, no trailing slash).
  2. GitHub App URL — URL of the App you created (protocol included, no trailing slash).
  3. GitHub App Identifier — App ID from the App’s General page.
  4. GitHub App Private Key (base64 encoded) — Base64-encoded private key from Generate a private key on the General page.
  5. GitHub App Webhook Secret — Webhook secret from the General page.

Click Install GitHub Enterprise App. GitHub prompts you to select repositories; you return to the Platform to finish configuring projects. After that, check runs and Actions follow the same flow as github.com-hosted repos on this page.

Troubleshooting​

  • Check runs never appear — Confirm the App is installed on the repository and the project is enabled in the Platform. Scheduled workflows do not create check runs.
  • Last contact never updates — Run a (non-scheduled) workflow after enabling the project. Last contact updates when a pipeline-attached scan completes; see Detection vs last contact.
  • Wrong or missing CI under Continuous integration — After editing workflow files on the default branch, use Refresh CI detection on Project → Settings → Integrations. Detection is one-shot unless you refresh; see Detection vs last contact.
  • Missing build-time SBOMs on the check — Confirm setup/cleanup Actions wrap the build job; re-run the workflow after fixing it.
  • Enterprise Actions not found — Confirm the RunSafe actions were synced to the Enterprise instance before referencing them in workflows.

If this page does not resolve the issue, email [email protected].