> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfops/self-managed-instances/workflow-details/dynamic-container-image-override.md).

# 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:

```yaml
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

{% hint style="warning" %}
**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.
{% endhint %}

{% hint style="info" %}
**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.
{% endhint %}

{% hint style="info" %}
**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.
{% endhint %}

## 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfops/self-managed-instances/workflow-details/dynamic-container-image-override.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.