Dynamic Container Image Override

This feature allows administrators to dynamically switch the Docker container images used by sfops workflows without re-syncing the sfops-gh-actions repository.

Use Cases

• Testing new sfp versions: Test RC or development images before rolling them out

• Emergency rollback: Quickly revert to a previous container version if issues arise

• Hotfix deployment: Switch to a patched image immediately across all workflows

How It Works

After syncing, sfops workflows use a pattern that checks for override variables:

container: ${{ vars.SFOPS_DOCKER_IMAGE_OVERRIDE || 'ghcr.io/your-org/sfops:latest' }}

• No override variable set: Uses the default image (hardcoded during sync)

• Override variable set: Uses the override image immediately

Configuration

Override Variables

Set these variables in your sfops-gh-actions repository (not the project repository):

Variable	Purpose
SFOPS_DOCKER_IMAGE_OVERRIDE	Override for the full sfops image
SFOPS_LITE_DOCKER_IMAGE_OVERRIDE	Override for the sfops-lite image

Setting Up an Override

1. Navigate to your sfops-gh-actions repository

2. Go to Settings → Secrets and variables → Actions → Variables tab

3. Click New repository variable

4. Add the variable name and the full image path as the value

Example:

Name:  SFOPS_DOCKER_IMAGE_OVERRIDE
Value: ghcr.io/your-org/sfops:v2.5.0-rc1

Removing an Override

To revert to the default image, simply delete the override variable from the repository settings. All workflows will immediately use the hardcoded default from the last sync.

Examples

Testing a Release Candidate

1. Build the new image: ghcr.io/your-org/sfops:v2.5.0-rc1
2. Set variable: SFOPS_DOCKER_IMAGE_OVERRIDE = ghcr.io/your-org/sfops:v2.5.0-rc1
3. Run test workflows to validate the new version
4. If successful, either:
   - Re-sync with the new version as the default, then delete the override
   - Keep the override until next scheduled sync
5. If issues found, delete the variable to revert immediately

Emergency Rollback

1. Issue detected with current sfops:latest image
2. Set variable: SFOPS_DOCKER_IMAGE_OVERRIDE = ghcr.io/your-org/sfops:v2.4.0
3. All workflows immediately use v2.4.0
4. Investigate and fix the issue at your own pace
5. Once fixed, delete the override or sync with updated default

Testing Both Image Variants

You can override one or both images independently:

# Test only the full image
SFOPS_DOCKER_IMAGE_OVERRIDE = ghcr.io/your-org/sfops:testing

# Test only the lite image
SFOPS_LITE_DOCKER_IMAGE_OVERRIDE = ghcr.io/your-org/sfops-lite:testing

# Test both simultaneously
SFOPS_DOCKER_IMAGE_OVERRIDE = ghcr.io/your-org/sfops:testing
SFOPS_LITE_DOCKER_IMAGE_OVERRIDE = ghcr.io/your-org/sfops-lite:testing

Important Notes

Scope: Override variables must be set in the sfops-gh-actions repository, not in project repositories. This is a GitHub Actions limitation - the vars context in reusable workflows reads from the repository where the workflow file exists.

Organization-wide Effect: When you set an override, it affects all workflows using that image across all projects that call the reusable workflows. This is by design for administrative control.

No Re-sync Required: Changes to override variables take effect immediately on the next workflow run. You don't need to re-sync or redeploy anything.

Comparison: Override vs Re-sync

Aspect	Override Variable	Re-sync
Speed	Immediate	Requires sync workflow run
Scope	All workflows	All workflows
Persistence	Until variable deleted	Permanent until next sync
Audit trail	Variable history	Git commit history
Best for	Testing, rollback	Production releases

Troubleshooting

Override Not Taking Effect

1. Verify the variable is set in sfops-gh-actions repository (not project repo)

2. Ensure the variable name is exactly SFOPS_DOCKER_IMAGE_OVERRIDE (case-sensitive)

3. Check that the image path is valid and accessible

4. Trigger a new workflow run (existing runs use the image at start time)

Image Pull Errors

If workflows fail with image pull errors after setting an override:

1. Verify the image exists in your container registry

2. Check that the image tag is correct

3. Ensure GitHub Actions has permission to pull from that registry