### Build with docker/bake-action Example

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/README.md

This example shows how to use the cache configuration action with `docker/bake-action`. It integrates with `docker/metadata-action` and defines targets in a `docker-bake.hcl` file.

```yaml
- uses: docker/metadata-action@v3
  id: metadata
  with:
    images: ghcr.io/${{ github.repository }}
- uses: int128/docker-build-cache-config-action@v1
  id: cache
  with:
    image: ghcr.io/${{ github.repository }}/cache
- uses: docker/bake-action@v5
  id: build
  with:
    push: true
    files: |
      ./docker-bake.hcl
      ${{ steps.metadata.outputs.bake-file }}
      ${{ steps.cache.outputs.bake-file }}
```

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

### Build with docker/build-push-action Example

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/README.md

This example demonstrates integrating the cache configuration action with `docker/build-push-action` for a complete build process. It utilizes `docker/metadata-action` to manage image tags and labels.

```yaml
- uses: docker/metadata-action@v3
  id: metadata
  with:
    images: ghcr.io/${{ github.repository }}
- uses: int128/docker-build-cache-config-action@v1
  id: cache
  with:
    image: ghcr.io/${{ github.repository }}/cache
- uses: docker/build-push-action@v2
  id: build
  with:
    push: true
    tags: ${{ steps.metadata.outputs.tags }}
    labels: ${{ steps.metadata.outputs.labels }}
    cache-from: ${{ steps.cache.outputs.cache-from }}
    cache-to: ${{ steps.cache.outputs.cache-to }}
```

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

### Example Docker Bake HCL Configuration

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/bake.md

Provides an example of a Docker Bake configuration file in HCL format, defining a target and inheriting cache settings.

```hcl
target "docker-build-cache-config-action" {}

target "default" {
  inherits = ["docker-build-cache-config-action"]
  context = "."
}
```

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

### Integration with Docker Build Push Action

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/run.md

This example demonstrates the complete integration of `int128/docker-build-cache-config-action` with `docker/build-push-action`, showing how to pass cache outputs.

```yaml
- uses: int128/docker-build-cache-config-action@v1
  id: cache
  with:
    image: ghcr.io/${{ github.repository }}/cache

- uses: docker/build-push-action@v5
  with:
    cache-from: ${{ steps.cache.outputs.cache-from }}
    cache-to: ${{ steps.cache.outputs.cache-to }}
```

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

### Cache-To Output Example (Import Only)

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/run.md

An empty string output for `cache-to` indicates that the cache will only be imported and not exported.

```text
(empty string)
```

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

### Cache-From Output Example

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/run.md

This output provides multiple Docker `--cache-from` flag values, separated by newlines. Use this directly with docker/build-push-action.

```text
type=registry,ref=ghcr.io/myorg/cache:pr-123
type=registry,ref=ghcr.io/myorg/cache:main
```

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

### Docker Build Push Action Cache-From Configuration

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/run.md

Example of how to use the `cache-from` output from the action within the `docker/build-push-action`.

```yaml
- uses: docker/build-push-action@v5
  with:
    cache-from: ${{ steps.cache.outputs.cache-from }}
```

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

### Cache-To Output Example (Single Destination)

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/run.md

This output specifies a single destination for the Docker cache, including the reference and mode for export.

```text
type=registry,ref=ghcr.io/myorg/cache:main,mode=max
```

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

### Flavor Escaping Example

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/event-handling.md

Demonstrates how forward slashes in flavor-decorated tags are escaped. The example shows that the '/' from the base branch is already escaped to '-' before flavor application.

```text
Base branch: refs/feature/x
Flavor: suffix=-cache
Tag formation: feature-x-cache
(The / from refs/feature/x is already escaped to -)
```

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

### Configure Docker Buildx Action for Debugging

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/README.md

Enable debug logging for the docker/setup-buildx-action to get more detailed output during builds. This is useful for troubleshooting.

```yaml
- uses: docker/setup-buildx-action@v3
  with:
    driver-options: debug=true
```

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

### Example Workflow with Docker Bake Action

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/bake.md

Illustrates a GitHub Actions workflow using the docker-build-cache-config-action to generate a bake file and then using docker/bake-action to build and push.

```yaml
- uses: int128/docker-build-cache-config-action@v1
  id: cache
  with:
    image: ghcr.io/${{ github.repository }}/cache
    bake-target: docker-build-cache-config-action

- uses: docker/bake-action@v5
  with:
    push: true
    files: |
      ./docker-bake.hcl
      ${{ steps.cache.outputs.bake-file }}
```

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

### Bake File Output Example (JSON)

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/run.md

This JSON structure represents the content of a temporary Docker Bake configuration file, detailing cache settings.

```json
{
  "target": {
    "docker-build-cache-config-action": {
      "cache-from": [
        "type=registry,ref=ghcr.io/myorg/cache:main"
      ],
      "cache-to": [
        "type=registry,ref=ghcr.io/myorg/cache:main,mode=max"
      ]
    }
  }
}
```

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

### Pull Request Cache Setup

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/README.md

Configures the action to enable caching specifically for pull request builds.

```yaml
- uses: int128/docker-build-cache-config-action@v1
  id: cache
  with:
    image: ghcr.io/${{ github.repository }}/cache
    pull-request-cache: true
```

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

### Docker Build Push Action Cache Configuration

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/README.md

Example of how to use the outputs from the build cache action with the docker/build-push-action. Ensure the cache-from and cache-to outputs are correctly referenced.

```yaml
cache-from: ${{ steps.cache.outputs.cache-from }}
cache-to: ${{ steps.cache.outputs.cache-to }}
```

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

### Build Multi-Architecture Images with Tag Suffixes

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/README_EXAMPLES.md

Use a tag suffix to isolate caches for each architecture when building multi-architecture Docker images. This example demonstrates setting up metadata, cache configuration, and the build-push action for different platforms.

```yaml
jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        platform:
          - linux/amd64
          - linux/arm64
    steps:
      - uses: docker/metadata-action@v3
        id: metadata
        with:
          images: ghcr.io/${{ github.repository }}
          flavor: suffix=-${{ matrix.platform }}
      - uses: int128/docker-build-cache-config-action@v1
        id: cache
        with:
          image: ghcr.io/${{ github.repository }}/cache
          flavor: suffix=-${{ matrix.platform }}
      - uses: docker/build-push-action@v2
        id: build
        with:
          push: true
          tags: ${{ steps.metadata.outputs.tags }}
          labels: ${{ steps.metadata.outputs.labels }}
          cache-from: ${{ steps.cache.outputs.cache-from }}
          cache-to: ${{ steps.cache.outputs.cache-to }}
          platforms: ${{ matrix.platform }}
```

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

### Fetch Pull Request Details

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/github.md

Example of using the Octokit client to fetch details of a specific pull request. Requires owner, repo, and pull_number.

```typescript
const octokit = getOctokit()
const { data: pull } = await octokit.rest.pulls.get({
  owner: 'myorg',
  repo: 'myrepo',
  pull_number: 123,
})
console.log(pull.base.ref) // Base branch name
```

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

### Cache Strategy Examples

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/INDEX.md

Details different cache strategies based on the Git event, such as push to branch or pull request. This is crucial for configuring effective caching mechanisms.

```text
On push to branch:
  → cache-from: REPO:branch-name
  → cache-to: REPO:branch-name

On pull request (default):
  → cache-from: REPO:main (base branch)
  → cache-to: (empty)

On pull request (with pull-request-cache: true):
  → cache-from: REPO:pr-123, REPO:main
  → cache-to: REPO:pr-123
```

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

### Build Multiple Image Tags with Environment-Specific Caches

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/README_EXAMPLES.md

Separate caches for different environments when building multiple image tags from a branch. This example uses a suffix for cache isolation based on the environment (e.g., development, staging) and a fallback cache key for pull requests.

```yaml
jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        environment:
          - development
          - staging
    steps:
      - uses: docker/metadata-action@v3
        id: metadata
        with:
          images: ghcr.io/${{ github.repository }}
          flavor: suffix=-${{ matrix.environment }}
      - uses: int128/docker-build-cache-config-action@v1
        id: cache
        with:
          image: ghcr.io/${{ github.repository }}/cache
          cache-key: ${{ matrix.environment }}
          cache-key-fallback: development
      - uses: docker/build-push-action@v2
        id: build
        with:
          push: true
          tags: ${{ steps.metadata.outputs.tags }}
          labels: ${{ steps.metadata.outputs.labels }}
          cache-from: ${{ steps.cache.outputs.cache-from }}
          cache-to: ${{ steps.cache.outputs.cache-to }}
```

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

### Usage with Pull Request Cache Enabled

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/run.md

Shows how to configure the 'run' function for pull request caching. This example includes specific inputs for flavors and enables pull request cache, potentially generating PR-specific cache tags.

```typescript
const inputs = {
  image: 'ghcr.io/myorg/cache',
  cacheType: 'registry' as const,
  flavor: ['suffix=-cache'],
  pullRequestCache: true,
  cacheKey: [],
  cacheKeyFallback: [],
  extraCacheFrom: '',
  extraCacheTo: 'image-manifest=true',
  bakeTarget: 'my-custom-target',
}

const outputs = await run(inputs, getOctokit(), await getContext())
// Outputs will include PR-specific cache tags
```

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

### Docker Bake Action Bake File Configuration

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/README.md

Example of how to include the generated bake file from the build cache action with the docker/bake-action. This allows for complex build definitions.

```yaml
files:
  - ./docker-bake.hcl
  - ${{ steps.cache.outputs.bake-file }}
```

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

### Generate Docker Flags - Registry Cache Example

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/docker.md

Generates Docker flags for a registry cache with a single source and destination tag. No extra options are provided.

```typescript
const flags = generateDockerFlags({
  cacheType: 'registry',
  cacheFromImageTag: ['ghcr.io/myorg/cache:main'],
  cacheToImageTag: ['ghcr.io/myorg/cache:main'],
  extraCacheFrom: '',
  extraCacheTo: '',
})

// Result:
// {
//   cacheFrom: ['type=registry,ref=ghcr.io/myorg/cache:main'],
//   cacheTo: ['type=registry,ref=ghcr.io/myorg/cache:main,mode=max']
// }
```

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

### Configure Docker Build Cache for Pull Requests

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/README.md

Use this action to generate `cache-from` and `cache-to` inputs for `docker/build-push-action`. This setup is crucial for managing cache effectively in pull request workflows.

```yaml
- uses: int128/docker-build-cache-config-action@v1
  id: cache
  with:
    image: ghcr.io/${{ github.repository }}/cache
- uses: docker/build-push-action@v2
  with:
    cache-from: ${{ steps.cache.outputs.cache-from }}
    cache-to: ${{ steps.cache.outputs.cache-to }}
```

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

### Get GitHub API Client (Octokit)

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/function-reference.md

Creates a pre-configured Octokit instance for interacting with the GitHub API. It includes automatic retry logic for transient failures and uses the GITHUB_TOKEN environment variable.

```typescript
export const getOctokit = (): Octokit => {
  const token = process.env.GITHUB_TOKEN
  if (!token) {
    throw new Error('GITHUB_TOKEN not found')
  }
  return new Octokit({ auth: token, retry: { enabled: true } })
}
```

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

### List Pull Request Commits

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/github.md

Example of listing commits for a pull request using the Octokit client. The retry plugin handles potential request failures automatically.

```typescript
const octokit = getOctoctkit()
const { data: commits } = await octokit.rest.pulls.listCommits({
  owner: 'myorg',
  repo: 'myrepo',
  pull_number: 123,
})
```

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

### Data Flow Diagram

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/architecture.md

Visualizes the data flow through the action's modules, starting from GitHub Actions inputs and progressing through `main.ts`, `run.ts`, and finally to the generated outputs like cache flags and bake files.

```text
GitHub Actions Inputs
         │
         ↓
    main.ts
    ├─ Reads action inputs
    ├─ Gets GitHub context
    └─ Gets Octokit client
         │
         ↓
    run.ts (Orchestrator)
    ├─ Calls inferImageTags()
    ├─ Calls generateDockerFlags()
    ├─ Calls generateBake()
    └─ Returns Outputs
         │
         ├─── cache-from
         ├─── cache-to
         └─── bake-file
```

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

### main()

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/function-reference.md

The entry point for GitHub Action execution. It validates inputs, reads action inputs, retrieves GitHub context, creates an Octokit client, orchestrates the main execution flow via the run() function, sets action outputs, and handles errors.

```APIDOC
## main()

### Description
Entry point for GitHub Action execution. Validates deprecated inputs, reads action inputs, retrieves GitHub context, creates Octokit API client, orchestrates execution via run(), sets action outputs, and handles errors.

### Signature
```typescript
const main = async (): Promise<void>
```

### Location
`src/main.ts:6-33`

### Inputs read
- `image` (required)
- `cache-type`
- `flavor`
- `pull-request-cache`
- `cache-key`
- `cache-key-fallback`
- `extra-cache-from`
- `extra-cache-to`
- `bake-target`

### Outputs set
- `cache-from`
- `cache-to`
- `bake-file`

### Error handling
- Throws on deprecated inputs
- Throws on missing required inputs
- Catches all errors and calls core.setFailed()
```

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

### Configure Action Entry Point

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/main.md

Defines the runtime and main script for the GitHub Action. Ensure this matches your build output.

```yaml
runs:
  using: 'node24'
  main: 'dist/index.js'
```

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

### Get Required Environment Variable

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/github.md

Retrieves a required environment variable by its name. Throws an assertion error if the variable is not found.

```typescript
const getEnv = (name: string): string
```

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

### main.md - Main Orchestration

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/INDEX.md

Documentation for the main entry point function, detailing its role in input reading, validation, output setting, error handling, and GitHub Actions integration.

```APIDOC
## main()

### Description

The `main()` function serves as the entry point for the docker-build-cache-config-action. It orchestrates the overall process, including reading and validating inputs, setting outputs for downstream steps, handling errors, and integrating with the GitHub Actions environment.

### Function Signature

`main()`

### Details

- **Input Reading and Validation**: Parses and validates all inputs provided to the action.
- **Output Setting**: Configures and sets outputs that can be consumed by subsequent actions in the workflow.
- **Error Handling**: Implements robust error handling to manage unexpected issues during execution.
- **GitHub Actions Integration**: Manages the interaction with the GitHub Actions environment, including context and event handling.
```

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

### Usage of cache-from output

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/configuration.md

Demonstrates how to use the `cache-from` output from the `int128/docker-build-cache-config-action` in a subsequent `docker/build-push-action` step.

```yaml
- uses: int128/docker-build-cache-config-action@v1
  id: cache
  with:
    image: ghcr.io/${{ github.repository }}/cache

- uses: docker/build-push-action@v5
  with:
    cache-from: ${{ steps.cache.outputs.cache-from }}
```

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

### Trim Prefix from String

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/function-reference.md

Removes a specified prefix from the beginning of a string if it exists. If the string does not start with the given prefix, it is returned unchanged.

```typescript
const trimPrefix = (s: string, prefix: string): string => {
  // ... implementation details ...
};
```

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

### Generated bake-file content

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/usage-patterns.md

Example of the JSON content generated by the docker-build-cache-config-action for bake-action integration. It specifies cache-from and cache-to configurations for the 'build' target.

```json
{
  "target": {
    "build": {
      "cache-from": [
        "type=registry,ref=ghcr.io/myorg/myapp/cache:main"
      ],
      "cache-to": [
        "type=registry,ref=ghcr.io/myorg/myapp/cache:main,mode=max"
      ]
    }
  }
}
```

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

### Generate Docker Flags - Import Only Example

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/docker.md

Generates Docker flags for importing cache only, with no cache export. Includes an extra option for cache-from.

```typescript
const flags = generateDockerFlags({
  cacheType: 'registry',
  cacheFromImageTag: ['ghcr.io/myorg/cache:main'],
  cacheToImageTag: [],
  extraCacheFrom: 'foo=bar',
  extraCacheTo: 'image-manifest=true',
})

// Result:
// {
//   cacheFrom: ['type=registry,ref=ghcr.io/myorg/cache:main,foo=bar'],
//   cacheTo: []
// }
```

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

### Usage of cache-to output

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/configuration.md

Demonstrates how to use the `cache-to` output from the `int128/docker-build-cache-config-action` in a subsequent `docker/build-push-action` step.

```yaml
- uses: int128/docker-build-cache-config-action@v1
  id: cache
  with:
    image: ghcr.io/${{ github.repository }}/cache

- uses: docker/build-push-action@v5
  with:
    cache-to: ${{ steps.cache.outputs.cache-to }}
```

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

### Project Structure Overview

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/architecture.md

Illustrates the directory layout and primary files within the docker-build-cache-config-action project. Each file serves a specific purpose in the action's execution flow.

```tree
src/
  ├── main.ts          # Entry point (reads inputs, orchestrates execution)
  ├── run.ts           # Main orchestration (ties modules together)
  ├── infer.ts         # Cache tag inference logic
  ├── docker.ts        # Docker flag generation
  ├── github.ts        # GitHub API and context helpers
  └── bake.ts          # Docker Bake file generation
```

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

### Get Repository Owner and Name

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/github.md

Parses the GITHUB_REPOSITORY environment variable to extract the owner and repository name. Assumes the variable is in the 'owner/repo' format.

```typescript
const getRepo = (): { owner: string; repo: string }
```

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

### Get Octokit Client

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/github.md

Creates an Octokit instance with automatic retry logic for GitHub API requests. Uses the GITHUB_TOKEN environment variable.

```typescript
export const getOctokit = (): Octokit
```

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

### Basic Usage in GitHub Actions Workflow

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/run.md

Demonstrates the basic usage of the 'run' function within a GitHub Actions workflow. Ensure necessary imports for Octokit and Context are available.

```typescript
import { run } from './run.js'
import { getOctokit, getContext } from './github.js'

const inputs = {
  image: 'ghcr.io/myorg/cache',
  cacheType: 'registry' as const,
  flavor: [],
  pullRequestCache: false,
  cacheKey: [],
  cacheKeyFallback: [],
  extraCacheFrom: '',
  extraCacheTo: '',
  bakeTarget: 'docker-build-cache-config-action',
}

const outputs = await run(inputs, getOctokit(), await getContext())
console.log('cache-from:', outputs.cacheFrom)
console.log('cache-to:', outputs.cacheTo)
console.log('bake-file:', outputs.bakeFile)
```

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

### Trim String Prefix

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/infer.md

Removes a specified prefix from the beginning of a string, but only if the string actually starts with that prefix. Returns the original string if the prefix is not found.

```typescript
const trimPrefix = (s: string, prefix: string): string
```

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

### Add Multiple Options to Extra Cache To

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/configuration.md

Configure 'cache-to' flags with multiple options like 'image-manifest=true' and 'oci-mediatypes=true' for advanced cache export scenarios.

```yaml
extra-cache-to: "image-manifest=true,oci-mediatypes=true"
```

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

### run.md - Core Orchestration Logic

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/INDEX.md

Details the core orchestration logic within the `run()` function, including its parameters, execution steps, and integration with other Docker actions.

```APIDOC
## run()

### Description

The `run()` function contains the core orchestration logic for the action. It defines the complete execution steps, manages inputs and outputs, and integrates with other Docker actions like `docker/build-push-action` and `docker/bake-action`.

### Function Signature

`run(inputs: Inputs, options: Options)`

### Parameters

- **inputs** (Inputs): An object containing all input parameters for the action.
- **options** (Options): An object containing configuration options for the execution.

### Details

- **Execution Steps**: Outlines the sequence of operations performed by the action.
- **Input/Output Types**: Defines the structure and types of inputs and outputs.
- **Integration**: Specifies how the action interacts with `docker/build-push-action` and `docker/bake-action`.
- **Output Format**: Details the format of the outputs generated by the action.
```

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

### Input to Output Mapping

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/INDEX.md

Shows the transformation of inputs to outputs within the action, and how these outputs are used by other Docker actions. Essential for understanding the action's interface.

```text
Inputs: image, cache-type, flavor, pull-request-cache, ...
  ↓
Outputs: cache-from, cache-to, bake-file
  ↓
Used in downstream steps:
  - docker/build-push-action: cache-from, cache-to
  - docker/bake-action: bake-file
```

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

### Run Unit and Integration Tests

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/architecture.md

Execute all tests for the project using npm test. This command invokes Vitest for running the test suite.

```bash
npm test
# Runs vitest
```

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

### Flavor Suffix for Same Repository Cache

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/configuration.md

Configure caching with a flavor suffix, useful for differentiating cache layers within the same repository. This example uses a suffix for the cache image.

```yaml
- uses: int128/docker-build-cache-config-action@v1
  id: cache
  with:
    image: ghcr.io/${{ github.repository }}
    flavor: suffix=-cache

- uses: docker/build-push-action@v5
  with:
    tags: ghcr.io/${{ github.repository }}:main
    cache-from: ${{ steps.cache.outputs.cache-from }}
    cache-to: ${{ steps.cache.outputs.cache-to }}
```

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

### Basic Workflow with docker/build-push-action

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/usage-patterns.md

Use this pattern to generate cache flags for docker/build-push-action. It imports cache from the main branch and exports it on push to main. On pull requests, it imports cache but does not export.

```yaml
name: Build and Push

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: docker/setup-buildx-action@v3

      - uses: int128/docker-build-cache-config-action@v1
        id: cache
        with:
          image: ghcr.io/${{ github.repository }}/cache

      - uses: docker/build-push-action@v5
        with:
          context: .
          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
          tags: ghcr.io/${{ github.repository }}:latest
          cache-from: ${{ steps.cache.outputs.cache-from }}
          cache-to: ${{ steps.cache.outputs.cache-to }}
```

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

### Add Multiple Options to Extra Cache From

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/configuration.md

Specify multiple comma-separated options for Docker BuildKit 'cache-from' flags, such as 'pull=true' and 'image-manifest=false'.

```yaml
extra-cache-from: "pull=true,image-manifest=false"
```

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

### Access Pull Request Details from Context

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/github.md

Example of accessing pull request specific details from the context payload. Checks if the event payload contains pull request information.

```typescript
const context = await getContext()
if ('pull_request' in context.payload) {
  const pr = context.payload.pull_request
  console.log(pr.base.ref)  // Base branch
  console.log(pr.number)    // PR number
}
```

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

### Import Base Image Cache

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/usage-patterns.md

Add the base image cache import using `extra-cache-from` with the appropriate registry reference.

```yaml
extra-cache-from: "type=registry,ref=..."  # Add base cache import
```

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

### Configure cache-from for Docker Build

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/configuration.md

Provides a newline-separated string for the `cache-from` input of `docker/build-push-action`. Use this to specify registry cache sources.

```shell
type=registry,ref=ghcr.io/myorg/cache:main
```

```shell
type=registry,ref=ghcr.io/myorg/cache:pr-123
type=registry,ref=ghcr.io/myorg/cache:main
```

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

### run()

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/run.md

The main orchestration function that generates cache configuration outputs. It infers cache tags, generates Docker flags, and creates a Docker Bake configuration file.

```APIDOC
## run()

### Description
Main orchestration function that generates cache configuration outputs. It infers cache tags, generates Docker flags, and creates a Docker Bake configuration file.

### Signature
```typescript
export const run = async (
  inputs: Inputs,
  octokit: Octokit,
  context: Context
): Promise<Outputs>
```

### Parameters
#### Parameters
- **inputs** (Inputs) - Required - Action input configuration
- **octokit** (Octokit) - Required - GitHub API client instance
- **context** (Context) - Required - GitHub Actions execution context

### Returns
**Promise<Outputs>** — A promise that resolves to an object containing `cacheFrom`, `cacheTo`, and `bakeFile` fields.

### Behavior
The function performs the following steps:

1. **Infers cache tags** — Calls `inferImageTags()` to determine source and destination image tags based on the event context
2. **Logs inferred tags** — Outputs the inferred cache-from and cache-to tags to the action log
3. **Generates Docker flags** — Calls `generateDockerFlags()` to create properly formatted Docker BuildKit cache flags
4. **Creates Bake file** — Calls `generateBake()` to create a Docker Bake configuration object
5. **Logs Bake configuration** — Outputs the Bake file contents to the action log
6. **Writes Bake file** — Creates a temporary file in the runner's temp directory and writes the Bake configuration as JSON
7. **Returns outputs** — Returns the formatted cache flags and Bake file path

### Examples
**Basic usage in GitHub Actions workflow:**

```typescript
import { run } from './run.js'
import { getOctokit, getContext } from './github.js'

const inputs = {
  image: 'ghcr.io/myorg/cache',
  cacheType: 'registry' as const,
  flavor: [],
  pullRequestCache: false,
  cacheKey: [],
  cacheKeyFallback: [],
  extraCacheFrom: '',
  extraCacheTo: '',
  bakeTarget: 'docker-build-cache-config-action',
}

const outputs = await run(inputs, getOctokit(), await getContext())
console.log('cache-from:', outputs.cacheFrom)
console.log('cache-to:', outputs.cacheTo)
console.log('bake-file:', outputs.bakeFile)
```

**With pull request cache enabled:**

```typescript
const inputs = {
  image: 'ghcr.io/myorg/cache',
  cacheType: 'registry' as const,
  flavor: ['suffix=-cache'],
  pullRequestCache: true,
  cacheKey: [],
  cacheKeyFallback: [],
  extraCacheFrom: '',
  extraCacheTo: 'image-manifest=true',
  bakeTarget: 'my-custom-target',
}

const outputs = await run(inputs, getOctokit(), await getContext())
// Outputs will include PR-specific cache tags
```
```

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

### getOctokit

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/function-reference.md

Creates a pre-configured GitHub API client instance. This client is set up with automatic retry capabilities for transient failures and uses the GITHUB_TOKEN environment variable for authentication.

```APIDOC
## getOctokit()

### Description
Creates a pre-configured GitHub API client instance. This client is set up with automatic retry capabilities for transient failures and uses the GITHUB_TOKEN environment variable for authentication.

### Signature
```typescript
export const getOctokit = (): Octokit
```

### Returns
An Octokit instance with the retry plugin enabled, ready for API calls.
```

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

### Main Function Signature

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/main.md

Defines the asynchronous main function that orchestrates the GitHub Action workflow. It handles input validation, reading inputs, getting GitHub context, creating an API client, executing the main logic, logging outputs, setting outputs, and error handling.

```typescript
const main = async (): Promise<void>
```

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

### Main Orchestration Function

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/MANIFEST.txt

The main entry point for orchestrating the build cache configuration process.

```APIDOC
## run

### Description
Main orchestration function for the docker-build-cache-config-action.

### Method
Not applicable (SDK/Action function)

### Endpoint
Not applicable (SDK/Action function)

### Parameters
(Details would be in function-reference.md or api-reference/run.md)

### Request Example
(Not applicable for SDK/Action function)

### Response
(Details would be in function-reference.md or api-reference/run.md)
```

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

### Enable Debug Logging for Cache Issues

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/usage-patterns.md

To troubleshoot cache import problems, enable debug logging in the `docker/setup-buildx-action` by setting `driver-options: debug=true`.

```yaml
- uses: docker/setup-buildx-action@v3
  with:
    driver-options: debug=true  # Enable debug logging
```

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

### Conditional Cache Export for PRs

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/usage-patterns.md

This example shows how to conditionally export Docker build cache based on whether a pull request is a draft. Draft PRs only import from the main branch and do not export, while ready PRs import from the specific PR branch and main, and export to the PR branch. This ensures that only finalized PRs contribute to the cache.

```yaml
- uses: int128/docker-build-cache-config-action@v1
  id: cache-with-export
  if: github.event.pull_request.draft == false
  with:
    image: ghcr.io/${{ github.repository }}/cache
    pull-request-cache: true

- uses: int128/docker-build-cache-config-action@v1
  id: cache-no-export
  if: github.event.pull_request.draft == true
  with:
    image: ghcr.io/${{ github.repository }}/cache
    pull-request-cache: false

- uses: docker/build-push-action@v5
  with:
    cache-from: ${{ steps.cache-with-export.outputs.cache-from || steps.cache-no-export.outputs.cache-from }}
    cache-to: ${{ steps.cache-with-export.outputs.cache-to || steps.cache-no-export.outputs.cache-to }}
```

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

### Scheduled Cleanup of Old PR Cache Tags

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/usage-patterns.md

This workflow demonstrates how to periodically clean up old PR cache tags. It iterates through container package versions, identifies tags starting with 'pr-', and checks if the corresponding PR still exists. If the PR does not exist, it suggests that the tag could be deleted. Adjust the registry logic for your specific needs.

```yaml
name: Cleanup PR Cache

on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: docker/setup-buildx-action@v3

      - name: Delete old PR tags
        run: |
          # This is example logic; adjust for your registry
          for tag in $(gh api repos/$GITHUB_REPOSITORY/packages/container/cache/versions \
            --jq '.[] | select(.metadata.container.tags[] | select(startswith("pr-"))) | .metadata.container.tags[]'); do
            # Check if PR still exists
            pr_num=$(echo $tag | sed 's/pr-//')
            if ! gh pr view $pr_num 2>/dev/null;
 then
              # PR closed or doesn't exist; could delete tag here
              echo "Could delete: $tag"
            fi
          done
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

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

### Use `flavor` with `prefix=` instead of `tag-prefix`

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/configuration.md

The `tag-prefix` input is deprecated. Use the `flavor` input with the `prefix=` option to achieve the same result.

```yaml
# Old way (no longer works)
tag-prefix: "v1-"

# New way
flavor: prefix=v1-
```

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

### Configure cache-to for Docker Build

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/configuration.md

Provides a newline-separated string for the `cache-to` input of `docker/build-push-action`. Use this to specify registry cache destinations. An empty string indicates no export.

```shell
type=registry,ref=ghcr.io/myorg/cache:main,mode=max
```

```shell
(empty string)
```

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

### bake.md - Docker Bake File Generation

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/INDEX.md

Explains the `generateBake()` function for creating Docker Bake files based on provided configurations.

```APIDOC
## generateBake()

### Description

The `generateBake()` function is used to generate Docker Bake files. It defines the structure for Docker Bake configuration and facilitates its usage with the `docker/bake-action`.

### Function Signature

`generateBake(config: BakeConfig): BakeFileContent`

### Parameters

- **config** (BakeConfig): An object containing the configuration for generating the Bake file.

### Returns

A string representing the content of the generated Docker Bake file.

### Details

- **Bake Type Definition**: Defines the structure of the `Bake` type.
- **Configuration Structure**: Outlines the expected structure for Docker Bake configuration.
- **Usage with docker/bake-action**: Provides guidance on how to use the generated Bake file with `docker/bake-action`.
- **Example Bake Files**: Includes example Bake files and configurations for various scenarios.
```

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

### Import Consumer Functions

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/function-reference.md

Import these functions from './run.js', './infer.js', './docker.js', './bake.js', and './github.js' to use them in your consumer code.

```typescript
import { run } from './run.js'
import { inferImageTags } from './infer.js'
import { generateDockerFlags } from './docker.js'
import { generateBake } from './bake.js'
import { getOctokit, getContext } from './github.js'
```

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

### Integrate with docker/bake-action

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/usage-patterns.md

Use Bake file output with docker/bake-action for more complex build scenarios. This workflow defines metadata, configures build cache, and then uses docker/bake-action to push images.

```yaml
- uses: docker/metadata-action@v5
  id: metadata
  with:
    images: ghcr.io/${{ github.repository }}

- uses: int128/docker-build-cache-config-action@v1
  id: cache
  with:
    image: ghcr.io/${{ github.repository }}/cache
    bake-target: build

- uses: docker/bake-action@v5
  with:
    files: |
      ./docker-bake.hcl
      ${{ steps.cache.outputs.bake-file }}
    push: true
    set: |
      *.tags=${{ steps.metadata.outputs.tags }}
```

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

### Configure Inline Cache Backend

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/README_EXAMPLES.md

Use this configuration to set the cache backend to 'inline'. This is useful for exporting build cache to an external location for future builds.

```yaml
- uses: int128/docker-build-cache-config-action@v1
  id: cache
  with:
    image: ghcr.io/${{ github.repository }}/cache
    cache-type: inline # cache backend storage
```

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

### Enable Image Manifest Support for Extra Cache To

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/configuration.md

Append 'image-manifest=true' to 'cache-to' flags for enhanced cache export, particularly for Amazon ECR cache manifest support.

```yaml
extra-cache-to: "image-manifest=true"
```

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

### Typical Data Flow in GitHub Actions

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/INDEX.md

Illustrates the data flow from GitHub Actions inputs through the main script, orchestration layer, and finally to action outputs. This is useful for understanding how data is processed within the action.

```text
GitHub Actions Inputs
    ↓
main.ts (reads inputs, gets context)
    ↓
run.ts (orchestrates):
  ├─ inferImageTags() → determine tags
  ├─ generateDockerFlags() → format flags
  └─ generateBake() → create file
    ↓
Action outputs: cache-from, cache-to, bake-file
```

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

### Generate Docker Flags from Cache Tags

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/architecture.md

This snippet demonstrates the conversion of inferred cache tags and additional options into Docker build flags. It shows the input cache tags and cache type, and the resulting DockerFlags structure, including cacheFrom and cacheTo configurations.

```text
Cache tags: [
  "ghcr.io/org/cache:pr-123",
  "ghcr.io/org/cache:main"
]
Cache type: "registry"
Extra options: "image-manifest=true"
    ↓
Generate Docker Flags
    ↓
DockerFlags: {
  cacheFrom: [
    "type=registry,ref=ghcr.io/org/cache:pr-123,image-manifest=true",
    "type=registry,ref=ghcr.io/org/cache:main,image-manifest=true"
  ]
  cacheTo: [
    "type=registry,ref=ghcr.io/org/cache:pr-123,mode=max,image-manifest=true"
  ]
}
```

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

### Build Action Script

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/main.md

Command to bundle the TypeScript source code into a single JavaScript file for execution. This includes generating source maps and license information.

```bash
npm run build
# Runs: ncc build --source-map --license licenses.txt src/main.ts
```

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

### Cache Configuration for Main Branch Builds

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/README.md

When building the main branch, import cache from the main tag and export to the main tag. This ensures the main branch always has the latest cache.

```yaml
cache-from: type=registry,ref=REGISTRY/REPOSITORY:main
cache-to: type=registry,ref=REGISTRY/REPOSITORY:main,mode=max
```

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

### Docker Bake Configuration for Actions

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/README.md

This HCL configuration defines targets for `docker-metadata-action` and `docker-build-cache-config-action`, and a default target that inherits from both for use with `docker/bake-action`.

```hcl
# docker-bake.hcl
target "docker-metadata-action" {}

target "docker-build-cache-config-action" {}

target "default" {
  inherits = ["docker-metadata-action", "docker-build-cache-config-action"]
  context = "."
}
```

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

### Generate Basic Cache Configuration

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/bake.md

Creates a Docker Bake configuration for a single target with specified cache import and export references.

```typescript
const bake = generateBake('docker-build-cache-config-action', {
  cacheFrom: ['type=registry,ref=ghcr.io/myorg/cache:main'],
  cacheTo: ['type=registry,ref=ghcr.io/myorg/cache:main,mode=max'],
})

// Result:
// {
//   target: {
//     'docker-build-cache-config-action': {
//       'cache-from': [
//         'type=registry,ref=ghcr.io/myorg/cache:main'
//       ],
//       'cache-to': [
//         'type=registry,ref=ghcr.io/myorg/cache:main,mode=max'
//       ]
//     }
//   }
// }
```

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

### Cache Configuration for Pull Request Builds (With PR Cache)

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/configuration.md

Demonstrates the cache configuration when 'pull-request-cache' is true for a pull request build. Imports from both the PR-specific tag and the base branch are configured, and cache is exported to the PR-specific tag.

```yaml
# Pull request build
cache-from: |
  type=registry,ref=REPO:pr-123
  type=registry,ref=REPO:main
cache-to: type=registry,ref=REPO:pr-123,mode=max
```

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

### github.md - GitHub Integration Utilities

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/INDEX.md

Documents utility functions for interacting with the GitHub API and retrieving GitHub Actions context.

```APIDOC
## GitHub Integration Utilities

### Description

This section details utility functions for seamless integration with GitHub Actions. It includes functions to obtain a pre-configured Octokit client and retrieve the GitHub Actions context, along with definitions for context types and environment variables.

### Functions

#### getOctokit()

- **Description**: Returns a pre-configured Octokit API client with retry logic.
- **Signature**: `getOctokit(): Octokit`

#### getContext()

- **Description**: Retrieves the GitHub Actions context object.
- **Signature**: `getContext(): Context`

### Details

- **Context Type**: Provides a detailed definition of the `Context` type, including all available fields.
- **Environment Variables**: Lists and explains the environment variables used by the action.
- **Helper Functions**: Includes helper functions like `getRepo` and `getEnv` for easier access to repository and environment information.
- **Webhook Events**: Describes supported webhook event types and their payloads.
```

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

### Setting Action Outputs

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/main.md

This snippet demonstrates how to set outputs for a GitHub Action using '@actions/core'. These outputs can be accessed in subsequent workflow steps.

```typescript
core.setOutput('cache-from', outputs.cacheFrom)
core.setOutput('cache-to', outputs.cacheTo)
core.setOutput('bake-file', outputs.bakeFile)
```

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

### Configure AWS Credentials and ECR Login

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/usage-patterns.md

Sets up AWS credentials and logs into Amazon ECR. This is a prerequisite for using ECR-related features.

```yaml
- uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::ACCOUNT:role/ROLE
    aws-region: us-east-1

- uses: aws-actions/amazon-ecr-login@v1
  id: ecr
```

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

### Integrate with docker/bake-action

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/api-reference/run.md

Use this snippet to integrate the docker-build-cache-config-action with docker/bake-action. It configures a cache image and merges the generated bake file with existing bake files.

```yaml
- uses: int128/docker-build-cache-config-action@v1
  id: cache
  with:
    image: ghcr.io/${{ github.repository }}/cache

- uses: docker/bake-action@v5
  with:
    files: |
      ./docker-bake.hcl
      ${{ steps.cache.outputs.bake-file }}
```

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

### Push Event Cache Configuration

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/README.md

Defines the cache-from and cache-to configurations for branch pushes and tag pushes.

```yaml
Branch push:
  cache-from: REPO:branch-name
  cache-to:   REPO:branch-name

Tag push:
  cache-from: REPO:default-branch
  cache-to:   (empty)
```

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

### Cache Configuration for Pull Request Builds (No PR Cache)

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/configuration.md

Illustrates the cache configuration when 'pull-request-cache' is false for a pull request build. Only imports from the base branch are configured.

```yaml
# Pull request build
cache-from: type=registry,ref=REPO:main
cache-to:  # (empty, no export)
```

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

### docker-bake.hcl configuration

Source: https://github.com/int128/docker-build-cache-config-action/blob/main/_autodocs/usage-patterns.md

Defines a 'build' target for the docker/bake-action, specifying the Dockerfile and context. This HCL file is referenced in the workflow to configure the build process.

```hcl
target "build" {
  dockerfile = "Dockerfile"
  context = "."
}
```