### Setup QEMU GitHub Action

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/INDEX.md

Example of using the docker/setup-qemu-action to set up QEMU for cross-platform builds in a GitHub Actions workflow. Version 4.0.0 is specified.

```yaml
steps:
- name: Set up QEMU
  uses: docker/setup-qemu-action@v4.0.0
```

--------------------------------

### Setup Buildx GitHub Action

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/INDEX.md

Example of using the docker/setup-buildx-action to set up Docker buildx in a GitHub Actions workflow. Version 4.1.0 is specified.

```yaml
steps:
- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v4.1.0
```

--------------------------------

### Cosign Installer GitHub Action

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/INDEX.md

Example of using the sigstore/cosign-installer action to install Cosign in a GitHub Actions workflow. Version 4.1.2 is specified.

```yaml
steps:
- name: Install Cosign
  uses: sigstore/cosign-installer@v4.1.2
```

--------------------------------

### Example Input Configuration: build_chunked_oci

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/INDEX.md

Provides an example of how the 'build_chunked_oci' input is documented, including its type, default value, incompatibilities, and environment variable mapping.

```text
- Input name: `build_chunked_oci`
- Type: boolean
- Default: `false`
- Incompatibilities: Cannot use with `rechunk: true`
- Environmental: Sets `BB_BUILD_CHUNKED_OCI`
```

--------------------------------

### Install SLSA Verifier Action

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

Installs the SLSA verifier tool. This step runs when signature verification is enabled.

```yaml
steps:
  - name: Install the slsa-verifier
    if: inputs.verify_install == 'true'
    uses: slsa-framework/slsa-verifier/actions/installer@ea584f4502babc6f60d9bc799dbbb13c1caa9ee6
    with:
      version: v2.7.1
```

--------------------------------

### Minimal Example (with squash)

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/validation-rules.md

Demonstrates a successful validation with squash enabled and a simple build_opts string.

```yaml
squash: "true"
build_opts: "--tag myimage:latest"
```

--------------------------------

### Check Cosign Installation

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/external-tools-dependencies.md

Verify that Cosign is installed and accessible in the runner's PATH. This command lists the Cosign executable in the expected installation directory.

```bash
ls -la /usr/bin/cosign
```

--------------------------------

### Install and extract BlueBuild CLI binary

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/external-tools-dependencies.md

Steps to pull the BlueBuild CLI installer image and extract the bluebuild binary.

```bash
# Pull installer image: ghcr.io/blue-build/cli:{version}-installer
# Extract binary from image: /out/bluebuild
# Copy to system: /usr/bin/bluebuild
```

--------------------------------

### QEMU Setup Configuration

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

Sets up QEMU, enabling the build of container images for multiple architectures on the GitHub runner. This is essential for cross-platform compatibility.

--------------------------------

### Build Options Example

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/action-inputs-reference.md

Provide additional options to the BlueBuild CLI build command. Multiple options can be space-separated.

```yaml
with:
  build_opts: "--tag latest --tag v1.0"
```

--------------------------------

### check_build_opts Example: Two Options

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/validation-rules.md

Demonstrates checking for the presence of either of two option flags in BUILD_OPTS.

```bash
check_build_opts "--build-driver" "--squash" "Cannot use either --build-driver or --squash"
```

--------------------------------

### Working Directory Example

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/action-inputs-reference.md

Change the working directory for the entire build process.

```yaml
with:
  working_directory: ./subproject/
```

--------------------------------

### Environment Variable Precedence Example

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/environment-variables.md

This YAML example illustrates how action inputs take precedence over environment variables when configuring the registry.

```yaml
# Both set the registry
registry: "custom.io"              # Action input (precedence 1)
BB_REGISTRY: "custom.io"           # Environment variable (precedence 2)
# Default would be ghcr.io
```

--------------------------------

### Valid Rechunk Example

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/validation-rules.md

Demonstrates a valid configuration where rechunk and rechunk_clear_plan are automatically added to build_opts.

```yaml
rechunk: "true"
rechunk_clear_plan: "true"
build_opts: "--tag myimage:latest"
```

--------------------------------

### Configure slsa-framework/slsa-verifier/actions/installer

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/external-tools-dependencies.md

Uses the slsa-framework/slsa-verifier action to install the SLSA verifier. This action is conditional and runs only when `verify_install` is set to 'true'.

```yaml
uses: slsa-framework/slsa-verifier/actions/installer@ea584f4502babc6f60d9bc799dbbb13c1caa9ee6
```

--------------------------------

### Cosign Installer Configuration

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

Installs the Cosign tool, used for signing and verifying container images, into the `/usr/bin` directory with sudo privileges. This ensures Cosign is available for image security operations.

```yaml
with:
  install-dir: /usr/bin
  use-sudo: true
```

--------------------------------

### BlueBuild with Custom Checkout and Pre-build Steps

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

This example demonstrates using a custom checkout with full history and pre-build steps to generate metadata. It skips the action's default checkout.

```yaml
name: Build with Custom Checkout

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate build metadata
        run: |
          echo "BUILD_TIMESTAMP=$(date -u +'%Y-%m-%dT%H:%M:%SZ')" >> $GITHUB_ENV
          echo "GIT_COMMIT=$(git rev-parse --short HEAD)" >> $GITHUB_ENV

      - uses: blue-build/github-action@v1
        with:
          recipe: recipe.yml
          cosign_private_key: ${{ secrets.SIGNING_SECRET }}
          pr_event_number: ${{ github.event.number }}
          skip_checkout: "true"
          working_directory: ./images/
          build_opts: "--tag build-${{ env.BUILD_TIMESTAMP }} --tag ${{ env.GIT_COMMIT }}"
```

--------------------------------

### Construct Installer Image URL

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

Defines the Docker image URL for the BlueBuild CLI installer based on the provided version tag.

```bash
CLI_INSTALLER_IMAGE="ghcr.io/blue-build/cli:${CLI_VERSION_TAG}-installer"
```

--------------------------------

### check_build_opts Example: Single Option

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/validation-rules.md

Demonstrates checking for the presence of a single option flag in BUILD_OPTS.

```bash
check_build_opts "--rechunk" "---" "Cannot use --rechunk"
```

--------------------------------

### Verify Installer Image with SLSA

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

Verifies the integrity of the BlueBuild CLI installer image using the SLSA verifier. This step is conditional and requires the SLSA verifier to be installed.

```bash
slsa-verifier verify-image "${CLI_INSTALLER_IMAGE}" \
    --source-uri github.com/blue-build/cli \
    "${VERIFY_FLAG}" "${REPO_TAG}"
```

--------------------------------

### Check Docker Buildx Version

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/external-tools-dependencies.md

Verify that Docker Buildx is installed and available on the runner. This command checks the installed version of Buildx.

```bash
docker buildx version
```

--------------------------------

### BlueBuild GitHub Action with Optimized Chunked OCI

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/REFERENCE.md

This example demonstrates using the `build_chunked_oci` option for optimized builds, along with specifying the maximum number of layers and enabling caching.

```yaml
- uses: blue-build/github-action@v1
  with:
    recipe: recipe.yml
    cosign_private_key: ${{ secrets.SIGNING_SECRET }}
    pr_event_number: ${{ github.event.number }}
    build_chunked_oci: "true"
    max_layers: "256"
    use_cache: "true"
```

--------------------------------

### Set CLI Version Tag

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/environment-variables.md

Define the version tag for constructing the CLI installer image URL. This is set in the 'Install BlueBuild' step.

```bash
export CLI_VERSION_TAG="v0.9"
```

--------------------------------

### Skip Checkout Example

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/action-inputs-reference.md

Set to true to skip the actions/checkout step, allowing manual checkout and modification before building.

```yaml
- uses: actions/checkout@v4
  with:
    # custom checkout options

- uses: blue-build/github-action@v1
  with:
    skip_checkout: true
```

--------------------------------

### Build with CLI Signature Verification

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

Enable signature verification for the BlueBuild CLI to ensure its integrity. This setup also installs the SLSA verifier and configures container policies for validation.

```yaml
name: Build with CLI Signature Verification

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: blue-build/github-action@v1
        with:
          recipe: recipe.yml
          cosign_private_key: ${{ secrets.SIGNING_SECRET }}
          pr_event_number: ${{ github.event.number }}
          verify_install: "true"
```

--------------------------------

### BlueBuild GitHub Action - Input Validation Script Example

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/action-architecture.md

Example of a Bash script used for validating input parameters in the BlueBuild GitHub Action. It checks for conflicting options and configuration issues.

```bash
#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
exit_on_error() {
  if [ "$1" -ne 0 ]; then
    echo "Error: $2"
    exit 1
  fi
}

# Check if two CLI flags are present, and if so, error out.
check_build_opts() {
  if [[ "$1" == "true" && "$2" == "true" ]]; then
    echo "Error: Cannot use both $3 and $4."
    exit 1
  fi
}

# Check if rechunk_clear_plan is enabled.
sets_clear_plan() {
  if [[ "${{ inputs.rechunk_clear_plan }}" == "true" ]]; then
    return 0 # 0 means true in bash
  else
    return 1 # 1 means false in bash
  fi
}

# Validate clear plan configuration.
clear_plan_build_opts_check() {
  if sets_clear_plan;
  then
    check_build_opts "${{ inputs.force_rebuild }}" "${{ inputs.skip_build }}" "--force-rebuild" "--skip-build"
    check_build_opts "${{ inputs.force_rebuild }}" "${{ inputs.skip_build }}" "--force-rebuild" "--skip-build"
  fi
}

# Main execution
clear_plan_build_opts_check
exit_on_error $? "Input validation failed."

exit 0
```

--------------------------------

### Custom Build Options Example

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/action-architecture.md

Pass arbitrary flags to the `bluebuild build` command using the `build_opts` input. All options are validated to prevent conflicts with action-controlled flags.

```yaml
build_opts: "--verbose --tag v1.0.0 --tag latest"
```

--------------------------------

### Set CLI Signature Verification Flag

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/environment-variables.md

Control whether to verify the CLI signature during installation. Set to 'true' or 'false' in the 'Install BlueBuild' step.

```bash
export VERIFY_INSTALL="false"
```

--------------------------------

### Conflicting Example (should fail)

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/validation-rules.md

Demonstrates a validation failure due to conflicting flags: 'squash' is true and '--squash' is also provided in build_opts.

```yaml
squash: "true"
build_opts: "--squash --tag myimage:latest"
```

--------------------------------

### Retry Push Count Example

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/action-inputs-reference.md

Configure the number of times to retry pushing the image to the registry.

```yaml
with:
  retry_push_count: "3"
```

--------------------------------

### Custom Working Directory Example

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/action-architecture.md

Build from subdirectories within a monorepo using the `working_directory` input. This is useful when recipes are located in different directories.

```yaml
working_directory: "./subproject/"
```

--------------------------------

### Set Repository Tag for SLSA Verification

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/environment-variables.md

Specify the repository reference for SLSA verification. This is set in the 'Install BlueBuild' step.

```bash
export REPO_TAG="v0.9.0"
```

--------------------------------

### Invalid Rechunk Clear Plan Example

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/validation-rules.md

Shows an invalid configuration where rechunk_clear_plan is set to true while build_chunked_oci and rechunk are false, resulting in an error.

```yaml
build_chunked_oci: "false"
rechunk: "false"
rechunk_clear_plan: "true"
```

--------------------------------

### Docker Buildx Setup Configuration

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

Configures Docker Buildx for container image builds, enabling cache support when the `use_cache` input is true. This step is skipped if advanced features like squash or chunked OCI are enabled.

```yaml
with:
  driver: docker-container
  cache-binary: ${{ inputs.use_cache }}
```

--------------------------------

### Squashed Build with Podman using BlueBuild

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

This configuration performs a squashed build, resulting in a smaller final image by disabling layer caching. It requires an Ubuntu 22.04 runner and automatically installs Podman.

```yaml
name: Build Squashed Image

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: blue-build/github-action@v1
        with:
          recipe: recipe.yml
          cosign_private_key: ${{ secrets.SIGNING_SECRET }}
          pr_event_number: ${{ github.event.number }}
          squash: "true"
          maximize_build_space: "true"
```

--------------------------------

### Custom CLI Version Examples

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/action-architecture.md

Specify a custom version for the BlueBuild CLI using the `cli_version` input. This allows using development branches, release candidates, or specific commits.

```yaml
cli_version: "main"           # Use development branch
```

```yaml
cli_version: "v0.10.0-rc1"    # Use release candidate
```

```yaml
cli_version: "abc123def"      # Use specific commit
```

--------------------------------

### SLSA Verifier GitHub Action

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/INDEX.md

Example of using the slsa-framework/slsa-verifier action to verify SLSA provenance in a GitHub Actions workflow. Version 2.7.1 is specified.

```yaml
steps:
- name: Run SLSA Verifier
  uses: slsa-framework/slsa-verifier@v2.7.1
```

--------------------------------

### Get Ubuntu Version Script

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

This bash script detects the Ubuntu version of the GitHub runner and outputs it. The detected version is stored in the `steps.ubuntu_version.outputs.version` output variable.

```bash
VERSION=$(awk -F= '/^VERSION_ID=/ {gsub(/
```

```bash
="$VERSION" >> "$GITHUB_OUTPUT"

```

--------------------------------

### Free Disk Space GitHub Action

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/INDEX.md

Example of using the hastd/free-disk-space action to free up disk space in a GitHub Actions workflow. Version 0.1.2 is specified.

```yaml
steps:
- name: Free disk space
  uses: hastd/free-disk-space@v0.1.2
```

--------------------------------

### Validation Rule Example: build_chunked_oci and rechunk conflict

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/INDEX.md

Illustrates a specific validation rule from validation-rules.md, highlighting the conflict between the 'build_chunked_oci' and 'rechunk' inputs and the corresponding error message.

```text
Rule: build_chunked_oci and rechunk cannot both be true
Error: Cannot set both 'build_chunked_oci' and 'rechunk' to true.
Location: build_opts_check.sh:41-45
```

--------------------------------

### Matrix Builds (Multiple Images)

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

Set up matrix builds to create multiple images, such as Fedora, Ubuntu, and Debian, using a single workflow.

```yaml
strategy:
  matrix:
    image: [fedora, ubuntu, debian]
steps:
  - uses: blue-build/github-action@v1
    with:
      recipe: ${{ matrix.image }}-recipe.yml
      cosign_private_key: ${{ secrets.SIGNING_SECRET }}
      pr_event_number: ${{ github.event.number }}
```

--------------------------------

### Blue Build Command Construction

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/environment-variables.md

This shows how the build command is constructed using environment variables and build options.

```bash
bluebuild build -v [BUILD_OPTS] "${RECIPE_PATH}"
```

--------------------------------

### Build Process Steps Overview

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/INDEX.md

This snippet lists the 13 sequential steps involved in the BlueBuild GitHub Action's build process, as detailed in build-process-steps.md.

```text
Step 1:  Validate inputs
Step 2:  Maximize build space
Step 3:  Set up Docker Buildx
Step 4:  Get Ubuntu version
Step 5:  Setup Podman
Step 6:  Install Cosign
Step 7:  Set up QEMU
Step 8:  Install SLSA Verifier
Step 9:  Checkout repository
Step 10: Set Container Policy
Step 11: Determine Vars
Step 12: Install BlueBuild
Step 13: Build Image
```

--------------------------------

### Enable Image Push

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/environment-variables.md

Export BB_BUILD_PUSH as "true" to enable pushing the built image to the registry. Defaults to "true".

```bash
export BB_BUILD_PUSH="true"
```

--------------------------------

### Pull BlueBuild CLI Installer Image from GHCR

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/external-tools-dependencies.md

This command pulls the BlueBuild CLI installer image from GitHub Container Registry (GHCR). It requires the registry to be accessible from the GitHub runner and uses the `registry_token` for authentication if provided.

```bash
docker pull ghcr.io/blue-build/cli:{version}-installer
```

--------------------------------

### Key Inputs Documented in action-inputs-reference.md

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/INDEX.md

Lists the primary input parameters documented in the action-inputs-reference.md file, which details all configuration options for the BlueBuild GitHub Action.

```text
recipe, cosign_private_key, push, registry_token, registry_username,
pr_event_number, maximize_build_space, use_unstable_cli, cli_version,
registry, registry_namespace, build_chunked_oci, max_layers, rechunk,
rechunk_clear_plan, use_cache, retry_push_count, squash, build_opts,
working_directory, skip_checkout, verify_install
```

--------------------------------

### Build with BlueBuild CLI

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/external-tools-dependencies.md

Basic command to initiate a build using the BlueBuild CLI, specifying options and the recipe path.

```bash
bluebuild build -v [OPTIONS] [RECIPE_PATH]
```

--------------------------------

### Best Practices: Use Signing

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

Always use signing for security by providing your Cosign private key.

```yaml
cosign_private_key: ${{ secrets.SIGNING_SECRET }}
```

--------------------------------

### Minimal BlueBuild GitHub Action Usage

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

This is the simplest way to use the action. It requires only the recipe file and a signing key.

```yaml
name: Build Custom OS Image

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: blue-build/github-action@v1
        with:
          recipe: recipe.yml
          cosign_private_key: ${{ secrets.SIGNING_SECRET }}
          pr_event_number: ${{ github.event.number }}
```

--------------------------------

### Add unstable Podman repository for Ubuntu

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/external-tools-dependencies.md

Specifies the repository source for installing Podman version 4+ on Ubuntu 22.04.

```bash
deb https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/unstable/xUbuntu_22.04/ /

```

--------------------------------

### Standard Production Workflow for BlueBuild

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

This workflow builds, signs, and pushes the OS image to GitHub Container Registry. It also maximizes build space.

```yaml
name: Build and Push OS Image

on:
  push:
    branches: [main]
    tags: ['v*']
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: blue-build/github-action@v1
        with:
          recipe: main-image.yml
          cosign_private_key: ${{ secrets.SIGNING_SECRET }}
          pr_event_number: ${{ github.event.number }}
          push: "true"
          registry: ghcr.io
          registry_username: ${{ github.repository_owner }}
          registry_token: ${{ github.token }}
          registry_namespace: ${{ github.repository_owner }}
          maximize_build_space: "true"
```

--------------------------------

### Checkout GitHub Action

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/INDEX.md

Example of using the actions/checkout action to check out code in a GitHub Actions workflow. Version 6.0.2 is specified.

```yaml
steps:
- uses: actions/checkout@v6.0.2
```

--------------------------------

### Add Squash Options to Build

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

Appends `--build-driver podman` and `--squash` to the BUILD_OPTS array if the 'squash' input is true.

```bash
BUILD_OPTS+=("--build-driver" "podman" "--squash")
```

--------------------------------

### Troubleshooting: Enable Disk Space Maximization

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

Enable disk space maximization to resolve 'No space left on device' errors during builds.

```yaml
maximize_build_space: "true"
```

--------------------------------

### Specify a Recipe File

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/action-inputs-reference.md

Use the 'recipe' input to specify the YAML file for building a custom image. The action checks both './config/' and './recipes/' directories for the specified file.

```yaml
- uses: blue-build/github-action@v1
  with:
    recipe: custom-image.yml
```

--------------------------------

### User-Provided Inputs for Blue Build

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/environment-variables.md

These environment variables are set by the user to configure the build process. They cover authentication, build options, and registry settings.

```bash
export COSIGN_PRIVATE_KEY="-----BEGIN ENCRYPTED COSIGN PRIVATE KEY-----
MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQI...\n-----END ENCRYPTED COSIGN PRIVATE KEY-----"

export GH_TOKEN="ghp_1234567890abcdef"
export GH_PR_EVENT_NUMBER="42"
export BB_BUILD_PUSH="true"
export BB_PASSWORD="ghp_1234567890abcdef"
export BB_USERNAME="myusername"
export BB_REGISTRY="ghcr.io"
export BB_REGISTRY_NAMESPACE="myorg"
export BB_CACHE_LAYERS="false"
export BB_RETRY_PUSH_COUNT="0"
export BB_SQUASH="false"
export BB_BUILD_CHUNKED_OCI="false"
export BB_RECHUNK="false"
export BB_BUILD_RECHUNK_CLEAR_PLAN="false"
export RECIPE_PATH="./recipes/recipe.yml"
```

--------------------------------

### Set SLSA Verification Flag

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/environment-variables.md

Determine the flag type for SLSA verification (e.g., --source-tag or --source-branch). This is set in the 'Install BlueBuild' step.

```bash
export VERIFY_FLAG="--source-tag"
```

--------------------------------

### Configure actions/checkout

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/external-tools-dependencies.md

Clones the user's repository into the GitHub runner workspace. Set `persist-credentials: false` for security best practices.

```yaml
with:
  persist-credentials: false
```

--------------------------------

### Checkout Repository Action

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

Clones the user's repository into the runner workspace. Credentials are not persisted for security.

```yaml
steps:
  - name: Checkout repository
    if: inputs.skip_checkout == 'false'
    uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
    with:
      persist-credentials: false
```

--------------------------------

### Minimal GitHub Actions Workflow

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/README.md

A basic workflow to build a custom OS image using the BlueBuild GitHub Action. Ensure necessary permissions and secrets are configured.

```yaml
name: Build Custom OS Image

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: blue-build/github-action@v1
        with:
          recipe: recipe.yml
          cosign_private_key: ${{ secrets.SIGNING_SECRET }}
          pr_event_number: ${{ github.event.number }}
          push: "true"
          registry_token: ${{ github.token }}

```

--------------------------------

### Using Custom Build Driver

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

Specify a custom build driver, such as Podman, using the `--build-driver` option. Ensure `squash` is set to `false` when using a custom build driver, as they conflict.

```yaml
build_opts: "--build-driver podman"
```

--------------------------------

### Best Practices: Use Minimal Permissions

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

Configure minimal permissions for the action to enhance security by adhering to the principle of least privilege.

```yaml
permissions:
  contents: read
  packages: write
```

--------------------------------

### BlueBuild GitHub Action for Production with Push

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/REFERENCE.md

This configuration is for production builds where the image needs to be pushed to a registry. It includes the necessary inputs for pushing and authentication.

```yaml
- uses: blue-build/github-action@v1
  with:
    recipe: recipe.yml
    cosign_private_key: ${{ secrets.SIGNING_SECRET }}
    pr_event_number: ${{ github.event.number }}
    push: "true"
    registry_token: ${{ github.token }}
```

--------------------------------

### Dynamic Recipe Path Resolution Logic

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/environment-variables.md

Illustrates the logic for resolving the RECIPE_PATH based on the existence of the recipe file in './config/' or './recipes/'.

```bash
if [ -f "./config/${RECIPE}" ]; then
  RECIPE_PATH="./config/${RECIPE}"
else
  RECIPE_PATH="./recipes/${RECIPE}"
fi
```

--------------------------------

### Applying Custom Registry Configuration

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

Configure custom registry settings, including the registry URL and namespace prefix, using the `--registry` and `--registry-prefix` options.

```yaml
build_opts: "--registry docker.io --registry-prefix my-org"
```

--------------------------------

### Build from Subdirectory Configuration

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

Configure the `working_directory` and `recipe` to build images from a subdirectory within your repository. This is useful for monorepo structures.

```yaml
working_directory: ./images/
recipe: base.yml
```

--------------------------------

### Key Sections in REFERENCE.md

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/INDEX.md

This snippet outlines the main sections covered in the REFERENCE.md document, providing a high-level overview of the action's features and architecture.

```yaml
# Key sections:
- Project Summary
- Key Features (5 areas)
- Action Inputs (Summary Table)
- Build Process (13 Steps)
- Validation Rules (Key Constraints)
- Conditional Execution Paths (4 paths)
- Architecture Overview
```

--------------------------------

### Enable Chunked OCI Build

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/environment-variables.md

Export BB_BUILD_CHUNKED_OCI as "true" to enable the chunked OCI build format. Defaults to "false".

```bash
export BB_BUILD_CHUNKED_OCI="true"
```

--------------------------------

### Execute Build with Sudo

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

Executes the BlueBuild command with sudo if the RUN_SUDO environment variable is set.

```bash
sudo -E bluebuild build
```

--------------------------------

### Enable Rechunking for Efficient Updates

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/environment-variables.md

Activate the rechunking process to optimize image updates. Defaults to 'false' if not specified.

```bash
export BB_RECHUNK="true"
```

--------------------------------

### Advanced BlueBuild Configuration with Optimization

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

This configuration enables chunked OCI builds, layer caching, and custom tagging for optimized images.

```yaml
name: Build Optimized OS Image

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: blue-build/github-action@v1
        with:
          recipe: optimized-image.yml
          cosign_private_key: ${{ secrets.SIGNING_SECRET }}
          pr_event_number: ${{ github.event.number }}
          push: "true"
          registry: ghcr.io
          registry_namespace: my-org
          build_chunked_oci: "true"
          max_layers: "256"
          use_cache: "true"
          maximize_build_space: "true"
          build_opts: "--tag latest --tag ${{ github.sha }}"
```

--------------------------------

### BlueBuild Build Command Structure

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/action-architecture.md

The core command used to build an image. Auto-added options depend on build configurations like squash, rechunk, and retry settings.

```bash
bluebuild build -v [AUTO-ADDED-OPTS] [BUILD_OPTS] [RECIPE_PATH]
```

--------------------------------

### Add Rechunk Options to Build

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

Sets RUN_SUDO to 1 and adds the `--rechunk` flag to build options if the 'rechunk' input is true.

```bash
BUILD_OPTS+=("--rechunk")
```

--------------------------------

### Free Disk Space Configuration

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

This configuration for the `hastd/free-disk-space` action skips the process if the runner has at least 80GB of free disk space. Use this step to ensure sufficient space for builds.

```yaml
with:
  skip-if-available: "80G"
```

--------------------------------

### Determine Build Variables

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

Resolves dynamic configuration variables for CLI version and recipe path using bash scripting. Outputs include CLI version, repository tag, verification flag, and recipe path.

```bash
steps:
  - name: Determine Vars
    id: build_vars
    shell: bash
    run: |
      # CLI Version Resolution
      if [[ "${{ inputs.use_unstable_cli }}" == 'true' ]] && [[ -z "${{ inputs.cli_version }}" ]]; then
        cli_version="main"
        repo_tag="main"
        verify_flag="--source-branch"
      elif [[ -n "${{ inputs.cli_version }}" ]]; then
        cli_version="${{ inputs.cli_version }}"
        repo_tag="${{ inputs.cli_version }}"
        if [[ "${{ inputs.cli_version }}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
          verify_flag="--source-tag"
        else
          verify_flag="--source-branch"
        fi
      else
        # Fetch latest tag from GitHub API for stable version
        latest_tag=$(curl -sH "Authorization: token ${{ github.token }}" https://api.github.com/repos/blue-build/cli/tags | jq -r '.[0].name')
        cli_version="v0.9" # Default stable version
        repo_tag="${{ latest_tag }}"
        verify_flag="--source-tag"
      fi

      # Recipe Path Resolution
      if [[ -e "./config/${{ inputs.recipe }}" ]]; then
        recipe_path="./config/${{ inputs.recipe }}"
      else
        recipe_path="./recipes/${{ inputs.recipe }}"
      fi

      # Set output variables
      echo "cli_version=${cli_version}" >> $GITHUB_OUTPUT
      echo "repo_tag=${repo_tag}" >> $GITHUB_OUTPUT
      echo "verify_flag=${verify_flag}" >> $GITHUB_OUTPUT
      echo "recipe_path=${recipe_path}" >> $GITHUB_OUTPUT
    env:
      RECIPE: ${{ inputs.recipe }}
      USE_UNSTABLE_CLI: ${{ inputs.use_unstable_cli }}
      CLI_VERSION: ${{ inputs.cli_version }}
      AUTH_HEADER: "token ${{ github.token }}"
```

--------------------------------

### Execute Build without Sudo

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

Executes the BlueBuild command directly without sudo.

```bash
bluebuild build
```

--------------------------------

### BlueBuild GitHub Action - High-Level Architecture Diagram

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/action-architecture.md

Visual representation of the BlueBuild GitHub Action's pipeline orchestration pattern, showing the sequential steps from input parameters to output.

```text
┌─────────────────────────────────────────────────────────────────┐
│                   GitHub Actions Workflow                        │
├─────────────────────────────────────────────────────────────────┤
│  INPUT PARAMETERS (13 inputs defined in action.yml)             │
│  - recipe, cosign_private_key, push, registry config, etc.      │
├─────────────────────────────────────────────────────────────────┤
│ VALIDATION LAYER                                                 │
│ └─ Step 1: Validate inputs (build_opts_check.sh)               │
├─────────────────────────────────────────────────────────────────┤
│ ENVIRONMENT PREPARATION LAYER                                   │
│ ├─ Step 2: Maximize build space (hastd/free-disk-space)        │
│ ├─ Step 3: Set up Docker Buildx (conditional)                  │
│ ├─ Step 4: Get Ubuntu version (detect runner OS)               │
│ ├─ Step 5: Setup Podman (conditional for Ubuntu 22.04)         │
│ └─ Step 6: Install cosign                                       │
├─────────────────────────────────────────────────────────────────┤
│ MULTI-ARCHITECTURE SETUP LAYER                                   │
│ └─ Step 7: Set up QEMU                                          │
├─────────────────────────────────────────────────────────────────┤
│ SECURITY & VERIFICATION LAYER                                    │
│ ├─ Step 8: Install SLSA Verifier (conditional)                 │
│ ├─ Step 9: Checkout repository (conditional)                   │
│ └─ Step 10: Set container policy (conditional)                 │
├─────────────────────────────────────────────────────────────────┤
│ CONFIGURATION RESOLUTION LAYER                                   │
│ └─ Step 11: Determine Vars (resolve CLI version & recipe path) │
├─────────────────────────────────────────────────────────────────┤
│ CLI INSTALLATION LAYER                                           │
│ └─ Step 12: Install BlueBuild CLI                              │
├─────────────────────────────────────────────────────────────────┤
│ BUILD EXECUTION LAYER                                            │
│ └─ Step 13: Build Image (executes bluebuild build command)     │
├─────────────────────────────────────────────────────────────────┤
│ OUTPUT                                                            │
│ └─ Built image pushed to container registry (if push: true)    │
└─────────────────────────────────────────────────────────────────┘
```

--------------------------------

### Set Registry Namespace

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/environment-variables.md

Export the BB_REGISTRY_NAMESPACE environment variable with the registry namespace or organization. Defaults to the GitHub repository owner.

```bash
export BB_REGISTRY_NAMESPACE="myorg"
```

--------------------------------

### File Organization Structure

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/README.md

This snippet shows the directory structure for the BlueBuild GitHub Action documentation, outlining the purpose of each markdown file.

```markdown
output/
├── INDEX.md                              (Navigation hub)
├── REFERENCE.md                          (Overview & summary)
├── README.md                             (This file)
│
├── action-inputs-reference.md            (Input parameters)
├── action-architecture.md                (System design)
├── build-process-steps.md                (Build pipeline)
├── validation-rules.md                   (Input validation)
├── environment-variables.md              (Runtime env)
├── external-tools-dependencies.md        (Tools & services)
└── implementation-guide.md               (Usage examples)

```

--------------------------------

### Execute BlueBuild Image Build

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/build-process-steps.md

The primary command to build a container image using the BlueBuild CLI. It accepts build options and the path to the recipe file.

```bash
bluebuild build -v [BUILD_OPTS] [RECIPE_PATH]
```

--------------------------------

### Skip Disk Space Maximization

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

Use this setting for small images that do not require significant disk space to save build time.

```yaml
maximize_build_space: "false"
```

--------------------------------

### Maximize Build Space

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/action-inputs-reference.md

Enable 'maximize_build_space' to run a disk space optimization step, removing unneeded software. This defaults to 'true' but can be disabled for faster builds if sufficient space is available.

```yaml
with:
  maximize_build_space: true
```

--------------------------------

### Set Registry Username

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/environment-variables.md

Export the BB_USERNAME environment variable with your registry authentication username. Defaults to the GitHub repository owner.

```bash
export BB_USERNAME="myusername"
```

--------------------------------

### Best Practices: Use Stable CLI Version

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

Use the stable CLI version in production to ensure reliability and avoid potential issues associated with unstable releases.

```yaml
use_unstable_cli: "false"
```

--------------------------------

### Enable Layer Caching

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/environment-variables.md

Export BB_CACHE_LAYERS as "true" to enable layer caching for Docker Buildx. Defaults to "false".

```bash
export BB_CACHE_LAYERS="true"
```

--------------------------------

### Input Incompatibilities for BlueBuild GitHub Action

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/REFERENCE.md

Lists pairs of inputs that cannot be used together and options that are forbidden when certain configurations are active. Use this to avoid runtime errors and unexpected behavior.

```markdown
❌ Cannot use together:
   - build_chunked_oci: true + rechunk: true
   - rechunk_clear_plan: true + (build_chunked_oci: false AND rechunk: false)

❌ Cannot add to build_opts:
   - "--push" (always forbidden)
   - "--squash" or "-s" (if squash: true)
   - "--build-driver" or "-B" (if squash: true)
   - "--build-chunked-oci" (if build_chunked_oci: true)
   - "--rechunk" (if rechunk: true)
   - "--rechunk-clear-plan" (if rechunk_clear_plan: true)
```

--------------------------------

### Troubleshooting: Enable Retry Logic for Pushes

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/implementation-guide.md

Configure retry logic for push operations to mitigate 'Failed to push image' errors caused by transient network issues.

```yaml
retry_push_count: "3"
```

--------------------------------

### Provide Cosign Private Key for Signing

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/action-inputs-reference.md

The 'cosign_private_key' input is required to sign the built image using Sigstore/cosign. Provide the secret containing your signing key.

```yaml
with:
  cosign_private_key: ${{ secrets.SIGNING_SECRET }}
```

--------------------------------

### Environment Variables Reference

Source: https://github.com/blue-build/github-action/blob/main/_autodocs/INDEX.md

This snippet lists key environment variables used by the BlueBuild action, their purpose, and their source. Useful for debugging and custom scripting.

```bash
COSIGN_PRIVATE_KEY      → Image signing key
BB_REGISTRY             → Container registry hostname
BB_RETRY_PUSH_COUNT     → Push retry attempts
RECIPE_PATH             → Resolved recipe file path
RUST_LOG_STYLE          → Always "always" for colored logs
```