6.1 Manual Process for Updating sfops from Upstream
This guide outlines the step-by-step process for manually updating your sfops instance from the upstream repository (hosted in private Gitea at source.flxbl.io). This process is an alternative to using the automated workflows.
Prerequisites
Git installed on your local machine
Access to your organization's sfops repository
Access credentials for the Gitea repository (source.flxbl.io)
Necessary permissions to create and merge pull requests
Docker installed (if working with image updates)
Authentication Setup
1. Gitea Authentication
Before starting, you'll need to set up authentication for the private Gitea repository:
Generate a Gitea Access Token:
Log in to source.flxbl.io
Go to User Settings → Applications
Generate a new access token with repository access
Save the token securely; it won't be shown again
Configure Git Authentication using the token:
# Add upstream remote with embedded credentials git remote add upstream https://<username>:<access-token>@source.flxbl.io/flxbl/sfops.git
Step-by-Step Process
1. Clone and Configure Your Repository
# Clone your sfops repository
git clone <your-sfops-repo-url>
cd sfops
# Add the upstream remote with authentication
git remote add upstream https://<username>:<access-token>@source.flxbl.io/flxbl/sfops.git
# Verify remotes (note: token will be hidden in output)
git remote -v
2. Sync with Upstream
# Fetch all branches and tags from upstream
git fetch upstream --tags
# Check out your main branch
git checkout main
# Create a new branch for the update
git checkout -b update-from-upstream/<version-tag>
3. Apply Updates
# Merge the specific version tag
git merge <version-tag>
# If there are conflicts, resolve them manually
# After resolving conflicts:
git add .
git commit -m "resolve conflicts for version <version-tag>"
4. Testing Changes
Review all modified files carefully
Test any modified workflows locally if possible
Check for any environment-specific configurations that need adjustment
Verify compatibility with your organization's customizations
5. Create and Submit Pull Request
Push your changes to your repository:
git push origin update-from-upstream/<version-tag>
Create a pull request with the following information:
Title:
feat: update from upstream <version-tag>
Description: Include the upstream release notes and any specific modifications made
Labels: Add appropriate labels for tracking
6. Handle Docker Image Updates
The sfops repository manages two Docker images: sfops
and sfops-lite
. Docker images may need to be updated in two scenarios:
When there's a new SFP CLI version to be incorporated
When there are other changes in the Dockerfiles or dependencies, even without an SFP CLI version change
Triggering Image Updates
For SFP CLI updates, update the version in the workflow file:
# Edit .github/workflows/trigger-docker.yml sfp-version: "43.1.0" # Update to desired version
For any Docker-related updates (including non-SFP CLI changes):
Navigate to Actions → "Build & Publish Docker Image" workflow
Click "Run workflow"
Select the branch (usually 'main')
Click "Run workflow"
The images follow a promotion path:
Initial build creates images with
preview
tagPromotes to
alpha
after approvalFinally promotes to
latest
for production use
Manual Verification Steps
Check the current image versions:
# List tags for your images curl -H "Authorization: Bearer <token>" https://ghcr.io/v2/<repo>/sfops/tags/list curl -H "Authorization: Bearer <token>" https://ghcr.io/v2/<repo>/sfops-lite/tags/list
Monitor the promotion workflow:
Build → Preview tag
Alpha approval → Alpha tag
Production approval → Latest tag
Verify image configurations:
Check Dockerfile changes in
dockerfiles/sfops.Dockerfile
Check Dockerfile changes in
dockerfiles/sfops-lite.Dockerfile
Verify SFP CLI version compatibility
7. Post-Merge Steps
After merging the pull request:
Monitor the triggered workflows:
Build & Test workflow
Docker image building workflow (if applicable)
Approve deployments to test environments
Verify functionality in test environment
Proceed with production deployment approval if tests pass
8. Production Deployment
Ensure all test environment validations are successful
Approve production deployment in the release workflow
Monitor production deployment
Verify production functionality
Important Notes
Always backup your configurations before starting the update process
Document any manual changes made during conflict resolution
Keep track of any customizations that need to be reapplied
Test thoroughly in non-production environments before proceeding to production
Consider the impact on concurrent development work
Maintain a rollback plan
Regularly rotate your Gitea access tokens for security
Never commit tokens or credentials to the repository
Troubleshooting
If you encounter issues during the update:
Check the git log to understand the changes:
git log --oneline upstream/main..main
Use git diff to examine specific changes:
git diff upstream/main main
Consider reverting to a previous state if needed:
git reset --hard <previous-commit>
Common Authentication Issues
If you get "Authentication failed":
Verify your Gitea token hasn't expired
Check if token has correct repository access permissions
Ensure you're using the correct username
Try re-authenticating with a new token
If you get "Repository not found":
Verify you have access to the repository in Gitea
Check if your token has the correct scope
Verify the repository URL is correct
Support
If you need assistance during the manual update process:
Contact your sfops point of contact
Check the #sfops slack channel for common issues and solutions
Review the release notes for specific version-related information
Remember to always test thoroughly and maintain proper documentation of any manual changes made during the update process.
Last updated