GitHub Configuration

Overview

This page contains all the information needed to create a GuardRails GitHub application on your GitHub Enterprise server. This is needed to allow GuardRails to seamlessly integrate into the development workflow and makes onboarding all repositories in your organization easy and quick.

Only required for GitHub Enterprise deployments.

IMPORTANT: For this Guide we will assume that <YOUR_HOST> will be either the configured DNS (i.e.: guardrails.your-company.com) or the provissioned server IP. Both will work. So, whenever you see a <YOUR_HOST> remember this. As well <github-domain> will be the host name of your GitHub Enterprise instance.

Create the GitHub Application

The goal of this step is to create a GitHub application that we are going to use to connect to GuardRails to allow for a seamless integration of the security scanning across all repositories. GuardRails is tightly integrated into the workflow and provides a pleasant developer experience.

Create a GitHub Application for GuardRails in your GitHub instance by following the instructions below:

When you create an App, you do it on the organization level. By creating it on any organization, the app will be available for the other organizations as well, so don't worry about which organization to choose at this point.

1. Go to <github-domain>/settings/organizations, then select any organization.

2. Go to https://<github-domain>/organizations/<github-org-name>/settings/apps and click New GitHub App on the top right corner.

3. Fill it out like described below

   • GitHub App name: GuardRails
   • Homepage URL: https://<YOUR_DASHBOARD_HOST>
   • User authorization callback URL: https://<YOUR_API_HOST>/authorize/github/callback
   • Setup URL (optional): Use the same URL that you have set on the homepage url above.
   • Redirect on update: Disabled
   • Webhook URL: https://<YOUR_PROBOT_HOST>
   • Webhook secret: Enter a Webhook secret that will be used to protect the Webhooks delivered from GitHub to GuardRails. You can use Passwords Generator to generate a secret. Make sure to save the password in a secure place as it is needed for later setup steps.
   • SSL verification: Based on whether you will use recognized certificates for GuardRails. Strongly recommended to be enabled.
   • Permissions:
     • Checks: Read & write
     • Contents: Read-Only
     • Issues: Read & write
     • Pull requests: Read & write
     • Commit statuses: Read & write
   • Organization permissions:
     • Members: Read-Only
   • User Permissions:
     • Email addresses: Read-Only
   • Subscribe to events:
     • Pull request: enabled
     • Push: enabled
     • Repository: enabled
     • Organization: enabled
   • Where can this GitHub app be installed: Any account
   • Click Create GitHub App.

   It should look like this:

   

4. Afterwards you will be redirected to the application page, which will look like this:

   

5. On this page, you will see the following fields which you need to save for later use:

   • App ID
   • Client ID
   • Client Secret

6. Click on the generate a private key link that appears on the top yellow message, or alternatively at the bottom of the GitHub App page where it also says generate a private key:

   

   This will download the file guardrails.20YY-MM-DD.private-key.pem, which you also have to save for later use.

7. (Optional) Configure how the application will look like by customizing the description and logo:

   1. Description: you can use the following description and add it to the basic information section of the GitHub App:

      ![GuardRails](https://docs.guardrails.io/assets/images/social-card.jpg)
      
      ## What is GuardRails?
      
      GuardRails provides **continuous security** feedback for modern development teams.
      
      ### What to expect?
      
      GuardRails scans new code changes as they happen in your repositories. For pull requests, we will post comments whenever security issues are detected. For branches, you will be able to see reports in the dashboard.
      
      We currently support **static code analysis** and **vulnerable library analysis** for Apex, Dotnet, JavaScript, Python, Ruby, Solidity, Go, PHP, Elixir, C, C++, Terraform, Java and more. However, GuardRails can be used on all repositories to identify and prevent secrets leakage thanks to our **secrets detection** engines.
      
      ### What else?
      
      GuardRails works out of the box, _no configuration required_. However, if you want a customize certain aspects, please refer to our documentation for the [configuration](https://docs.guardrails.io/docs/en/configuration) options.
      
      ## Support
      
      If you experience any difficulties or have any questions, you can reach out to us by [email](mailto:[email protected]), or directly via [our support website](https://support.guardrails.io).

   2. Logo: you can download our logo and upload it to the Display information section of the GitHub App.

      At the end it should look like this example:

      

---

If you followed and completed the steps of this guide, you should have collected the following data in order to continue:

• GitHub GuardRails Application ID
• GitHub GuardRails Application Client ID
• GitHub GuardRails Application Secret
• GitHub GuardRails Application Webhook Secret
• GitHub GuardRails Application Private Key

Make sure you have this before you proceed to Setup & Deploy