apko YAML Reference

A reference guide for writing YAML for apko

Apko files are a YAML based declarative definition of an image to be built by apko. Unlike Dockerfiles, there is no support for running arbitrary Unix commands (i.e. there is no equivalent of RUN statements). This means apko can guarantee the contents and reproducibility of the final image, as well as produce extra metadata such as SBOMs.

This page provides a reference for apko’s YAML specification.


This section defines sources and packages you want to include in your image.

repositoriesDefines a list of repositories to look in for packages. These can be either URLs or file paths. File paths should start with a label like @local e.g: @local /github/workspace/packages.
packagesA list containing all packages that should be installed as part of a given image’s requirements.
keyringPGP keys to add to the keyring for verifying packages.


    - https://packages.wolfi.dev/os/wolfi-signing.rsa.pub
    - https://packages.wolfi.dev/os
    - wolfi-base
    - nginx


This section defines the default commands and/or services to be executed by the container at runtime.

typeWhen this is set to service-bundle, the s6 supervisor will be used to start commands listed in services.
commandSpecifies a command to run when the container starts. Note that this sets the image entrypoint, not the cmd top level element. Only valid when type is not service-bundle.
shell-fragmentBehaves like command, except that the command is a shell fragment. Only valid when type is not service-bundle.
servicesMaps service names to commands that should be started by the s6 supervisor when the container starts. This option is only valid when type is set to service-bundle.

Services are monitored with the s6 supervisor.


Example 1: Command entrypoint

  command: /usr/bin/php81

Example 2: Service entrypoint

  type: service-bundle
    php-fpm: /usr/sbin/php-fpm


Defines a command to run when the container starts up. If entrypoint.command is not set, it will be executed with /bin/sh -c. If entrypoint.command is set, cmd will be passed as arguments to entrypoint.command. This sets the “cmd” value on OCI images.


cmd: help


Configures the shutdown signal sent to the main process in the container by the runtime. By default, this is SIGTERM. Be mindful when using this alongside a service-bundle entrypoint, which will intercept and potentially reinterpret the signal.


stop-signal: SIGQUIT


Sets the working directory for the image. Commands defined within the image entrypoint are taken as relative to this path. Equivalent to WORKDIR in Dockerfile syntax.


work-dir: /app


The architectures to build. This top-level directive expects a list with all architectures that should be a target for the build. By default, apko will try to build for all architectures that are currently supported.


  - x86_64


This section defines environment variables that will be set for this image.


  PATH: /usr/sbin:/sbin:/usr/bin:/bin
  myVAR: "test"


This section defines users and groups that should be added to this image.

groupsA list with the groups that should be present in this image.
usersA list with the user accounts that should be present in this image.
run-asThe default user to run the entrypoint command.


    - username: php
      uid: 65532
      gid: 65532
    - username: laravel
      uid: 1000
      gid: 1000
  run-as: 65532


Defines filesystem operations that can be applied to the image. This includes setting permissions on files or directories as well as creating empty files, directories, and links.

pathFilesystem path to handle.
typeThe type of file operation to perform. This can be one of the following:
- directory: create an empty directory at the path
- empty-file: create an empty file at the path
- hardlink: create a hardlink (ln) at the path, linking to the value specified in source
- symlink: create a symbolic link (ln -s) at the path, linking to the value specified in source
- permissions: sets file permissions on the file or directory at the path.
run-asThe default user to run the entrypoint command.
uidUID to associate with the file
gidGID to associate with the file
permissionsFile permissions to set. Permissions should be specified in octal e.g. 0o755 (see man chmod for details).
sourceUsed in hardlink and symlink, this represents the path to link to.


  - path: /app
    type: directory
    permissions: 0o777
    uid: 65532
    gid: 65532


Defines a path to a configuration file which should be used as the base config. By default, there is no base config used.

The path can be either a local file, or a file in a remote git repository, in the same style as Go package names and GitHub Actions.


include: github.com/chainguard-dev/apko/examples/alpine-base.yaml@main

This would reference the file examples/alpine-base.yaml in the main branch of the apko git repository.

At present, the path structure assumes that the git repository lives on a site similar to GitHub, GitLab, or Gitea. In other words, given an include path like the above, it will parse as:

host: github.com
repository: chainguard-dev/apko
path: examples/alpine-base.yaml
reference: main


annotations defines the set of annotations that should be applied to images and indexes.


  image-author: Chainguard
  image-source: http://gihub.com/chainguard-images/images

Last updated: 2024-05-02 11:07