Skip to main content
In this guide we’ll connect FluxCD’s ImageRepository custom resource to a Docker Hub image repository to fetch image metadata (tags). Flux’s ImageRepository scans a registry and records available tags; later you can use that information to drive automated updates with ImagePolicy and ImageUpdateAutomation (GitOps).
Replace siddharth67 below with your own Docker Hub username when building and pushing images.

​
Overview

This tutorial covers:
  • Creating an ImageRepository resource to point Flux at your Docker Hub repo.
  • Forcing Flux to reconcile your flux-system Git source.
  • Building and pushing a new image tag to Docker Hub.
  • Verifying that Flux discovers the newly pushed tag.
  • Next steps: ImagePolicy and ImageUpdateAutomation to automate Git updates.
Relevant keywords: FluxCD, ImageRepository, GitOps, Docker Hub, ImagePolicy, ImageUpdateAutomation, reconcile, kubectl.

​
1. Create an ImageRepository resource

You can create the ImageRepository resource directly with the Flux CLI or prepare a YAML manifest and commit it to the Git repository monitored by flux-system. Below is the YAML manifest (kind: ImageRepository) used in this demo:
To export an editable YAML using the Flux CLI:
Commit the exported or hand-edited YAML to the Git repository watched by the flux-system GitRepository.

​
2. Force Flux to reconcile the Git source

After committing the ImageRepository YAML, trigger an immediate reconciliation so Flux fetches the latest Git revision and applies any new resources:
Example CLI output showing Flux annotated and fetched the revision:
Check image resources discovered by Flux. Depending on your Flux CLI version you can use:
Or inspect the ImageRepository directly with kubectl:
Example output indicating a successful scan and the number of tags found:
(An initial scan may show only a single tag if your Docker Hub repo had one tag at the time.)
ImageRepository only scans the registry and reports tags. It does not change your Deployment images by itself. To automate updates you must add an ImagePolicy and ImageUpdateAutomation (or manually update the Deployment image in Git).

​
3. Make source changes, build a new image tag, and push to Docker Hub

Update your application source (for example, bump the app version and change UI assets), then build and push a new Docker image tag. Example Dockerfile used in the project:
Build the new image locally and tag it (example tag 7.8.1):
Push the new tag to Docker Hub:
Example push output (truncated):
Then refresh your Docker Hub repository page and confirm the new tag (for example 7.8.1) is visible.

​
4. Confirm Flux discovers the new tag

Flux’s ImageRepository controller will scan the registry on its configured interval and should detect the new tag. You can force a Git reconciliation again to ensure Flux’s configuration is current, then inspect the ImageRepository status to verify discovered tags. Force reconciliation (if needed):
View the ImageRepository status to see lastScanResult and latestTags:
Look for a status block similar to:
You can also list all ImageRepository resources and their tag counts:
Example showing two tags discovered:
To confirm your running Deployment still uses the previous image tag (i.e., no automatic update has been performed yet):
Example output showing the deployment still using the older tag:

​
5. What’s next: automate updates with ImagePolicy and ImageUpdateAutomation

To enable fully automated GitOps image updates:
  • Create an ImagePolicy to select which tags are eligible (e.g., semantic versioning rules, regex).
  • Create an ImageUpdateAutomation that updates the manifests in your Git repository when a new tag matching the policy appears.
  • Flux will then update the Git repository and the GitRepository controller will apply the updated manifest, updating your Deployment.
Summary of the primary image automation resources: Example commands (overview):
Refer to Flux docs for detailed manifests and configuration options: the exact manifests depend on your repo structure, Git provider, and desired automation workflow.

​
Quick reference table: useful commands

That’s all for this demo. Follow-up steps: define an ImagePolicy and ImageUpdateAutomation to enable end-to-end automated image updates via GitOps.

Watch Video

Practice Lab