Skip to main content
Safe Settings can be deployed in various environments to suit your infrastructure needs. Choose the deployment method that best fits your organization’s requirements.

​
Deployment Methods

Safe Settings supports multiple deployment options:
  • Docker - Containerized deployment for local or cloud environments
  • AWS Lambda - Serverless deployment with automatic scaling
  • Kubernetes - Production-grade orchestration with Helm charts
  • GitHub Actions - Scheduled sync operations without infrastructure

​
Prerequisites

Before deploying Safe Settings, ensure you have:
  1. GitHub App created with proper permissions
  2. Node.js 18.x or later (Node.js 20.x LTS recommended)
  3. Environment variables configured
  4. Admin repository set up in your organization

​
Required Environment Variables

All deployment methods require these core environment variables:
PRIVATE_KEY takes precedence over PRIVATE_KEY_PATH. Use PRIVATE_KEY (base64 encoded) for containerized deployments.

​
Core Variables

VariableDescriptionRequired
APP_IDGitHub App ID from app settings pageYes
WEBHOOK_SECRETWebhook secret generated during app creationYes
PRIVATE_KEYBase64 encoded private key contentsYes*
PRIVATE_KEY_PATHPath to private key fileYes*
* Either PRIVATE_KEY or PRIVATE_KEY_PATH is required

​
Optional Variables

VariableDescriptionDefault
ADMIN_REPORepository containing configuration filesadmin
CONFIG_PATHPath to configuration directory.github
SETTINGS_FILE_PATHSettings file namesettings.yml
DEPLOYMENT_CONFIG_FILEDeployment settings file pathdeployment-settings.yml
LOG_LEVELLogging level (trace, debug, info, warn, error)info
CRONCron schedule for periodic sync-
ENABLE_PR_COMMENTEnable PR comments with validation resultstrue
BLOCK_REPO_RENAME_BY_HUMANBlock manual repository renamingfalse
GHE_HOSTGitHub Enterprise Server hostname-
GH_ORGOrganization name for manifest flow setup-
WEBHOOK_PROXY_URLSMEE URL for local testing-
NODE_TLS_REJECT_UNAUTHORIZEDDisable SSL validation (use with caution)1

​
Environment-Specific Variables

​
GitHub Enterprise Server

GHE_HOST=github.mycompany.com

​
Scheduled Sync

# Run every hour
CRON='0 * * * *'

# Cron format:
# ┌────────────── second (optional)
# │ ┌──────────── minute
# │ │ ┌────────── hour
# │ │ │ ┌──────── day of month
# │ │ │ │ ┌────── month
# │ │ │ │ │ ┌──── day of week
# * * * * * *

​
Local Development

WEBHOOK_PROXY_URL=https://smee.io/your-channel
LOG_LEVEL=trace

​
Deployment Checklist

Before deploying, ensure you’ve completed these steps:
1
Create GitHub App
2
Create a GitHub App with the required permissions and download the private key.
3
Learn how to create a GitHub App →
4
Prepare Environment Variables
5
Set up your .env file or environment configuration:
6
cp .env.example .env
7
Update with your app credentials:
8
APP_ID=123456
WEBHOOK_SECRET=your-webhook-secret
PRIVATE_KEY="$(cat private-key.pem | base64)"
9
Choose Deployment Method
10
Select the deployment method that fits your infrastructure:
11
  • Docker - Quick start with containers
  • AWS Lambda - Serverless with auto-scaling
  • Kubernetes - Production orchestration
  • GitHub Actions - No infrastructure needed
    • 12
    Install GitHub App
    13
    Install the GitHub App in your organization for all repositories.
    14
    Safe Settings must be installed for all repositories in your organization to function correctly.

    ​
    Deployment Architecture

    Safe Settings can be deployed in two modes:

    ​
    Webhook Mode

    Responds to GitHub webhook events in real-time:
    • Repository created
    • Settings modified
    • Branch protection changed
    • Pull requests opened

    ​
    Scheduled Mode

    Runs on a schedule to prevent configuration drift:
    • Periodic sync using CRON
    • AWS Lambda with EventBridge
    • GitHub Actions scheduled workflow
    For production deployments, use both webhook and scheduled modes to ensure settings are always in sync.

    ​
    Next Steps

    Choose your deployment method:

    Docker

    Quick containerized deployment

    AWS Lambda

    Serverless with auto-scaling

    Kubernetes

    Production orchestration

    GitHub Actions

    No infrastructure required

    ​
    Support

    For deployment issues:
    • Check the logs with LOG_LEVEL=debug
    • Verify environment variables are set correctly
    • Ensure GitHub App has proper permissions
    • Review webhook delivery in GitHub App settings

    Build docs developers (and LLMs) love

    Get started for freeTalk to us