# GitHub

With our CI integration to GitHub you can automatically upload your latest commits and pull requests to Debricked. Best of all, it only takes a couple of minutes to set up!

There are currently two ways of integrating your projects with debricked:

Click on the links to jump to the corresponding section in the documentation.

# GitHub App

# Installation

  • Start by heading over to https://github.com/apps/debricked/.
  • Click on install button in the top right corner. GitHub app install
  • Choose your personal account or your organisations account. Select account
  • If you havent entered your password in a while you might be have to re-enter your personal account password. Confirm password
  • Install directly or request access to install.
  • If installing to a personal account or an organisation account where you are an admin, you will be able to select which, or all, repositories which you want to install the integration to. All repositories
  • If not, you will still be able to select which, or all, repositories you want to install the integration to, but an organisation admin will have to approve your installation request. Selected repositories request
  • If installation was successful, you or your organisation admin will be redirected to Debrickeds service settings. A popup will be shown letting you trigger a first time scan of your repositories. Scan repositories

Note

Repositories not selected during the first scan will not be scanned initially. However, new commits to a repo will trigger a scan.

# Permissions

The GitHub app requires certain permission in order for our service to work.

More specifically, we require:

  • Read access to metadata.
  • Read and write access to checks, code, issues, and pull-requests.

The reason why we need these permissions is given below.

  • Read access to metadata (opens new window) - This is a default permission to all GitHub apps, and do not leak any sensitive information.
  • Read and write access to checks (opens new window) - Checks are also known as actions which we create and update in order to inform users about the scan progress. It is also used for posting results and trigger event for the GitHub App.
  • Read access to code - This is used in order for us to scan the dependency files. Note that we only read dependency files, not the source code.
  • Write access to code - This is required to create pull-requests with fixes for the dependency files.
  • Read and write access to pull-requests (opens new window) - This is also necessary for creating pull-requests.
  • Read and write access to issues (opens new window) - This is for future capabilities of issue integration between Debricked and GitHub.

# Configuration

# Adding more repos to scan

If you selected specific repositories upon installation, and would like to add more repos to be scanned, you can go to the repositories view, click on "New" -> "Repository" and follow the link to grant access to more repos.

Note

The added repos will only show in the UI once a scan has been started. Start a scan manually by going to "New" -> "Repository" or simply push a commit, which will start the scan automatically.

GitHub add more repos

You can also go directly in to your GitHub account and edit the app configuration.

# Enable/Disable app scanning

If you want to enable/disable scanning repos via the GitHub App, go to "Manage" -> "Repositories & Commits" and toggle the "GitHub App scanning" switch.

Disabling GitHub App scanning allows you to scan your repos using a CI integration instead, while still keeping the app for opening Fix Pull Requests to the repo.

Disable app scanning

# Configuring integration

It is possible to configure the GitHub integration by adding a .debricked.yaml file to the root of your repository, such as excluding directories and skipping adding the scan output to GitHub.

Note

It can take up to an hour before config changes take effect. Our GitHub actions alternative does not have this limitation.

# Enabling slow scan

You may want to do this if you for example get a message like Your repository seems to be too large... In this case you need to enable slow scan to make the scan pass. To enable it:

  • Create or edit .debricked.yaml in the root of your repository
  • Set slow_scan to true, like so:
slow_scan: true
  • Commit, done!

Note

Slow scan does exactly what it says, makes the scan slower. It should only be used if your repository can't be scanned using the normal scan.

# Excluding directories

You may want to do this if you for example get a message like Your repository seems to be too large... In this case you need to exclude some directories to make the scan pass. To exclude directories:

  • Create or edit .debricked.yaml in the root of your repository
  • Put the directories you want to exclude in the file, like so:
excluded_directories: ['large-directory', 'important-directory/unwanted-directory', 'another-directory']
  • Commit, done!

# Enable skip scan

You may want to do this if you don't want your pipeline to break because you have vulnerabilities, or if you have a very complex project where the scan time is too long for your needs. Note that enabling "skip scan" means that we still scan your repositories, but the pipeline won't wait for the results. To skip adding scan output to GitHub:

  • Create or edit .debricked.yaml in the root of your repository
  • Set skip_scan to true, like so:
skip_scan: true
  • Commit, done!

# Uninstallation

If there is a problem during installation of the app, you can uninstall the app as follows.

  • Go to your GitHub user settings
  • If the app was installed on an organizational account, switch to that account
  • Under "Account settings", click "Applications"
  • Find Debricked's app in the list, and hit "configure"
  • At the bottom, click on "Uninstall"

GitHub uninstall app

To re-install the app, follow the installation guide or set up GitHub actions.

If you are uninstalling the app due to unmet expectations, or other issues, please let us know at support@debricked.com.

# GitHub Actions

# Configure Debricked token

  • Start by generating an access token by following the instructions here. Copy the token so that you can use it in the next step.
  • You can add your access token as a secret under "Settings -> Secrets" in your repository. GitHub environment variables

# Configure GitHub Action

You can scan your repositories as part of your CI pipeline by using the GitHub Action debricked/actions/scan@v1.

Depending on what package manager you are using there are different step setups.

How come? In order for us to analyse all dependencies in your project, their versions and relations, files containing the resolved dependency trees have to be created prior to scanning. Those depend on the package manager used. If files are lacking we try to generate them on our side which can negatively affect speed and accuracy.

Example: If npm (opens new window) is used in your project you will have a package.json file, but in order for us to scan all your dependencies we need either package-lock.json or yarn.lock as well.

Example: If Maven (opens new window) is used in your project you will have a pom.xml file, but in order for us to resolve all your dependencies we need a second file. The issue? Maven do not offer a lock file system. Instead, Maven dependency:tree plugin can be used to create a file called .debricked-maven-dependencies.tgf.

Create a .github/workflows/debricked.yml file and put in the contents of one of the following templates:

Commit your changes to .github/workflows/debricked.yml and watch the pipeline run!

# Skip scan feature

Sometimes you just wish to start a dependency scan in the background, without actually have it block the pipeline. To do this, use the skip-scan action. It will upload dependency files to Debricked, without waiting for the scan results. However, remember to visit Debricked regularly so you don't miss any new vulnerabilities in your code! See example workflow below.

name: Debricked scan

on: [push, pull_request]

jobs:
  vulnerabilities-scan:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: debricked/actions/skip-scan@v1
      env:
        DEBRICKED_TOKEN: ${{ secrets.DEBRICKED_TOKEN }}