👋 We've unified all of GitHub's product documentation in one place! Check out the content for REST API, GraphQL API, and Developers. Learn more on the GitHub blog.

Uploading a SARIF file to GitHub

You can upload SARIF files from third-party static analysis tools to GitHub and see code scanning alerts from those tools in your repository.

People with write permissions to a repository can upload code scanning data from a third-party tool.

In this article

Were you able to find what you were looking for?

Note: Code scanning is currently in beta and subject to change. To request access to the beta, join the waitlist.

About SARIF file uploads for code scanning

To upload results from third-party tools, you must use the Static Analysis Results Interchange Format (SARIF) 2.1.0 format. For more information, see "About SARIF support for code scanning."

GitHub will display code scanning alerts from the uploaded SARIF file in your repository. For more information, see "Managing alerts from code scanning."

To view results of a third-party SARIF file, you must upload the SARIF file to GitHub using a GitHub Actions workflow. The SARIF file can be generated from a SARIF-compatible analysis tool that you run in the same GitHub Actions workflow used to upload the file. Alternatively, when the file is generated as an artifact outside of your repository, you can push the SARIF file directly to a repository and use a workflow to upload the SARIF file.

Uploading a code scanning analysis with GitHub Actions

To upload a third-party SARIF file to GitHub, you'll need a GitHub Actions workflow. For more information, see "About GitHub Actions" and "Configuring a workflow".

Your workflow will need to use the upload-sarif action, which has input parameters that you can use to configure the upload. The main input parameter you'll use is sarif-file, which configures the file or directory of SARIF files to be uploaded. The directory or file path is relative to the root of the repository. For more information see the upload-sarif action.

The upload-sarif action can be configured to run when the push and scheduled event occur. For more information about GitHub Actions events, see "Events that trigger workflows."

If your SARIF file doesn't include partialFingerprints, the upload-sarif action will calculate the partialFingerprints field for you and attempt to prevent duplicate alerts. GitHub can only create partialFingerprints when the repository contains both the SARIF file and the source code used in the static analysis. For more information about preventing duplicate alerts, see "About SARIF support for code scanning."

Example workflow for SARIF files generated outside of a repository

You can create a new workflow that uploads SARIF files after you commit them to your repository. This is useful when the SARIF file is generated as an artifact outside of your repository.

This example workflow runs anytime commits are pushed to the repository. The action uses the partialFingerprints property to determine if changes have occurred. In addition to running when commits are pushed, the workflow is scheduled to run once per week. For more information, see "Events that trigger workflows."

This workflow uploads the results.sarif file located in the root of the repository. For more information about creating a workflow file, see "Configuring a workflow."

Alternatively, you could modify this workflow to upload a directory of SARIF files. For example, you could place all SARIF files in a directory in the root of your repository called sarif-output and set the action's input parameter sarif_file to sarif-output.

name: "Upload SARIF"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every at 00:00 on Sunday UTC time.
on:
  push:
  schedule:
  - cron: '0 0 * * 0'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    # This step checks out a copy of your repository.
    - name: Checkout repository
      uses: actions/checkout@v2
    - name: Upload SARIF file
      uses: github/codeql-action/upload-sarif@v1
      with:
        # Path to SARIF file relative to the root of the repository
        sarif_file: results.sarif

Example workflow that runs the ESLint analysis tool

If you generate your third-party SARIF file as part of a continuous integration (CI) workflow, you can add the upload-sarif action as a step after running your CI tests. If you don't already have a CI workflow, you can create one using a GitHub Actions template. For more information, see "Starting with preconfigured workflow templates."

This example workflow runs anytime commits are pushed to the repository. The action uses the partialFingerprints property to determine if changes have occurred. In addition to running when commits are pushed, the workflow is scheduled to run once per week. For more information, see "Events that trigger workflows."

The workflow shows an example of running the ESLint static analysis tool as a step in a workflow. The Run ESLint step runs the ESLint tool and outputs the results.sarif file. The workflow then uploads the results.sarif file to GitHub using the upload-sarif action. For more information about creating a workflow file, see "Configuring a workflow."

name: "ESLint analysis"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every at 00:00 on Sunday UTC time.
on:
  push:
  schedule:
  - cron: '0 0 * * 0'

jobs:
  build:
    steps:
    - uses: actions/checkout@v2
    - name: Run npm install
      run: npm install
    # Runs the ESlint code analysis
    - name: Run ESLint
      # eslint exits 1 if it finds anything to report
      run: node_modules/.bin/eslint build docs lib script spec-main -f node_modules/@microsoft/eslint-formatter-sarif/sarif.js -o results.sarif || true
    # Uploads results.sarif to GitHub repository using the upload-sarif action
    - uses: github/codeql-action/upload-sarif@v1
      with:
        # Path to SARIF file relative to the root of the repository
        sarif_file: results.sarif

Further reading

Were you able to find what you were looking for?

Ask a human

Can't find what you're looking for?

Contact us