Skip to content

Latest commit

 

History

History
273 lines (192 loc) · 11.4 KB

deploy.md

File metadata and controls

273 lines (192 loc) · 11.4 KB

Deployment

Create the GitHub App

Every deployment will need an App.

  1. The easiest way to create the Github App is using the manifest flow . If you set up the app using the manifest flow, congrats, you are DONE!
  2. Create a new GitHub App with:
    • Homepage URL: the URL to the GitHub repository for your app
    • Webhook URL: Use https://example.com/ for now, we'll come back in a minute to update this with the URL of your deployed app.
    • Webhook Secret: Generate a unique secret with openssl rand -base64 32 and save it because you'll need it in a minute to configure your deployed app.

Permissions & events

  1. Set the correct Permissions & events for the GitHub Integration:

Permissions

Repository Permissions

  • actions: write
  • administration: write
  • checks: write
  • security_events: write
  • contents: write
  • metadata: read
  • pull_requests: write
  • secret_scanning_alerts: write

Organization Permissions

  • Administration: Read

Events

  • check_run
  • check_suite
  • code_scanning_alert
  • pull_request
  • repository_dispatch

Install

  1. Download the private key from the app. Save the private key: it will be needed later.
  2. Make sure that you click the green Install button on the top left of the app page.
  3. This gives you an option of installing the app on all or a subset of your repositories. Important: Install this App for All repos in the Org

Deploy the app on a vm

Prepare the source code

You will first need to clone the source code to your local environment that will run the Docker container.

Note: If running locally without Docker, ensure that Node 14.x or later is installed. Note: If you are running the app from a Docker image, skip to step.

  • Clone the codebase

    • git clone https://github.com/decyjphr-org/ghas-compliance.git or git clone <this repo>

  • Change directory to inside the code base

    • cd ghas-compliance/

  • Run npm install to build the code

  • The easiest way to create the Github App is using the manifest flow . To set up the app in an org, provide the GH_ORG env variable in the .env file

  • If using the manifest flow, create .env from .env.example and set the GH_ORG variable if installing the app in an org.

  • Start the app, npm run dev if running locally, or npm run prod

  • If using the manifest flow, follow the steps here

  • If not using the manifest flow then follow the steps in Create the GitHub App

  • Create .env from .env.example

    • cp .env.example .env

  • Update the .env with the needed fields.

    To deploy an app to any cloud provider, you will need 3 environment variables:

  • APP_ID: the ID of the app, which you can get from the app settings page.

  • WEBHOOK_SECRET: the Webhook Secret that you generated when you created the app.

And one of: (You will need to copy the contents of the .pem created from GitHub . This will be used when the app is built and deployed.)

  • PRIVATE_KEY: (preferred approach) the contents of the private key you downloaded after creating the app, and base64 encode it ...or
  • PRIVATE_KEY_PATH: the path to a private key file. (Modify the Dockerfile to COPY the file if this is done)

PRIVATE_KEY takes precedence over PRIVATE_KEY_PATH.

Other Optional values in the .env are:

  • LOG_LEVEL: Control the logging level
  • NODE_TLS_REJECT_UNAUTHORIZED: 0 for ignoring SSL validation and errors
  • GHE_HOST: This is a required field for GitHub Enterprise Server implementations (Example: github.mycompany.com)
  • WEBHOOK_PROXY_URL: SMEE Url for testing locally

Once you have the .env file configured, you are ready to start the building of the container.

Deploy the app in Docker

Build the Docker container

Once you have configured the GitHub App and updated the source code, you should be ready to build the container.

  • Change directory to inside the code base
    • cd ghas-compliance/
  • Build the container
    • sudo docker build -t ghas-compliance .
  • This process should complete successfully and you will then have a Docker container ready for deployment

Run the Docker container

Once the container has been successfully built, you can deploy it and start utilizing the GitHub App.

Start the container with docker-compose

If you have docker-compose installed, you can simply start and stop the Docker container with:

  • cd ghsas-compliance/; docker-compose up -d This will start the container in the background and detached.

Start Docker container Detached in background

  • Start the container detached with port assigned (Assuming port 3000 for the webhook)
    • sudo docker run --rm --detach --interactive -p 80:3000 --env-file .env --name ghas-compliance ghas-compliance
  • You should now have the container running in the background and can validate it running with the command:
    • sudo docker ps
  • This should show the ghas-compliance alive and running

Start Docker container attached in forground (Debug)

  • If you need to run the container in interactive mode to validate connectivity and functionality:
    • sudo docker run -it -p 80:3000 ghas-compliance
  • You will now have the log of the container showing to your terminal, and can validate connectivity and functionality.

Connect to running Docker container (Debug)

  • If you need to connect to the container thats already running, you can run the following command:
    • sudo docker exec -it ghas-compliance /bin/sh
  • You will now be inside the running Docker container and can perform any troubleshooting needed

Deploy the app to AWS Lambda

Serverless Framework Deployment of GHAS Compliance on AWS

Deploy the app in Kubernetes

Deploying using kubectl

  • Create and push your image to a container registry
  • Create a imagePullSecret
    • For e.g. kubectl create secret docker-registry regcred --docker-server=DOCKER_REGISTRY_SERVER --docker-username=DOCKER_USER --docker-password=DOCKER_PASSWORD --docker-email=DOCKER_EMAIL
  • Create app secrets from the .env file kubectl create secret generic app-env --from-env-file=.env
  • Deploy the app kubectl apply -f ghas-compliance.yml

NOTE: If your secrets' names are different; modify them in the deployment yaml.

  • Expose the app using a service kubectl apply -f svc-ghas-compliance.yml

Deploying using helm

Helm must be installed to use the charts. Please refer to Helm's documentation to get started.

Once Helm is set up properly, add the repo as follows:

$ helm repo add decyjphr https://decyjphr-org.github.io/charts/

Run helm search repo ghas-compliance to see the charts.

Run helm show values decyjphr/ghas-compliance to see the values.

Install template with values for APP_ID, PRIVATE_KEY, WEBHOOK_SECRET using --values (Preferred approach)

helm install ghas-compliance decyjphr/ghas-compliance --values myvalues.yaml

Install template with values for APP_ID, PRIVATE_KEY, WEBHOOK_SECRET using --set

helm install ghas-compliance decyjphr/ghas-compliance --set appEnv.APP_ID="\"0000\"" --set appEnv.PRIVATE_KEY="TFM...==" --set appEnv.WEBHOOK_SECRET="ZjZlYTFjN...=="

Generate Kubernetes YAMLs

helm template ghas-compliance decyjphr/ghas-compliance --values myvalues.yaml

Chart documentation is available in decyjphr charts repo.

See helm repo for command documentation.

Consider using a custom image

For production use cases one should consider to build a custom GHAS-Compliance app image which conforms to your org standards.

The repository contains documentation how to do it.

NOTE: If you want a reproducible build then you should specify a non floating tag for the image yadhav/ghas-compliance:2.249.3 .

Once you built the image and pushed it to your registry you can specify it in your values file like this:

image:
  repository: yadhav/ghas-compliance
  pullPolicy: IfNotPresent
  # Overrides the image tag whose default is the chart appVersion.
  tag: ""

In case you are using a private registry you can use 'imagePullSecretName' to specify the name of the secret to use when pulling the image:

imagePullSecrets: [regcred]

Running the app with an HTTPS server

In order to meet compliance needs of enterprises that require the traffic to the app to be encrypted, we have provided an HTTPS Server to run the app

Deploy the app in Heroku

Probot runs like any other Node app on Heroku. After creating the GitHub App:

  1. Make sure you have the Heroku CLI client installed.

  2. Clone the app that you want to deploy. e.g. git clone https://github.com/probot/stale

  3. Create the Heroku app with the heroku create command:

    $ heroku create
Creating arcane-lowlands-8408... done, stack is cedar
http://arcane-lowlands-8408.herokuapp.com/ | [email protected]:arcane-lowlands-8408.git
Git remote heroku added

  4. Go back to your app settings page and update the Webhook URL to the URL of your deployment, e.g. http://arcane-lowlands-8408.herokuapp.com/.

  5. Configure the Heroku app, replacing the APP_ID and WEBHOOK_SECRET with the values for those variables, and setting the path for the PRIVATE_KEY:

    $ heroku config:set APP_ID=aaa \
    WEBHOOK_SECRET=bbb \
    PRIVATE_KEY="$(cat ~/Downloads/*.private-key.pem)"

  6. Deploy the app to heroku with git push:

    $ git push heroku master
...
-----> Node.js app detected
...
-----> Launching... done
      http://arcane-lowlands-8408.herokuapp.com deployed to Heroku

  7. Your app should be up and running! To verify that your app is receiving webhook data, you can tail your app's logs:

     $ heroku config:set LOG_LEVEL=trace
 $ heroku logs --tail

Share the app

The Probot website includes a list of featured apps. Consider adding your app to the website so others can discover and use it.

Combining apps

To deploy multiple apps in one instance, create a new app that has the existing apps listed as dependencies in package.json:

{
  "name": "my-probot-app",
  "private": true,
  "dependencies": {
    "probot-autoresponder": "probot/autoresponder",
    "probot-settings": "probot/settings"
  },
  "scripts": {
    "start": "probot run"
  },
  "probot": {
    "apps": ["probot-autoresponder", "probot-settings"]
  }
}