# docker/actions-toolkit architecture

> Architecture diagram of the GitHub repository docker/actions-toolkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/docker/actions-toolkit
- Repository: https://github.com/docker/actions-toolkit

## Overview

Actions Toolkit is a reusable library for Docker GitHub Actions, providing shared action utilities and wrappers around Docker build tooling. The principal workflow is an action author using the toolkit to prepare or invoke build tools and interact with GitHub Actions; the repository also covers image handling, signing and verification, and supporting developer utilities. The README documents the product scope, while sampled imports establish only some internal links; unsampled modules are represented without inferred call chains.

Main entry points: [`src/exec.ts`](https://github.com/docker/actions-toolkit/blob/main/src/exec.ts) (Process execution), [`src/buildx/buildx.ts`](https://github.com/docker/actions-toolkit/blob/main/src/buildx/buildx.ts) (Buildx operations), [`src/docker/docker.ts`](https://github.com/docker/actions-toolkit/blob/main/src/docker/docker.ts) (Docker client), [`src/github/github.ts`](https://github.com/docker/actions-toolkit/blob/main/src/github/github.ts) (GitHub integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Toolkit API"]
  node_toolkit["Toolkit facade<br/>[toolkit.ts]"]
  node_exports["Package exports<br/>[index.ts]"]
end

subgraph group_build["Build tooling"]
  node_buildx["Buildx operations<br/>[buildx.ts]"]
  node_bake["Bake orchestration<br/>[bake.ts]"]
  node_buildkitgit["BuildKit Git<br/>[git.ts]"]
  node_buildkittypes["BuildKit protocol types<br/>[client.ts]"]
end

subgraph group_image["Docker and images"]
  node_docker["Docker client<br/>[docker.ts]"]
  node_dockerinstall["Docker setup<br/>[install.ts]"]
  node_compose["Compose setup<br/>[install.ts]"]
  node_imagetools["Image tools<br/>[imagetools.ts]"]
  node_oci["OCI models<br/>[oci.ts]"]
  node_regctl["Registry client<br/>[regctl.ts]"]
  node_undock["Image unpacking<br/>[undock.ts]"]
end

subgraph group_trust["Signing and trust"]
  node_cosigninstall["Cosign setup<br/>[install.ts]"]
  node_cosign["Cosign client<br/>[cosign.ts]"]
  node_sigstore["Sigstore verification<br/>[sigstore.ts]"]
end

subgraph group_support["Action support"]
  node_github["GitHub integration<br/>[github.ts]"]
  node_cache[("Tool and image cache<br/>[cache.ts]")]
  node_context["Temporary workspace<br/>[context.ts]"]
  node_exec["Process execution<br/>[exec.ts]"]
  node_git["Git utilities<br/>[git.ts]"]
  node_utilities["Shared utilities<br/>[util.ts]"]
  node_githubbuilder["Runner and bake helpers"]
end

node_author(("Docker action"))

node_author -->|"uses library"| node_toolkit
node_toolkit -.->|"exposes API"| node_exports
node_buildx -->|"checks availability"| node_docker
node_buildx -->|"uses Git support"| node_buildkitgit
node_buildx -->|"creates annotations"| node_github
node_buildx -->|"runs commands"| node_exec
node_buildx -->|"uses status types"| node_buildkittypes
node_bake -->|"uses Buildx"| node_buildx
node_bake -->|"uses workspace"| node_context
node_bake -->|"runs commands"| node_exec
node_docker -->|"caches images"| node_cache
node_docker -->|"runs commands"| node_exec
node_docker -->|"uses workspace"| node_context
node_dockerinstall -->|"configures daemon"| node_docker
node_dockerinstall -->|"fetches releases"| node_github
node_dockerinstall -->|"reads manifests"| node_regctl
node_dockerinstall -->|"uses unpacker"| node_undock
node_dockerinstall -->|"starts services"| node_exec
node_compose -->|"uses cache"| node_cache
node_compose -->|"uses workspace"| node_context
node_compose -->|"checks Docker"| node_docker
node_compose -->|"fetches releases"| node_github
node_imagetools -->|"uses Buildx"| node_buildx
node_imagetools -->|"uses workspace"| node_context
node_imagetools -->|"runs commands"| node_exec
node_regctl -->|"runs commands"| node_exec
node_undock -->|"runs commands"| node_exec
node_cosigninstall -->|"checks builder"| node_buildx
node_cosigninstall -->|"caches binary"| node_cache
node_cosigninstall -->|"uses Sigstore"| node_sigstore
node_cosign -->|"runs commands"| node_exec
node_sigstore -->|"checks availability"| node_cosign
node_sigstore -->|"uses image tools"| node_imagetools
node_sigstore -->|"runs commands"| node_exec
node_sigstore -->|"uses GitHub APIs"| node_github
node_github -.->|"calls GitHub"| node_author
node_git -->|"runs commands"| node_exec
node_git -->|"uses GitHub"| node_github

click node_toolkit "https://github.com/docker/actions-toolkit/blob/main/src/toolkit.ts"
click node_exports "https://github.com/docker/actions-toolkit/blob/main/src/index.ts"
click node_buildx "https://github.com/docker/actions-toolkit/blob/main/src/buildx/buildx.ts"
click node_bake "https://github.com/docker/actions-toolkit/blob/main/src/buildx/bake.ts"
click node_buildkitgit "https://github.com/docker/actions-toolkit/blob/main/src/buildkit/git.ts"
click node_buildkittypes "https://github.com/docker/actions-toolkit/blob/main/src/types/buildkit/client.ts"
click node_docker "https://github.com/docker/actions-toolkit/blob/main/src/docker/docker.ts"
click node_dockerinstall "https://github.com/docker/actions-toolkit/blob/main/src/docker/install.ts"
click node_compose "https://github.com/docker/actions-toolkit/blob/main/src/compose/install.ts"
click node_imagetools "https://github.com/docker/actions-toolkit/blob/main/src/buildx/imagetools.ts"
click node_oci "https://github.com/docker/actions-toolkit/blob/main/src/oci/oci.ts"
click node_regctl "https://github.com/docker/actions-toolkit/blob/main/src/regclient/regctl.ts"
click node_undock "https://github.com/docker/actions-toolkit/blob/main/src/undock/undock.ts"
click node_cosigninstall "https://github.com/docker/actions-toolkit/blob/main/src/cosign/install.ts"
click node_cosign "https://github.com/docker/actions-toolkit/blob/main/src/cosign/cosign.ts"
click node_sigstore "https://github.com/docker/actions-toolkit/blob/main/src/sigstore/sigstore.ts"
click node_github "https://github.com/docker/actions-toolkit/blob/main/src/github/github.ts"
click node_cache "https://github.com/docker/actions-toolkit/blob/main/src/cache.ts"
click node_context "https://github.com/docker/actions-toolkit/blob/main/src/context.ts"
click node_exec "https://github.com/docker/actions-toolkit/blob/main/src/exec.ts"
click node_git "https://github.com/docker/actions-toolkit/blob/main/src/git.ts"
click node_utilities "https://github.com/docker/actions-toolkit/blob/main/src/util.ts"
click node_githubbuilder "https://github.com/docker/actions-toolkit/tree/main/src/github-builder"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_toolkit,node_exports toneBlue
class node_buildx,node_bake,node_buildkitgit,node_buildkittypes toneAmber
class node_docker,node_dockerinstall,node_compose,node_imagetools,node_oci,node_regctl,node_undock toneMint
class node_cosigninstall,node_cosign,node_sigstore toneRose
class node_github,node_cache,node_context,node_exec,node_git,node_utilities,node_githubbuilder,node_author toneIndigo
```

## Components

### Toolkit API

- [Toolkit facade](https://github.com/docker/actions-toolkit/blob/main/src/toolkit.ts): `src/toolkit.ts`
- [Package exports](https://github.com/docker/actions-toolkit/blob/main/src/index.ts): `src/index.ts`

### Build tooling

- [Buildx operations](https://github.com/docker/actions-toolkit/blob/main/src/buildx/buildx.ts): `src/buildx/buildx.ts`
- [Bake orchestration](https://github.com/docker/actions-toolkit/blob/main/src/buildx/bake.ts): `src/buildx/bake.ts`
- [BuildKit Git](https://github.com/docker/actions-toolkit/blob/main/src/buildkit/git.ts): `src/buildkit/git.ts`
- [BuildKit protocol types](https://github.com/docker/actions-toolkit/blob/main/src/types/buildkit/client.ts): `src/types/buildkit/client.ts`

### Docker and images

- [Docker client](https://github.com/docker/actions-toolkit/blob/main/src/docker/docker.ts): `src/docker/docker.ts`
- [Docker setup](https://github.com/docker/actions-toolkit/blob/main/src/docker/install.ts): `src/docker/install.ts`
- [Compose setup](https://github.com/docker/actions-toolkit/blob/main/src/compose/install.ts): `src/compose/install.ts`
- [Image tools](https://github.com/docker/actions-toolkit/blob/main/src/buildx/imagetools.ts): `src/buildx/imagetools.ts`
- [OCI models](https://github.com/docker/actions-toolkit/blob/main/src/oci/oci.ts): `src/oci/oci.ts`
- [Registry client](https://github.com/docker/actions-toolkit/blob/main/src/regclient/regctl.ts): `src/regclient/regctl.ts`
- [Image unpacking](https://github.com/docker/actions-toolkit/blob/main/src/undock/undock.ts): `src/undock/undock.ts`

### Signing and trust

- [Cosign setup](https://github.com/docker/actions-toolkit/blob/main/src/cosign/install.ts): `src/cosign/install.ts`
- [Cosign client](https://github.com/docker/actions-toolkit/blob/main/src/cosign/cosign.ts): `src/cosign/cosign.ts`
- [Sigstore verification](https://github.com/docker/actions-toolkit/blob/main/src/sigstore/sigstore.ts): `src/sigstore/sigstore.ts`

### Action support

- [GitHub integration](https://github.com/docker/actions-toolkit/blob/main/src/github/github.ts): `src/github/github.ts`
- [Tool and image cache](https://github.com/docker/actions-toolkit/blob/main/src/cache.ts): `src/cache.ts`
- [Temporary workspace](https://github.com/docker/actions-toolkit/blob/main/src/context.ts): `src/context.ts`
- [Process execution](https://github.com/docker/actions-toolkit/blob/main/src/exec.ts): `src/exec.ts`
- [Git utilities](https://github.com/docker/actions-toolkit/blob/main/src/git.ts): `src/git.ts`
- [Shared utilities](https://github.com/docker/actions-toolkit/blob/main/src/util.ts): `src/util.ts`
- [Runner and bake helpers](https://github.com/docker/actions-toolkit/tree/main/src/github-builder): `src/github-builder`

### Other components

- **Docker action**

## Connections

- Docker action → Toolkit facade: uses library
- Toolkit facade → Package exports: exposes API
- Buildx operations → Docker client: checks availability (evidence: `src/buildx/buildx.ts`)
- Buildx operations → BuildKit Git: uses Git support (evidence: `src/buildx/buildx.ts`)
- Buildx operations → GitHub integration: creates annotations (evidence: `src/buildx/buildx.ts`)
- Buildx operations → Process execution: runs commands (evidence: `src/buildx/buildx.ts`)
- Buildx operations → BuildKit protocol types: uses status types (evidence: `src/buildx/buildx.ts`)
- Bake orchestration → Buildx operations: uses Buildx (evidence: `src/buildx/bake.ts`)
- Bake orchestration → Temporary workspace: uses workspace (evidence: `src/buildx/bake.ts`)
- Bake orchestration → Process execution: runs commands (evidence: `src/buildx/bake.ts`)
- Docker client → Tool and image cache: caches images (evidence: `src/docker/docker.ts`)
- Docker client → Process execution: runs commands (evidence: `src/docker/docker.ts`)
- Docker client → Temporary workspace: uses workspace (evidence: `src/docker/docker.ts`)
- Docker setup → Docker client: configures daemon (evidence: `src/docker/install.ts`)
- Docker setup → GitHub integration: fetches releases (evidence: `src/docker/install.ts`)
- Docker setup → Registry client: reads manifests (evidence: `src/docker/install.ts`)
- Docker setup → Image unpacking: uses unpacker (evidence: `src/docker/install.ts`)
- Docker setup → Process execution: starts services (evidence: `src/docker/install.ts`)
- Compose setup → Tool and image cache: uses cache (evidence: `src/compose/install.ts`)
- Compose setup → Temporary workspace: uses workspace (evidence: `src/compose/install.ts`)
- Compose setup → Docker client: checks Docker (evidence: `src/compose/install.ts`)
- Compose setup → GitHub integration: fetches releases (evidence: `src/compose/install.ts`)
- Image tools → Buildx operations: uses Buildx (evidence: `src/buildx/imagetools.ts`)
- Image tools → Temporary workspace: uses workspace (evidence: `src/buildx/imagetools.ts`)
- Image tools → Process execution: runs commands (evidence: `src/buildx/imagetools.ts`)
- Registry client → Process execution: runs commands (evidence: `src/regclient/regctl.ts`)
- Image unpacking → Process execution: runs commands (evidence: `src/undock/undock.ts`)
- Cosign setup → Buildx operations: checks builder (evidence: `src/cosign/install.ts`)
- Cosign setup → Tool and image cache: caches binary (evidence: `src/cosign/install.ts`)
- Cosign setup → Sigstore verification: uses Sigstore (evidence: `src/cosign/install.ts`)
- Cosign client → Process execution: runs commands (evidence: `src/cosign/cosign.ts`)
- Sigstore verification → Cosign client: checks availability (evidence: `src/sigstore/sigstore.ts`)
- Sigstore verification → Image tools: uses image tools (evidence: `src/sigstore/sigstore.ts`)
- Sigstore verification → Process execution: runs commands (evidence: `src/sigstore/sigstore.ts`)
- Sigstore verification → GitHub integration: uses GitHub APIs (evidence: `src/sigstore/sigstore.ts`)
- GitHub integration → Docker action: calls GitHub
- Git utilities → Process execution: runs commands (evidence: `src/git.ts`)
- Git utilities → GitHub integration: uses GitHub (evidence: `src/git.ts`)
