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:

1. 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

2. 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

1. Review all modified files carefully

2. Test any modified workflows locally if possible

3. Check for any environment-specific configurations that need adjustment

4. Verify compatibility with your organization's customizations

5. Create and Submit Pull Request

1. Push your changes to your repository:

   git push origin update-from-upstream/<version-tag>

2. 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:

1. When there's a new SFP CLI version to be incorporated

2. When there are other changes in the Dockerfiles or dependencies, even without an SFP CLI version change

Triggering Image Updates

1. 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

2. 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"

3. The images follow a promotion path:

   • Initial build creates images with preview tag

   • Promotes to alpha after approval

   • Finally promotes to latest for production use

Manual Verification Steps

1. 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

2. Monitor the promotion workflow:

   • Build → Preview tag

   • Alpha approval → Alpha tag

   • Production approval → Latest tag

3. Verify image configurations:

   • Check Dockerfile changes in dockerfiles/sfops.Dockerfile

   • Check Dockerfile changes in dockerfiles/sfops-lite.Dockerfile

   • Verify SFP CLI version compatibility

Even if there's no SFP CLI version change, you might need to rebuild the Docker images to incorporate other updates or improvements. Always use the manual workflow trigger when you need to ensure the latest changes are included in the Docker images.

7. Post-Merge Steps

After merging the pull request:

1. Monitor the triggered workflows:

   • Build & Test workflow

   • Docker image building workflow (if applicable)

2. Approve deployments to test environments

3. Verify functionality in test environment

4. Proceed with production deployment approval if tests pass

8. Production Deployment

1. Ensure all test environment validations are successful

2. Approve production deployment in the release workflow

3. Monitor production deployment

4. 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:

1. Check the git log to understand the changes:

   git log --oneline upstream/main..main

2. Use git diff to examine specific changes:

   git diff upstream/main main

3. Consider reverting to a previous state if needed:

   git reset --hard <previous-commit>

Common Authentication Issues

1. 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

2. 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.