# containers/buildah architecture

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

- Interactive diagram: https://gitdiagram.com/containers/buildah
- Repository: https://github.com/containers/buildah

## Overview

Buildah is a CLI and Go API for constructing OCI or Docker-format images, primarily by creating a working container, applying build instructions or direct edits, then committing the result. The README documents this user workflow and additional image/container operations; sampled source shows CLI initialization, build-stage execution, file-copy support, and container mount handling. Several command implementations and integrations were not sampled, so documented capabilities are included but uncertain implementation links are omitted or marked unverified.

Main entry points: [`cmd/buildah/main.go`](https://github.com/containers/buildah/blob/main/cmd/buildah/main.go) (Buildah CLI), [`cmd/buildah/run.go`](https://github.com/containers/buildah/blob/main/cmd/buildah/run.go) (Run command), [`cmd/buildah/pull.go`](https://github.com/containers/buildah/blob/main/cmd/buildah/pull.go) (Pull image), [`cmd/buildah/build.go`](https://github.com/containers/buildah/blob/main/cmd/buildah/build.go) (Build command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command interface"]
  node_cli["Buildah CLI<br/>[main.go]"]
  node_input["Flag parsing<br/>[parse.go]"]
  node_buildcmd["Build command<br/>[build.go]"]
end

subgraph group_build["Image construction"]
  node_buildapi["Build API<br/>[build.go]"]
  node_stage["Build stages<br/>[stage_executor.go]"]
  node_copy["File transfer<br/>[copier.go]"]
  node_mkcw["Confidential workloads<br/>[archive.go]"]
end

subgraph group_container["Working containers"]
  node_from["Create container<br/>[from.go]"]
  node_addcopy["Add and copy<br/>[addcopy.go]"]
  node_run["Run command<br/>[run.go]"]
  node_chroot["Isolated execution<br/>[run_linux.go]"]
  node_mount["Volume mounts<br/>[volumes.go]"]
  node_config["Image configuration<br/>[config.go]"]
end

subgraph group_image["Image operations"]
  node_commit["Commit container<br/>[commit.go]"]
  node_pull["Pull image<br/>[pull.go]"]
  node_push["Push image<br/>[push.go]"]
  node_management["Image and container management<br/>[images.go]"]
end

node_user(("Buildah user"))
node_store[("Local image storage")]
node_registry(("Image registry"))

node_user -->|"invokes"| node_cli
node_cli -->|"uses parsing"| node_input
node_cli -.->|"dispatches commands"| node_buildcmd
node_buildcmd -.->|"configures build"| node_buildapi
node_buildapi -.->|"builds stages"| node_stage
node_stage -->|"copies files"| node_copy
node_user -->|"creates working container"| node_from
node_user -->|"adds content"| node_addcopy
node_user -->|"runs instruction"| node_run
node_run -.->|"executes isolated"| node_chroot
node_run -.->|"applies mounts"| node_mount
node_user -->|"sets image config"| node_config
node_user -->|"commits container"| node_commit
node_user -->|"requests image"| node_pull
node_pull -->|"pulls from"| node_registry
node_pull -.->|"stores image"| node_store
node_user -->|"publishes image"| node_push
node_push -->|"pushes to"| node_registry
node_user -->|"manages local objects"| node_management
node_commit -.->|"writes image"| node_store
node_management -.->|"manages stored images"| node_store
node_user -.->|"creates confidential workload"| node_mkcw

click node_cli "https://github.com/containers/buildah/blob/main/cmd/buildah/main.go"
click node_input "https://github.com/containers/buildah/blob/main/pkg/parse/parse.go"
click node_buildcmd "https://github.com/containers/buildah/blob/main/cmd/buildah/build.go"
click node_buildapi "https://github.com/containers/buildah/blob/main/define/build.go"
click node_stage "https://github.com/containers/buildah/blob/main/imagebuildah/stage_executor.go"
click node_copy "https://github.com/containers/buildah/blob/main/copier/copier.go"
click node_mkcw "https://github.com/containers/buildah/blob/main/internal/mkcw/archive.go"
click node_from "https://github.com/containers/buildah/blob/main/cmd/buildah/from.go"
click node_addcopy "https://github.com/containers/buildah/blob/main/cmd/buildah/addcopy.go"
click node_run "https://github.com/containers/buildah/blob/main/cmd/buildah/run.go"
click node_chroot "https://github.com/containers/buildah/blob/main/chroot/run_linux.go"
click node_mount "https://github.com/containers/buildah/blob/main/internal/volumes/volumes.go"
click node_config "https://github.com/containers/buildah/blob/main/cmd/buildah/config.go"
click node_commit "https://github.com/containers/buildah/blob/main/cmd/buildah/commit.go"
click node_pull "https://github.com/containers/buildah/blob/main/cmd/buildah/pull.go"
click node_push "https://github.com/containers/buildah/blob/main/cmd/buildah/push.go"
click node_management "https://github.com/containers/buildah/blob/main/cmd/buildah/images.go"

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_cli,node_input,node_buildcmd,node_user toneBlue
class node_buildapi,node_stage,node_copy,node_mkcw,node_store toneAmber
class node_from,node_addcopy,node_run,node_chroot,node_mount,node_config toneMint
class node_commit,node_pull,node_push,node_management toneRose
class node_registry toneIndigo
```

## Components

### Command interface

- [Buildah CLI](https://github.com/containers/buildah/blob/main/cmd/buildah/main.go): `cmd/buildah/main.go`
- [Flag parsing](https://github.com/containers/buildah/blob/main/pkg/parse/parse.go): `pkg/parse/parse.go`
- [Build command](https://github.com/containers/buildah/blob/main/cmd/buildah/build.go): `cmd/buildah/build.go`

### Image construction

- [Build API](https://github.com/containers/buildah/blob/main/define/build.go): `define/build.go`
- [Build stages](https://github.com/containers/buildah/blob/main/imagebuildah/stage_executor.go): `imagebuildah/stage_executor.go`
- [File transfer](https://github.com/containers/buildah/blob/main/copier/copier.go): `copier/copier.go`
- [Confidential workloads](https://github.com/containers/buildah/blob/main/internal/mkcw/archive.go): `internal/mkcw/archive.go`

### Working containers

- [Create container](https://github.com/containers/buildah/blob/main/cmd/buildah/from.go): `cmd/buildah/from.go`
- [Add and copy](https://github.com/containers/buildah/blob/main/cmd/buildah/addcopy.go): `cmd/buildah/addcopy.go`
- [Run command](https://github.com/containers/buildah/blob/main/cmd/buildah/run.go): `cmd/buildah/run.go`
- [Isolated execution](https://github.com/containers/buildah/blob/main/chroot/run_linux.go): `chroot/run_linux.go`
- [Volume mounts](https://github.com/containers/buildah/blob/main/internal/volumes/volumes.go): `internal/volumes/volumes.go`
- [Image configuration](https://github.com/containers/buildah/blob/main/cmd/buildah/config.go): `cmd/buildah/config.go`

### Image operations

- [Commit container](https://github.com/containers/buildah/blob/main/cmd/buildah/commit.go): `cmd/buildah/commit.go`
- [Pull image](https://github.com/containers/buildah/blob/main/cmd/buildah/pull.go): `cmd/buildah/pull.go`
- [Push image](https://github.com/containers/buildah/blob/main/cmd/buildah/push.go): `cmd/buildah/push.go`
- [Image and container management](https://github.com/containers/buildah/blob/main/cmd/buildah/images.go): `cmd/buildah/images.go`

### Other components

- **Buildah user**
- **Local image storage**
- **Image registry**

## Connections

- Buildah user → Buildah CLI: invokes
- Buildah CLI → Flag parsing: uses parsing (evidence: `cmd/buildah/main.go`)
- Buildah CLI → Build command: dispatches commands
- Build command → Build API: configures build
- Build API → Build stages: builds stages
- Build stages → File transfer: copies files (evidence: `imagebuildah/stage_executor.go`)
- Buildah user → Create container: creates working container
- Buildah user → Add and copy: adds content
- Buildah user → Run command: runs instruction
- Run command → Isolated execution: executes isolated
- Run command → Volume mounts: applies mounts
- Buildah user → Image configuration: sets image config
- Buildah user → Commit container: commits container
- Buildah user → Pull image: requests image
- Pull image → Image registry: pulls from
- Pull image → Local image storage: stores image
- Buildah user → Push image: publishes image
- Push image → Image registry: pushes to
- Buildah user → Image and container management: manages local objects
- Commit container → Local image storage: writes image
- Image and container management → Local image storage: manages stored images
- Buildah user → Confidential workloads: creates confidential workload