View Source GitHub App

This guide to installing the Paraxial.io GitHub App assumes you are using GitHub Actions for CI/CD. The app is compatible with other providers (CircleCI, etc).

For an overview of why the GitHub App is useful, see the blog post -

1-create-a-paraxial-io-site-for-your-production-environment

1. Create a Paraxial.io site for your production environment.

github_app

2-install-the-paraxial-io-agent-locally

2. Install the Paraxial.io agent locally.

Why install the Paraxial.io agent locally if the goal is to run the Github app in CI/CD? This is for developer experience and happiness. A CI run can take minutes to complete, and the cycle of "make a code change, wait several minutes for CI to finish" slows down developer productivity. By running the check locally, the debugging loop is much faster.

Note: You MUST use version 2.6.0 or later. Earlier versions do not support the GitHub App.

github_app

Install the Paraxial.io agent in mix.exs, then configure dev.exs and prod.exs.

github_app github_app

For this example we really only need dev.exs, however the reason you want this in both environments is for the additional runtime protection features of Paraxial.io. See the docs for more details - https://hexdocs.pm/paraxial/install.html

Set the environment variable in your terminal with:

$ export PARAXIAL_API_KEY=df90...redacted...

This key is found in the "Site Settings" page. Now run:

% mix paraxial.scan
13:35:00.130 [info]  [Paraxial] API key found, scan results will be uploaded
...
13:35:01.905 [info]  [Paraxial] Scan written successfully. UUID 4b6a5fe3-626a-46e5-a959-6008f6114a74

3-install-the-paraxial-io-github-app-get-the-install_id

3. Install the Paraxial.io GitHub App, get the install_id.

You can install the Paraxial.io App in an organization or in your own account. GitHub Marketplace - https://github.com/marketplace/paraxial-io

github_app

Note the install_id of 45554672. Your value will be different. Make a note of this value somewhere, you will need it later.

The Paraxial.io Github App is compatible with all CI/CD pipelines. We will be using a Github Action in this example, but to adapt this to a different environment you need the following info:

  1. Paraxial.io App Install ID (45554672 in this example, your value will be different)
  2. Repo Owner
  3. Repo Name
  4. Pull Request number

The dynamic values should be accessible in your CI environment.

4-put-the-paraxial-io-api-key-in-github-actions-secrets

4. Put the Paraxial.io API Key in GitHub Actions Secrets

This secret key is found in "Site Settings" in the Paraxial.io web interface.

github_app github_app

5-configure-the-github-action

5. Configure the GitHub Action

Before continuing, answer the following questions:

  1. What is the name of your repo's primary branch? (It is probably master or main)
  • If your repo's branch is different, replace the "branches" value.
  1. If Paraxial.io detects security problems, do you want the build to fail?
  • If you do not want the build to fail when security issues are detected, remove the --add-exit-code flag.
  1. What is your Paraxial.io Github App Install ID?
  • See the section above

GitHub Action:

.github/workflows/elixir.yml

name: Paraxial.io Application Secure

on:
  push:
    branches: [ "master" ]
  pull_request:
    branches: [ "master" ]

permissions:
  contents: read

jobs:
  build:

    name: Build and test
    runs-on: ubuntu-latest

    env:
      PARAXIAL_API_KEY: ${{ secrets.PARAXIAL_API_KEY }}

    steps:
    - uses: actions/checkout@v3
    - name: Set up Elixir
      uses: erlef/setup-beam@61e01a43a562a89bfc54c7f9a378ff67b03e4a21 # v1.16.0
      with:
        elixir-version: '1.15.2' # [Required] Define the Elixir version
        otp-version: '26.0'      # [Required] Define the Erlang/OTP version
    - name: Restore dependencies cache
      uses: actions/cache@v3
      with:
        path: deps
        key: ${{ runner.os }}-mix-${{ hashFiles('**/mix.lock') }}
        restore-keys: ${{ runner.os }}-mix-

    - name: Install dependencies
      run: mix deps.get

    - name: Compile dependencies
      run: mix deps.compile

    - name: Get Github Repo Name
      run: echo "REPO_NAME=$(echo ${{ github.repository }} | cut -d'/' -f2)" >> $GITHUB_ENV
    
    - name: Send info to Paraxial.io
      run: |
        mix paraxial.scan --github_app \
          --install_id REPLACE_THIS_VALUE \
          --repo_owner ${{ github.repository_owner }} \
          --repo_name ${{ env.REPO_NAME }} \
          --pr_number ${{ github.event.number }} \
          --add-exit-code

Troubleshooting:

  1. What version of the Paraxial.io agent is running in CI/CD? Check your lock file. You must use version 2.6.0 or later for the GitHub App to work.