release.yml

# Workflow name displayed on the GitHub Actions UI.
name: Publish Docker Image to GHCR

# This block defines the trigger for the workflow.
# It's configured to run exclusively when a new release is published in the repository.
# This ensures that images are only built and pushed for official, versioned releases.
on:
  release:
    types: [edited , created , published] # Triggers on release creation, editing, or publishing.

# Defines the jobs that will be executed as part of the workflow.
jobs:
  # A single job named 'build-and-publish' is defined.
  build-and-publish:
    # A descriptive name for the job, visible in the GitHub Actions UI.
    name: Build and Publish to GHCR
    # Specifies that the job will run on the latest version of an Ubuntu Linux runner.
    runs-on: ubuntu-latest
    # Sets the permissions granted to the GITHUB_TOKEN for this job.
    # This is the most secure way to grant access, avoiding the need for personal access tokens.
    permissions:
      contents: read      # Allows the job to checkout the repository's code.
      packages: write    # Allows the job to push Docker images to the GitHub Container Registry (GHCR).

    # A sequence of steps that make up the job.
    steps:
      # Step 1: Checks out the repository's source code.
      # This makes the Dockerfile and application code available to the runner.
      - name: Checkout repository
        uses: actions/checkout@v4

      # Step 2: Sets up Docker Buildx.
      # Buildx is a Docker CLI plugin that enables advanced features like creating multi-platform builds.
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      # Step 3: Logs in to the GitHub Container Registry (GHCR).
      # This step authenticates the runner, allowing it to push the built image to GHCR.
      - name: Log in to the GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          # The standard GITHUB_TOKEN is used for authentication.
          # Its permissions are defined in the 'permissions' block above.
          password: ${{ secrets.GB_TOKEN }}

      # Step 4: Extracts metadata for the Docker image.
      # This action automatically generates appropriate tags and labels for the image
      # based on the Git context (e.g., the release version).
      - name: Extract metadata (tags, labels) for Docker
        id: meta # Assigns an ID to this step so its outputs can be referenced later.
        uses: docker/metadata-action@v5
        with:
          # Specifies the name of the image. ghcr.io/${{ github.repository }} will be automatically
          # converted to lowercase, e.g., ghcr.io/euclidstellar/code-review-agent.
          images: ghcr.io/${{ github.repository }}
          # The action automatically creates tags from the release version.
          # For a release 'v1.2.3', it will generate tags: 'v1.2.3', 'v1.2', 'v1', and 'latest'.
          tags: type=raw,value=v1
      # Step 5: Builds the Docker image and pushes it to GHCR.
      # This step uses the Dockerfile in the root of the repository.
      - name: Build and push multi-platform image
        uses: docker/build-push-action@v5
        with:
          # The build context is the current directory ('.').
          context: .
          # 'true' indicates that the image should be pushed to the registry after a successful build.
          push: true
          # Builds the image for both AMD64 and ARM64 architectures, making the action more versatile.
          platforms: linux/amd64,linux/arm64
          # Uses the tags generated by the 'meta' step (e.g., v1.2.3, v1, latest).
          tags: ${{ steps.meta.outputs.tags }}
          # Applies the labels generated by the 'meta' step for better image organization.
          labels: ${{ steps.meta.outputs.labels }}