GitHub

Learn how to integrate Debricked with Github.

With our CI integration to GitHub you can automatically upload your latest commits and pull requests to Debricked.

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

• GitHub Actions

• GitHub App

GitHub actions

Configure Debricked token

Start by generating an access token. Copy the token so that you can use it in the next step.

You can add your access token as a secret, called DEBRICKED_TOKEN, under Settings → Secrets and variables → Actions in your repository.

Integrate a single repository

You can scan your repositories as part of your CI pipeline by using the GitHub action: https://github.com/debricked/actions.

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

In order for us to analyze 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 1: If npm 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 2: If Maven 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, as Maven does not offer a lock file system. Instead, "Maven dependency:tree" plugin can be used to create a file called ".debricked-maven-dependencies.tgf".

1. Create a ".github/workflows/debricked.yml" file and put in the contents of the template.

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

Integrate multiple repositories

Integrating many repositories with one workflow using GitHub can greatly simplify the process of managing and deploying code across multiple projects. You can set this up with required workflows set up in an organization ruleset, which triggers for every pull request and blocks the merge if the pipeline fails.

Considerations:

• Organization Rulesets are only available with GitHub Enterprise.

• GitHub Actions must be enabled for a repository in the organization's settings in order for required workflows to run.

• Ruleset workflows only work with the pull_request or merge_group events.

• Ruleset workflows and workflows from a specific repository are not mutually exclusive. If you use a required workflow and configure GitHub Actions for a specific repository, they will both run.

Step 1: Create an organization secret

To avoid having to add the DEBRICKED_TOKEN to every integrated repository, it is possible to share the Debricked token between repositories in your organisation. In order to enable this, you need to create an organization secret:

1. Generate a Debricked access token.

2. Go to organization Settings → Secrets and variables → Actions.

3. Click New organization secret.

4. Add the generated token to a variable called DEBRICKED_TOKEN.

Step 2: Create repository for the shared workflow

Set up a repository within your workspace for the shared workflow:

1. Create a new repository in your workspace or enter an already existing one.

2. Create a workflow yaml file and paste the Debricked workflow template contents as below:

https://github.com/debricked/cli/blob/main/examples/templates/GitHub/debricked.yml

name: Debricked scan

on: [push]

jobs:
  vulnerabilities-scan:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: debricked/actions@v4
        env:
          DEBRICKED_TOKEN: ${{ secrets.DEBRICKED_TOKEN }}

1. Change line 3 from on: [push] to on: [pull_request] for it to be able to run as a required workflow.

Step 3: Configure ruleset

1. Visit the settings page of your organization by clicking your avatar in the top right of the GitHub UI, select Your organizations and then the Settings button for the organization.

2. Under Code, planning, and automation go to Repository→ Repository Rulesets.

3. Click New branch ruleset or select an already existing ruleset.

4. In Enforcement status drop-down, select either Active if you want to enforce the rules from the start or Evaluate if you want to test it first.

5. In Target repositories section, select which repositories and branches the ruleset should be enforced for. We recommend starting out with either the default branches or including by pattern. If not, you have to set up bypassing roles or teams, to avoid situations where all branch actions in the repository get blocked.

6. in Branch protections tick Require workflows to pass before merging.

7. Click the Add workflow.

8. Select imported repository and branch from the dropdown lists and workflow from that repository in the modal window.

After these steps, the workflow should be executed for pull request events in the selected repositories and branches.

GitHub application

Installation

1. Start by heading over to https://github.com/apps/debricked/.

2. Click install on the top right corner.

3. Choose your personal account or your organization’s account.

4. If you have not entered your password in a while, you might have to re-enter your personal account password.

5. Install directly or request access to install:

• If installing to a personal account or an organization account where you are an admin, you will be able to select the repositories to install the integration.

• If you do not have the admin permissions, you will still be able to select which repositories to install the integration, but an organization admin should approve your installation request.

1. If the installation is successful, you or your organisation admin will be redirected to Debricked’s service settings, where pop-up will be shown letting you trigger a first-time scan of your repositories.

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

Permissions

The GitHub app requires certain permissions in order for our service to work:

• Read access to metadata - This is a default permission to all GitHub apps, and does not leak any sensitive information.

• Read and write access to checks - 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 events 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 - This is also necessary for creating pull-requests.

• Read and write access to issues - This is for future capabilities of issue integration between Debricked and GitHub.

Configuration

If you selected specific repositories upon installation, and would like to add more repos to be scanned:

1. Click Repositories on the left side menu.

2. Click New.

3. Select Repository.

4. Follow the link to grant access to more repositories.

The added repos will only show in the UI once a scan is started by either:

• Starting a scan manually, by going to New -> Repository

• Pushing a commit, which will start the scan automatically

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

Enable or disable application scanning

If you want to enable/disable scanning repositories via the GitHub App:

1. Go to Repository Settings.

2. Toggle the GitHub App scanning switch to off.

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

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.

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

Enabling slow scan

In cases where you get the “Your repository seems to be too large” error, you may want to enable slow scan to make the scan pass. To do so:

1. Create or edit the .debricked.yaml in the root of your repository.

2. Set slow_scan to true:

slow_scan: true

1. Commit the changes.

Excluding directories

Another solution to resolve the “Your repository seems to be too large” error is to exclude some directories in order to make the scan pass. To do so:

1. Create or edit the .debricked.yaml in the root of your repository.

2. Put the directories you want to exclude in the file:

excluded_directories: ['large-directory', 'important-directory/unwanted-directory', 'another-directory']

1. Commit the changes.

Enable skip scan

In order to prevent your pipeline from breaking due to vulnerabilities (or if you have a very complex project where the scan time is too long for your needs) you may want to enable the skip scan. This means that we still scan your repositories, but the pipeline won't wait for the results. To skip adding scan output to GitHub:

1. Create or edit the .debricked.yaml in the root of your repository.

2. Set skip_scan to true as below:

skip_scan: true

1. Commit the changes.

Uninstallation

If there is a problem during installation of the app, follow these steps to uninstall the app:

1. In GitHub, go to your GitHub user settings.

2. If the app was installed on an organizational account, switch to that account.

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, let us know at [e-mail].