Charon/docs/plans/ci_artifact_handover.md

title, status, scope

title	status	scope
CI Docker Image Artifact Handover	draft	ci/integration, docker/build

1. Introduction

This plan updates the CI pipeline to pass the Docker image between jobs as a build artifact instead of pulling from a registry. The goal is to eliminate the integration-stage "invalid reference format" error by loading a known-good local image tag (charon:local) in each integration job.

Objectives:

• Export a Docker image tarball from the build stage, tagged charon:local.
• Upload the tarball as a CI artifact and consume it in integration jobs.
• Remove Docker Hub login and image pull steps from integration jobs.
• Ensure the export step reuses build cache to avoid double build time.

2. Research Findings

• The integration jobs in .github/workflows/ci-pipeline.yml currently log into Docker Hub and run docker pull using needs.build-image.outputs.image_ref_dockerhub.
• The reported "invalid reference format" error is consistent with an empty or malformed image reference at the pull step.
• The build job already uses docker/build-push-action for the main build/push step but does not export a local image tarball artifact.

3. Technical Specifications

3.1 Build Image Job: Export Artifact

Location: .github/workflows/ci-pipeline.yml job build-image.

Add a dedicated export step after the main build step:

• Use docker/build-push-action with:
  • platforms: linux/amd64
  • outputs: type=docker,dest=/tmp/charon.tar
  • tags: charon:local
• Ensure cache reuse to avoid a full rebuild:
  • Main build step: add cache-to: type=gha,mode=max
  • Export step: add cache-from: type=gha

Update the run_integration output in build-image:

• Set run_integration to true when the artifact build succeeds.
• Do not depend on steps.image-policy.outputs.push == true for integration gating.

Add an artifact upload step:

• Use actions/upload-artifact.
• name: docker-image
• path: /tmp/charon.tar
• retention-days: 1

3.2 Integration Jobs: Consume Artifact

Jobs:

• integration-cerberus
• integration-crowdsec
• integration-waf
• integration-ratelimit

Required changes:

• Remove steps:
  • "Log in to Docker Hub"
  • "Pull shared image"
• Add steps:
  • Download artifact via actions/download-artifact with name: docker-image and path: /tmp.
  • Load image via docker load --input /tmp/charon.tar.
  • Verify image availability with docker image inspect charon:local.

3.3 Image Tag Validation

• Ensure the export step sets tags: charon:local so integration tests continue to use the existing charon:local tag without changes to test scripts.

4. Implementation Plan

Phase 1: CI Build Artifact Export

1. Update build-image job to add cache settings to the existing docker/build-push-action step.
2. Add a new export step using docker/build-push-action with platforms: linux/amd64, outputs: type=docker,dest=/tmp/charon.tar, and tags: charon:local.
3. Upload /tmp/charon.tar as docker-image artifact.
4. Update run_integration output to depend on artifact build success only.

Phase 2: Integration Job Artifact Handover

1. Remove Docker Hub login and pull steps from each integration job.
2. Add actions/download-artifact for docker-image.
3. Add a docker load step and verify charon:local.

Phase 3: Validation

1. Confirm integration jobs no longer call docker pull.
2. Confirm docker image inspect charon:local succeeds before each integration test script.
3. Confirm build logs show cache reuse for the export step.

5. Acceptance Criteria (EARS)

• WHEN the build-image job completes, THE SYSTEM SHALL export a Docker tarball at /tmp/charon.tar tagged charon:local.
• WHEN the build-image job completes, THE SYSTEM SHALL upload the tarball as an artifact named docker-image.
• WHEN an integration job starts, THE SYSTEM SHALL download the docker-image artifact and load it with docker load.
• WHEN the image is loaded in an integration job, THE SYSTEM SHALL verify charon:local exists before running integration scripts.
• WHEN integration jobs run, THE SYSTEM SHALL NOT log into Docker Hub or pull from the registry.
• WHEN the export step runs, THE SYSTEM SHALL reuse the build cache from the main build step to avoid a full rebuild.
• WHEN the artifact build step succeeds, THE SYSTEM SHALL set run_integration to true regardless of registry push settings.

6. Risks and Mitigations

• Risk: Export step rebuilds the image, increasing CI time. Mitigation: Use cache-to on the main build step and cache-from on the export step to reuse the Buildx cache.

• Risk: Artifact download or load fails due to path issues. Mitigation: Use consistent /tmp/charon.tar path and add docker image inspect charon:local to fail fast.

7. Confidence Score

Confidence: 86 percent

Rationale: The workflow changes are limited to CI steps and standard Docker Buildx artifact handoff. The only uncertainty is whether the integration gate should also be adjusted to align with artifact-based handoff, which can be validated after implementation.