To deploy the app anywhere, you will need 3 key 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:
-
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. This will require modification for different environments to make sure the file is available. E.g. For Docker: modify the Dockerfile to COPY the file into the container.
Note
PRIVATE_KEY
takes precedence over PRIVATE_KEY_PATH
.
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 16.x or later is installed.
-
Clone the codebase
git clone https://github.com/github/safe-settings.git
orgit clone <this repo>
-
Change directory to inside the code base
cd safe-settings/
-
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 theGH_ORG
variable if installing the app in an org. -
Start the app,
npm run dev
if running locally, ornpm 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 fields outlined in the Deployment Environment Variables section
Optional values in the .env file can be found under the Environment variables section. Additionally, you can set:
NODE_TLS_REJECT_UNAUTHORIZED
:0
for ignoring SSL validation and errorsGHE_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.
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 safe-settings/
- Build the container
docker build -t safe-settings .
- This process should complete successfully and you will then have a Docker container ready for deployment
Once the container has been successfully built, you can deploy it and start utilizing the GitHub App.
If you have docker-compose installed, you can simply start and stop the Docker container with:
cd safe-settings/; docker-compose --env-file .env up -d
This will start the container in the background and detached.
- Start the container detached with port assigned (Assuming port 3000 for the webhook)
docker run -d -p 3000:3000 safe-settings
- You should now have the container running in the background and can validate it running with the command:
docker ps
- This should show the
safe-settings
alive and running
- If you need to run the container in interactive mode to validate connectivity and functionality:
docker run -it -p 3000:3000 safe-settings
- You will now have the log of the container showing to your terminal, and can validate connectivity and functionality.
- If you need to connect to the container thats already running, you can run the following command:
docker exec -it safe-settings /bin/sh
- You will now be inside the running Docker container and can perform any troubleshooting needed
Serverless Framework Deployment of safe-settings on AWS
- 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
- For e.g.
- Create app secrets from the
.env
filekubectl create secret generic app-env --from-env-file=.env
- Deploy the app
kubectl apply -f safe-settings.yaml
NOTE: If your secrets' names are different; modify them in the deployment yaml.
- Expose the app using a service
kubectl apply -f svc-safe-settings.yaml
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, view the latest Helm chart version:
helm show chart oci://ghcr.io/github/helm-charts/safe-settings
Configure required values
See the values that can be configured.
helm show values oci://ghcr.io/github/helm-charts/safe-settings
Make sure to set the Deployment Environment Variables in a myvalues.yaml
file.
Optionally, you can set other values like LOG_LEVEL. See Environment variables for more details.
You can also override the deploymentConfig
value.
Install the chart
Set the values using --values
(preferred approach)
helm install safe-settings oci://ghcr.io/github/helm-charts/safe-settings --values myvalues.yaml
Set the with values using --set
helm install safe-settings oci://ghcr.io/github/helm-charts/safe-settings --set appEnv.APP_ID="\"0000\"" --set appEnv.PRIVATE_KEY="TFM...==" --set appEnv.WEBHOOK_SECRET="ZjZlYTFjN...=="
Note
Setting up Ingress controller is out of scope of this doc, but is recommended.
If not doing an install using Helm. Generate Kubernetes YAMLs
helm template safe-settings oci://ghcr.io/github/helm-charts/safe-settings --values myvalues.yaml
See helm repo for command documentation.
Consider using a custom image
For production use cases one should consider to build a custom safe-settings app image which conforms to your org standards.
Follow the instructions here on how to do it.
Note
If you want a reproducible build then you should specify a non floating tag for the image ghcr.io/github/safe-settings:2.1.10
.
Once you built the image and pushed it to your registry you can specify it in your values
file like this:
image:
repository: custom-registry/safe-settings
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]
Glitch lets you host node applications for free and edit them directly in your browser. It’s great for experimentation and entirely sufficient for simple apps.
- Create a new app on Glitch.
- Click on your app name on the top-right, press on advanced options and then on
Import from GitHub
(You will need to login with your GitHub account to enable that option). Enter the full repository name you want to import, e.g. for the welcome app it would bebehaviorbot/new-issue-welcome
. Thenew-issue-welcome
app is a great template to get started with your own app, too! - Next open the
.env
file and replace its content withReplace the twoAPP_ID=<your app id> WEBHOOK_SECRET=<your app secret> PRIVATE_KEY_PATH=.data/private-key.pem NODE_ENV=production
<...>
placeholders with the values from your app. The.env
file cannot be accessed or seen by others. - Press the
New File
button and enter.data/private-key.pem
. Paste the content of your GitHub App’sprivate-key.pem
in there and save it. Files in the.data
folder cannot be seen or accessed by others, so your private key is safe. - That’s it, your app should have already started 👍 Press on the
Show
button on top and paste the URL as the value ofWebhook URL
. Ensure that you remove/probot
from the end of theWebhook URL
that was just pasted.
Enjoy!
Bonus: You can deploy your app using glitch-deploy directly from your terminal or as continuous deployment.
Probot runs like any other Node app on Heroku. After creating the GitHub App:
-
Make sure you have the Heroku CLI client installed.
-
Clone the app that you want to deploy. e.g.
git clone https://github.com/probot/stale
-
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/ | git@heroku.com:arcane-lowlands-8408.git Git remote heroku added
-
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/
. -
Configure the Heroku app, replacing the
APP_ID
andWEBHOOK_SECRET
with the values for those variables, and setting the path for thePRIVATE_KEY
:$ heroku config:set APP_ID=aaa \ WEBHOOK_SECRET=bbb \ PRIVATE_KEY="$(cat ~/Downloads/*.private-key.pem)"
-
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
-
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
Every deployment will need an App.
- 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! - 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.
- Set the correct Permissions & events for the GitHub Integration:
- Actions: Read-only
- Administration: Read & Write
- Checks: Read & Write
- Commit statuses: Read & Write
- Contents: Read & Write
- Custom properties: Read & Write
- Environments: Read & Write
- Issues: Read & Write
- Metadata: Read-only
- Pull requests: Read & Write
- Variables: Read & Write
- Administration: Read & Write
- Custom properties: Admin
- Members: Read & Write
- Branch protection rule
- Check run
- Check suite
- Create
- Custom property values
- Member
- Pull request
- Push
- Repository
- Repository ruleset
- Team
-
Download the private key from the app.
-
Make sure that you click the green Install button on the top left of the app page. 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
The Probot website includes a list of featured apps. Consider adding your app to the website so others can discover and use it.
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"]
}
}