Uni B Agency

1. Philosophy & Non-Negotiables

Every change — no matter how small — must flow through GitHub. A typo fix, a colour change, a config tweak: all of it goes through a commit, a pull request, and the automated pipeline. There are no exceptions.

Why This Matters

Direct server edits are the single biggest cause of:

• Production outages that cannot be traced or rolled back
• Security vulnerabilities introduced silently
• Code drift where the server no longer matches what is in version control
• Team confusion when developers pull “outdated” code

At Uni B Agency, we treat the live server the same way a pilot treats a plane’s controls — we follow a checklist, every time, without shortcuts.

The Three Guarantees This Process Gives Us

2. Branching Strategy

We use a structured three-tier branching model.

main          <-- production server deploys from here (PROTECTED)
  ^
develop       <-- integration branch, staging deploys from here
  ^
feature/*     <-- individual developer work
hotfix/*      <-- emergency production patches only

Branch Protection Rules

Configure in GitHub: Repository → Settings → Branches

3. Repository Setup

3.1 Creating a New Project Repository

All Uni B Agency project repositories are private by default, live under the UNI-B-AGENCY GitHub organisation, and follow the naming convention project-domain.

# On your local machine
cd /path/to/project

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin git@github.com:UNI-B-AGENCY/[project-name].git
git push -u origin main

# Create the develop branch immediately
git checkout -b develop
git push -u origin develop

3.2 Required Files in Every Repository

3.3 Standard .gitignore Entries

# Secrets -- never commit these
.env
.env.*
!.env.example

# Dependencies -- installed on deploy
/vendor
/node_modules

# Laravel runtime files
/bootstrap/cache/*
/storage/*.key
/storage/installed
/storage/framework/cache/*
/storage/framework/sessions/*
/storage/framework/views/*
/storage/logs/*

# Server-specific files -- never commit these
/cgi-bin/
error_log
*.sql
/public/user-uploads/*
!public/user-uploads/.htaccess

# Local dev tools
/.cursor/
/.idea/
/.vscode/
*.code-workspace
.DS_Store
Thumbs.db

4. cPanel Server Setup

One-time setup per project, performed by the lead developer.

4.1 Document Root Configuration

1. cPanel → Domains (or Subdomains)
2. Find your domain → click Manage
3. Set Document Root to: /home/[cpanel-username]/[project-folder]/public
4. Save

4.2 SSH Key for GitHub Access

Run in cPanel Terminal:

# Generate a dedicated deploy key (no passphrase -- required for automation)
ssh-keygen -t ed25519 -f ~/.ssh/github_deploy -N ""

# Create SSH config so git uses this key for GitHub
cat > ~/.ssh/config << 'EOF'
Host github.com
    IdentityFile ~/.ssh/github_deploy
    User git
EOF

chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/github_deploy

# Print the public key to add to GitHub
cat ~/.ssh/github_deploy.pub

In GitHub: Repository → Settings → Deploy keys → Add deploy key. Title: cPanel Production Server. Do NOT grant write access.

ssh -T git@github.com
# Expected: Hi UNI-B-AGENCY/[repo]! You've successfully authenticated...

4.3 Clone via cPanel Git Version Control

1. cPanel → Files → Git™ Version Control
2. Click Create → enable Clone a Repository
3. Clone URL: git@github.com:UNI-B-AGENCY/[repo].git
4. Repository Path: /home/[cpanel-username]/[project-folder] (use a name that does NOT match the subdomain folder)
5. Click Create and accept the GitHub SSH host key

4.4 SSH Key for GitHub Actions

# Generate a separate key for GitHub Actions
ssh-keygen -t ed25519 -f ~/.ssh/github_actions_deploy -N ""

# Authorise it for SSH login
cat ~/.ssh/github_actions_deploy.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

# Print the PRIVATE key -- this goes into GitHub Secrets
cat ~/.ssh/github_actions_deploy

Add to GitHub Secrets: Repository → Settings → Secrets and variables → Actions

4.5 Initial Laravel Setup on the Server

Run once after the first clone, before the site goes live:

cd ~/[project-folder]

# Create production environment file
cp .env.example .env
nano .env   # Fill in all production values

# Install dependencies
/usr/local/bin/composer install --no-dev --optimize-autoloader

# Generate application key
php artisan key:generate

# Run database migrations
php artisan migrate --force

# Create storage symlink
php artisan storage:link

# Cache configuration for performance
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Set permissions
chmod -R 775 storage bootstrap/cache

5. GitHub Actions CI/CD Pipeline

5.1 Standard Workflow File

Save as .github/workflows/deploy.yml in every project:

name: Deploy to Production

on:
  push:
    branches:
      - main          # Only deploys when code reaches main

jobs:
  deploy:
    name: SSH Deploy to cPanel
    runs-on: ubuntu-latest

    steps:
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1.2.0
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USERNAME }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          port: ${{ secrets.SSH_PORT }}
          script: |
            set -e   # Stop on any error

            cd ~/[project-folder]

            # Force-align server with GitHub (discards any server-side drift)
            git fetch origin
            git reset --hard origin/main

            # Install/update PHP dependencies
            /usr/local/bin/composer install --no-dev --optimize-autoloader

            # Maintenance mode: allow only server IP
            php artisan down --allow=127.0.0.1

            # Run any pending database migrations
            php artisan migrate --force

            # Rebuild caches
            php artisan config:cache
            php artisan route:cache
            mkdir -p resources/views/modules/sms
            php artisan view:cache

            # Ensure storage link exists
            php artisan storage:link --force

            # Bring site back online
            php artisan up

            echo "Deployment complete."

5.2 What Each Step Does

5.3 The set -e Directive

6. The Deployment Workflow

This is the day-to-day process every developer at Uni B Agency follows.

Normal Feature Development

git checkout develop && git pull origin develop

git checkout -b feature/your-feature-name

git add [specific files]
git commit -m "Short description of what and why"

git push origin feature/your-feature-name

Releasing to Production

Commit Message Standard

[type]: short description (max 72 characters)

Optional: longer explanation of WHY this change was made.

feat: add phone and email to landing page footer
fix: correct task submission file URL using asset_url_local_s3
hotfix: resolve login redirect loop on production
chore: update composer dependencies for security patches

7. Security Standards

Security is not optional. Every developer is responsible for the security of code they commit.

7.1 Secrets Management

All secrets live in the .env file on the server. The .env file is in .gitignore and must never be committed. For GitHub Actions, use GitHub’s encrypted Secrets — never hardcode values in the workflow YAML.

7.2 API Token Rotation

cPanel API tokens must be rotated every 90 days or immediately after any team member leaves.

1. cPanel → Manage API Tokens → Create new token
2. Update the GitHub Secret with the new token
3. Delete the old token in cPanel
4. Confirm the next deployment succeeds before closing the session

7.3 Server File Monitoring

Periodically scan the server for files that do not belong:

# Find PHP files in non-PHP directories (potential webshells)
find ~/[project]/public/css -name "*.php"
find ~/[project]/public/js -name "*.php"
find ~/[project]/documentation -name "*.php"

# Find recently modified PHP files (last 7 days)
find ~/[project]/public -name "*.php" -mtime -7

# Find world-writable files (security risk)
find ~/[project] -perm -002 -type f

If suspicious files are found:

1. Read the file content before deleting
2. If it contains obfuscated code — change all passwords immediately (cPanel, database, GitHub, email)
3. Check .htaccess files for injected redirect rules
4. Delete the files and audit server access logs
5. Report to the team lead

7.4 Production Environment Settings

APP_ENV=production
APP_DEBUG=false          # NEVER true on production -- exposes stack traces
APP_URL=https://your-domain.com
REDIRECT_HTTPS=true

7.5 File Permissions

# Application directories
chmod -R 755 ~/[project]

# Storage and cache -- must be writable
chmod -R 775 ~/[project]/storage
chmod -R 775 ~/[project]/bootstrap/cache

# Environment file -- owner only
chmod 600 ~/[project]/.env

7.6 Dependency Security

# Check for known PHP vulnerabilities
composer audit

# Check for known JS vulnerabilities
npm audit

Block any merge that introduces a package with a critical severity vulnerability.

8. Environment Configuration

8.1 The Environment Hierarchy

8.2 What Lives in .env.example

This file is the contract. It must list every variable the application needs with safe placeholder values. New developers cp .env.example .env and fill in their local values.

APP_NAME=ProjectName
APP_KEY=                          # Generate with: php artisan key:generate
APP_ENV=local                     # Change to: production on server
APP_DEBUG=true                    # Change to: false on server
APP_URL=http://localhost

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_db_user
DB_PASSWORD=

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@unibagency.com
MAIL_FROM_NAME="${APP_NAME}"

8.3 Production .env Handoff

When a new project goes live, the lead developer:

1. Sets the production .env on the server directly via cPanel Terminal
2. Runs php artisan config:cache to apply it
3. Does not share the production .env in Slack, email, or any chat system
4. Stores it securely in the team’s password manager (e.g. Bitwarden, 1Password)

9. Emergency Hotfix Procedure

When production is broken and cannot wait for the normal cycle:

# 1. Branch off main (NOT develop)
git checkout main
git pull origin main
git checkout -b hotfix/brief-description

# 2. Make the minimum fix required -- nothing more

# 3. Commit with a clear message
git add [specific files]
git commit -m "hotfix: [description of what was broken and what was fixed]"

# 4. Push and open a PR directly to main
git push origin hotfix/brief-description
# Open PR: main <-- hotfix/brief-description
# Get one approval (can be fast-tracked in a genuine emergency)

# 5. Merge to main -- triggers automatic deployment
# Verify the fix on the live site

# 6. IMPORTANT: merge the hotfix into develop too
git checkout develop
git pull origin develop
git merge hotfix/brief-description
git push origin develop

# 7. Delete the hotfix branch
git branch -d hotfix/brief-description
git push origin --delete hotfix/brief-description

10. Onboarding a New Project

Checklist for setting up a brand new project under this CI/CD standard:

11. Onboarding a New Developer

GitHub Authentication Setup (Do This First)

Before you can push or clone, your local machine needs to authenticate with GitHub. Choose one method:

# 1. Check if you already have an SSH key
cat ~/.ssh/id_ed25519.pub
# If it prints a key starting with ssh-ed25519, copy it and skip to step 3.
# If you get "No such file or directory", generate one:

# 2. Generate a new SSH key
ssh-keygen -t ed25519 -C "your_email@example.com"
# Press Enter through all prompts to accept the default location

# 3. Print the public key and copy the output
cat ~/.ssh/id_ed25519.pub

Local Setup

# Clone the repository (SSH)
git clone git@github.com:UNI-B-AGENCY/[repo].git

# -- OR -- clone via HTTPS (if using Method B above)
git clone https://github.com/UNI-B-AGENCY/[repo].git
cd [repo]

# Set up environment
cp .env.example .env
# Fill in local database and other local credentials

# Install dependencies
composer install
npm install

# Set up the database
php artisan migrate
php artisan db:seed  # if seeders exist

# Start the local server
php artisan serve

Daily Workflow Reminder

They never touch main directly. Ever.

12. Forbidden Practices

The following actions are prohibited at Uni B Agency. Violation will result in an incident review.

13. Troubleshooting Reference

cd ~/[project] && git status

git fetch origin
git reset --hard origin/main

GET https://[host]:2083/execute/VersionControl/update?repository_root=/home/[user]/[project]

cat ~/[project]/.cpanel.yml    # Must exist
git status                      # Must show "nothing to commit"

mkdir -p resources/views/modules/sms
php artisan view:cache

php artisan route:clear
php artisan config:clear
php artisan cache:clear
# Then re-run caches:
php artisan config:cache
php artisan route:cache
php artisan view:cache

php artisan storage:link --force

# Run once per server -- never commit
touch ~/[project]/storage/installed
php artisan config:clear

# Check if you have an existing key
cat ~/.ssh/id_ed25519.pub

# If "No such file or directory", generate one first:
ssh-keygen -t ed25519 -C "your_email@example.com"
# Then print it:
cat ~/.ssh/id_ed25519.pub

# Switch your remote from SSH to HTTPS
git remote set-url origin https://github.com/UNI-B-AGENCY/[repo].git

# Push (GitHub will prompt for credentials)
git push -u origin main

# Use set-url to overwrite the existing remote
git remote set-url origin git@github.com:UNI-B-AGENCY/[repo].git

# Verify it is correct
git remote -v

# Then push
git push -u origin main