Merge branch 'main-enterprise' into docs-github-action

Author: decyjphr

.github/workflows/create-pre-release.yml

@@ -50,15 +50,15 @@ jobs:
           cache: 'npm'
       - run: npm install
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435
       - name: Log in to the Container registry
-        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772
+        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
       - name: Build Docker Image Locally
-        uses: docker/build-push-action@1dc73863535b631f98b2378be8619f83b136f4a0
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83
         with:
           context: .
           file: ./Dockerfile
@@ -85,7 +85,7 @@ jobs:
           commitish: ${{ github.ref }}
       - name: Push Docker Image
         if: ${{ success() }}
-        uses: docker/build-push-action@1dc73863535b631f98b2378be8619f83b136f4a0
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83
         with:
           context: .
           file: ./Dockerfile

.github/workflows/create-release.yml

@@ -28,15 +28,15 @@ jobs:
           cache: "npm"
       - run: npm install
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435
       - name: Log in to the Container registry
-        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772
+        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
       - name: Build Docker Image Locally
-        uses: docker/build-push-action@1dc73863535b631f98b2378be8619f83b136f4a0
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83
         with:
           context: .
           file: ./Dockerfile
@@ -59,7 +59,7 @@ jobs:
           bump: final
       - name: Push Docker Image
         if: ${{ success() }}
-        uses: docker/build-push-action@1dc73863535b631f98b2378be8619f83b136f4a0
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83
         with:
           context: .
           file: ./Dockerfile

.github/workflows/rc-release.yml

@@ -60,23 +60,23 @@ jobs:
       - run: echo ${{ github.actor }}
 
       - name: Log in to the Container registry
-        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772
+        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Extract metadata
         id: meta
-        uses: docker/metadata-action@902fa8ec7d6ecbf8d84d538b9b233a880e428804
+        uses: docker/metadata-action@c1e51972afc2121e065aed6d45c65596fe445f3f
         with:
           images: ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ env.IMAGE_NAME }}
       - name: Set up QEMU
         uses: docker/setup-qemu-action@29109295f81e9208d7d86ff1c6c12d2833863392
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435
       - name: Build and push Docker image
-        uses: docker/build-push-action@1dc73863535b631f98b2378be8619f83b136f4a0
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83
         with:
           context: .
           push: true

README.md

@@ -1,6 +1,11 @@
-# GitHub Safe-Settings
+# 🛡️ GitHub Safe-Settings
 
 [![Create a release](https://github.com/github/safe-settings/actions/workflows/create-release.yml/badge.svg)](https://github.com/github/safe-settings/actions/workflows/create-release.yml)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+
+> **Policy-as-Code for GitHub Organizations**  
+> Centrally manage and enforce repository settings, branch protections, teams, and more across your entire GitHub organization.
 
 `Safe-settings` – an app to manage policy-as-code and apply repository settings across an organization.
 
@@ -29,8 +34,121 @@
 
 > [!NOTE]
 > The `suborg` and `repo` level settings directory structure cannot be customized.
->
 
+## 🚀 Quick Start
+
+### 1. **Deploy Safe-Settings**
+
+Choose your preferred deployment method:
+
+- **🌟 AWS Lambda (**: Use the [SafeSettings-Template](https://github.com/bheemreddy181/SafeSettings-Template) for production-ready deployment with Docker containers, GitHub Actions CI/CD, and comprehensive testing
+- **🐳 Docker**: Deploy using Docker containers locally or in your infrastructure
+- **☁️ Cloud Platforms**: Deploy to Heroku, Glitch, or Kubernetes
+
+👉 **[View all deployment options →](docs/deploy.md)**
+
+### 2. **Create Admin Repository**
+
+Create an `admin` repository in your organization to store all configuration files:
+
+```bash
+# Create admin repo in your organization
+gh repo create your-org/admin --private
+```
+
+### 3. **Configure Settings Structure**
+
+Set up your configuration files in the admin repository:
+
+```
+admin/
+├── .github/
+│   ├── settings.yml          # Organization-wide settings
+│   ├── suborgs/              # Sub-organization settings
+│   │   ├── frontend-team.yml
+│   │   └── backend-team.yml
+│   └── repos/                # Repository-specific settings
+│       ├── api-service.yml
+│       └── web-app.yml
+```
+
+### 4. **Install GitHub App**
+
+Install the Safe-Settings GitHub App in your organization with the required permissions.
+
+👉 **[Complete setup guide →](#how-to-use)**
+
+## 📊 Visual Architecture
+
+### Configuration Hierarchy
+
+```mermaid
+graph TD
+    A[Organization Settings<br/>.github/settings.yml] --> B[Sub-Organization Settings<br/>.github/suborgs/*.yml]
+    B --> C[Repository Settings<br/>.github/repos/*.yml]
+    
+    style A fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000
+    style B fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000
+    style C fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px,color:#000
+```
+
+**Precedence Order**: Repository > Sub-Organization > Organization
+
+### Request Flow
+
+```mermaid
+sequenceDiagram
+    participant GH as GitHub
+    participant SS as Safe-Settings
+    participant AR as Admin Repo
+    participant TR as Target Repos
+    
+    Note over GH,TR: Webhook Event Processing
+    
+    GH->>+SS: Webhook Event<br/>(push, repo created, etc.)
+    SS->>SS: Validate Event Source
+    SS->>+AR: Fetch Configuration Files<br/>(.github/settings.yml, suborgs/, repos/)
+    AR-->>-SS: Return Config Files
+    
+    SS->>SS: Merge Configurations<br/>(Org → Suborg → Repo)
+    SS->>SS: Compare with Current<br/>GitHub Settings
+    
+    alt Configuration Changes Detected
+        SS->>+TR: Apply Settings<br/>(Branch Protection, Teams, etc.)
+        TR-->>-SS: Confirm Changes
+        SS->>GH: Create Check Run<br/>(Success/Failure)
+    else No Changes Needed
+        SS->>GH: Create Check Run<br/>(No Changes)
+    end
+    
+    SS-->>-GH: HTTP 200 Response
+    
+    Note over GH,TR: Pull Request Validation (Dry-Run Mode)
+    
+    GH->>+SS: PR Event<br/>(opened, synchronize)
+    SS->>+AR: Fetch PR Changes<br/>(Modified Config Files)
+    AR-->>-SS: Return Changed Configs
+    
+    SS->>SS: Validate Changes<br/>(Dry-Run Mode)
+    SS->>SS: Run Custom Validators<br/>(if configured)
+    
+    alt Validation Passes
+        SS->>GH: ✅ Check Success<br/>+ PR Comment (optional)
+    else Validation Fails
+        SS->>GH: ❌ Check Failure<br/>+ Error Details
+    end
+    
+    SS-->>-GH: HTTP 200 Response
+    
+    Note over GH,TR: Scheduled Sync (Drift Prevention)
+    
+    SS->>SS: Cron Trigger<br/>(if configured)
+    SS->>+AR: Fetch All Configurations
+    AR-->>-SS: Return All Configs
+    SS->>+TR: Sync All Repositories<br/>(Prevent Drift)
+    TR-->>-SS: Confirm Sync
+    SS->>GH: Create Check Run<br/>(Sync Results)
+```
 
 ## How it works
 

index.js

@@ -624,6 +624,32 @@ module.exports = (robot, { getRouter }, Settings = require('./lib/settings')) =>
     return syncSettings(false, context)
   })
 
+  robot.on('repository.archived', async context => {
+    const { payload } = context
+    const { sender } = payload
+
+    if (sender.type === 'Bot') {
+      robot.log.debug('Repository Archived by a Bot')
+      return
+    }
+    robot.log.debug('Repository Archived by a Human')
+
+    return syncSettings(false, context)
+  })
+
+  robot.on('repository.unarchived', async context => {
+    const { payload } = context
+    const { sender } = payload
+
+    if (sender.type === 'Bot') {
+      robot.log.debug('Repository Unarchived by a Bot')
+      return
+    }
+    robot.log.debug('Repository Unarchived by a Human')
+
+    return syncSettings(false, context)
+  })
+
   if (process.env.CRON) {
     /*
     # ┌────────────── second (optional)