Setup for self managed instances

The below diagram describes how updates are rolled out to a customer's GitHub org when a customer prefers a self managed instance

Quick Start Guide

This guide walks you through setting up a self-managed instance of sfops in your GitHub organization, allowing you to maintain full control over your CI/CD pipelines while receiving updates from the upstream sfops repository.

Prerequisites

1. Gitea Access Token

   • Log into source.flxbl.io (contact flxbl team for access)
   • Go to User Settings → Applications
   • Click "Generate New Token" under Manage Access Tokens
   • Configure the token:
     • Token Name: e.g., "sfops-access"
     • Repository and Organization Access: All (public, private, and limited)
     • Permissions:
       • repository: Read
       • package: Read

2. GitHub Personal Access Token (Classic) for GHA_TOKEN

   The built-in GITHUB_TOKEN cannot trigger workflows in other repositories or push packages. Create a PAT for:

   • Deploying workflows to sfops-gh-actions and sfops-dev-central repositories
   • Publishing Docker images to GitHub Container Registry (ghcr.io)
   • Creating pull requests for upstream synchronization

   Steps:

   • Navigate to: GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
     • Direct URL: https://github.com/settings/tokens
   • Click "Generate new token" → "Generate new token (classic)"
   • Add a descriptive note: e.g., "sfops GHA_TOKEN"
   • Set expiration based on your security requirements
   • Select the following scopes:
     • ☑️ repo (Full control of private repositories)
     • ☑️ workflow (Update GitHub Action workflows)
     • ☑️ write:packages (Upload packages to GitHub Package Registry)
     • Under admin:org → ☑️ read:org (Read org and team membership)
   • Click "Generate token" at the bottom of the page
   • ⚠️ IMPORTANT: Copy the token immediately! GitHub only shows it once
   • If your organization uses SSO: Click "Configure SSO" next to your new token and authorize it for your organization
   • Keep this browser tab open until you've configured the token as GHA_TOKEN in Step 4

Step-by-Step Setup Process

Step 1: Fork sfops from Gitea to GitHub

Option A: GitHub Import (Recommended)

Use GitHub's import feature for a quick setup:

1. Navigate to: New repository → Import a repository
   • Direct URL: https://github.com/new/import
2. Enter repository URL: https://source.flxbl.io/flxbl/sfops.git
3. For authentication:
   • Username: Your Gitea username
   • Password: Your Gitea token (created above)
4. Name your repository: sfops
5. Set visibility to Internal
6. Click "Begin import"

For future updates from upstream:

• Automated: Configure the Sync Upstream Repository workflow - requires GHA_TOKEN (your GitHub PAT from prerequisites) and SFOPS_UPSTREAM_URL secrets configured in Step 4
• Manual: See Option B below for command-line syncing

Option B: Manual Clone & Push

For manual control over the import process:

# Clone the sfops repository from Gitea
git clone https://<username>:<gitea-token>@source.flxbl.io/flxbl/sfops.git sfops
cd sfops

# Set your GitHub repository as origin
git remote remove origin
git remote add origin https://github.com/<your-org>/sfops.git

# Push to your GitHub repository
git push -u origin --all
git push -u origin --tags

# Add upstream remote for manual syncing
git remote add upstream https://<username>:<gitea-token>@source.flxbl.io/flxbl/sfops.git

Step 2: Create Required Repositories

Ensure the following repositories exist in your GitHub organization:

• sfops - Source code (already created in Step 1)
• sfops-gh-actions - Create as empty repository:
  • Visibility: Internal
  • Do NOT add README, .gitignore, or license
  • Will be populated by sfops workflows
• sfops-dev-central - Create as empty repository:
  • Visibility: Internal
  • Do NOT add README, .gitignore, or license
  • Will be populated by sfops workflows
• Your existing Salesforce project repository (will be configured to use sfops)

→ Detailed repository setup

Step 3: Configure GitHub App

Create a GitHub App (sfops-bot) to enable cross-repository operations and avoid PAT limitations. The app provides secure authentication for syncing workflows, managing deployments, and automating issue tracking.

→ GitHub App configuration

Step 4: Configure Secrets and Variables

Add required secrets and variables to your sfops repository for Docker image building, deployment, and upstream synchronization.

→ Repository configuration

Step 5: Trigger Initial Workflows

Build and deploy your sfops instance to the target repositories.

→ Workflow execution

Step 6: Set Up Your Salesforce Project

Configure your Salesforce project repository to use sfops workflows.

→ Project setup

Step 7: Configure Update Process

Set up automated synchronization with upstream sfops releases.

→ Update configuration

Support

For assistance with setup:

• Contact your sfops point of contact
• Check the #sfops Slack channel
• Review the troubleshooting guide