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.
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.
Install the Paraxial.io agent in mix.exs
, then configure dev.exs
and prod.exs
.
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
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:
- Paraxial.io App Install ID (
45554672
in this example, your value will be different) - Repo Owner
- Repo Name
- 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.
5-configure-the-github-action
5. Configure the GitHub Action
Before continuing, answer the following questions:
- 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.
- 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.
- 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:
- 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.