# chainctl images repos build edit

URL: https://chainguard-docs-preview-git-1016-404s.chainguard.app/platform/chainctl/chainctl-docs/chainctl_images_repos_build_edit.md
Last Modified: October 15, 2026
Tags: chainctl, Reference, Product

## chainctl images repos build edit

Edit a build config, optionally creating a new repo with --save-as

### Synopsis


Extend a Chainguard image with custom packages, environment variables,
certificates, and runtime APK repositories.

You can use Custom Assembly to customize any image you are entitled to by
adding packages from Chainguard's repository, setting environment variables,
adding OCI annotations or customizing user accounts and groups.

Furthermore, Custom Assembly allows you to include any additional custom
certificates in the image. They will be merged with the default certificate
bundle, enabling the image to trust non-standard certificate authorities and
connect to services secured with custom TLS certificates.

You can also configure custom runtime APK repositories using --with-runtime-repositories.
When set, these replace the default virtualapk.cgr.dev repositories in
/etc/apk/repositories, allowing runtime package installation from your own
APK mirrors.

Finally, you can create variants by choosing to save the customized
configuration as a new repository instead of modifying the existing one.

How it works:

You customize the image by editing a YAML configuration manifest. The command
opens your editor with the current repository configuration (or a template for
new repositories). To skip the interactive editor, use the --file flag to
provide a pre-written configuration file.

After editing, the command displays a diff of your changes for review. Upon
confirmation, it updates the repository configuration and starts a custom build
automatically.


Customizable sections:

  contents.packages
    Add additional packages to install in the image (e.g., development tools,
    utilities). Packages must be available in Chainguard's package repository.
    Package names may include the {{major}} and {{minor}} template tokens,
    which expand to the corresponding components of the base image's main
    package version at build time. For example, "py{{major}}.{{minor}}-cryptography"
    becomes "py3.13-cryptography" on an image whose main package is
    python-3.13, and tracks the base image as its version moves.

  contents.runtime_repositories
    Add APK repositories to /etc/apk/repositories in the image for runtime
    package installation. When set, these replace the default virtualapk.cgr.dev
    repositories. Must be HTTPS URLs.

  contents.runtime_keyring
    Trust additional APK signing public keys for the runtime repositories
    (e.g., a re-signing mirror). Each entry has a name and a PEM PUBLIC KEY
    content; the key is written to /etc/apk/keys under its name, which must
    match the filename referenced by the repository's APKINDEX signature
    (.SIGN.RSA256.<name>). Keys can also be loaded from files using the
    --with-runtime-keys flag.

  environment
    Set environment variables that will be available in the image. Variables
    with the 'CHAINGUARD_' or 'GUARDED_' prefix are reserved and cannot be
    used.

  annotations
    Add custom OCI annotations to the image for tracking build information,
    compliance, or metadata. Keys with the 'dev.chainguard' prefix are reserved
    and cannot be used.

  accounts
    Customize image users and groups. You can define custom users with specific
    UIDs/GIDs, home directories, and group memberships. You can also specify
    which user the image should run as.

  certificates
    Provide custom certificates that will be merged with the default certificate
    bundle in the image. This is useful for adding internal CA certificates.
    Certificates can be defined in the YAML manifest or loaded from files using
    the --with-certificates flag (can be specified multiple times). Both methods
    can be combined and all certificates are merged together.
    NOTE: This is a Beta feature that requires enrollment. Contact your Customer
    Success Team to enable this feature.

  guarded_entrypoint
    Set to true to wrap the image entrypoint with /usr/bin/guarded-entrypoint
    when the image is rebuilt. At container start the wrapper replaces each
    environment value written as a secret reference (cg+BACKEND://REF, for
    example cg+gsm://projects/acme/secrets/db/versions/latest) with the
    secret, runs any preflight checks, and then starts the app.
    preflight, fail_mode, and command_override require guarded_entrypoint:
    true in the same manifest.
    NOTE: Guarded Entrypoint, including preflight, fail_mode, and
    command_override, is a Beta feature. Contact Chainguard customer support
    to get access.

  preflight
    Readiness checks the wrapper runs before starting the app, up to 32. Each
    entry sets exactly one of tcp (a host:port to dial) or path (a file that
    must exist), and optionally timeout (default 30s), interval (default
    500ms), and on_failure: fail (the default; the container does not start)
    or continue (the failure is logged). tcp and path expand ${VAR} from the
    resolved environment and cannot contain ',' or '='.

  fail_mode
    What the wrapper does when a secret reference cannot be resolved: closed
    (the default) stops the container; open logs the failure and starts the
    app anyway.

  command_override
    What the wrapper starts after preparing the environment. In default mode
    it runs command only when it receives no arguments at all (the image has
    no ENTRYPOINT or CMD and none are passed at run time), and otherwise runs
    the arguments it received; prepend runs command followed by those
    arguments; override runs command and drops them. prepend and override
    require a command. Each command entry expands ${VAR} from the resolved
    environment; an unset ${VAR} stops the container instead of expanding
    to empty. Write $$ for a literal $, for example $${PORT:-8080} to leave
    ${PORT:-8080} for a shell. The command is stored in the image config,
    which anyone who can pull the image can read, so never write a secret
    into it; set it in environment as a cg+BACKEND://REF reference. An
    expanded ${VAR} is visible in the process's command line, so prefer an
    app that reads the secret from its environment.

Notice: Customer shall not provide Chainguard any personal data (or similarly regulated data)
as part of the Custom Assembly tool, other than the personal data that Chainguard collects in
the ordinary course of business, as further detailed in its
[Privacy Notice](https://www.chainguard.dev/legal/privacy-notice).

```
chainctl images repos build edit [flags]
```

### Examples

```

# Edit a repository interactively (prompts for repo selection)
chainctl images repos build edit

# Edit a specific repository
chainctl images repos build edit --repo=my-custom-python

# Edit and save as a new repository
chainctl images repos build edit --repo=my-custom-python --save-as=my-new-python

# Apply configuration from a file
chainctl images repos build edit --repo=my-custom-python --file=config.yaml

# Apply configuration from a file and save as new repository
chainctl images repos build edit --file=config.yaml --save-as=my-new-python

# Add custom certificates (interactive mode)
chainctl images repos build edit --repo=my-custom-python --with-certificates=ca1.pem --with-certificates=ca2.pem

# Add a customer APK signing key for a re-signing mirror (the file's basename
# must match the key name the mirror's APKINDEX signature references)
chainctl images repos build edit --repo=my-custom-python --with-runtime-keys=key-ee8fa0a3.rsa.pub

# Keys can also be set in a --file manifest; the name must match the filename
# referenced by the mirror's APKINDEX signature (.SIGN.RSA256.<name>):
#
#   contents:
#     runtime_keyring:
#       - name: key-ee8fa0a3.rsa.pub
#         content: |
#           -----BEGIN PUBLIC KEY-----
#           ...
#           -----END PUBLIC KEY-----

# Combine file-based config with certificates
chainctl images repos build edit --file=config.yaml --with-certificates=internal-ca.pem

# Wrap the entrypoint with guarded-entrypoint from a --file manifest.
# At start the wrapper resolves DB_PASSWORD from Secret Manager, waits
# for the cache, and runs the command. The wrapper expands ${CACHE_HOST};
# $${PORT:-8080} reaches the shell as ${PORT:-8080}. The sh -c form needs
# an image with a shell; in a shell-less image, list the program directly,
# as in [python, /app/main.py].
#
#   guarded_entrypoint: true
#   environment:
#     DB_PASSWORD: cg+gsm://projects/acme/secrets/db/versions/latest
#     CACHE_HOST: redis
#   fail_mode: closed
#   preflight:
#     - tcp: ${CACHE_HOST}:6379
#       timeout: 60s
#   command_override:
#     mode: override
#     command:
#       - sh
#       - -c
#       - exec my-app --cache ${CACHE_HOST} --port $${PORT:-8080}
chainctl images repos build edit --repo=my-custom-app --file=config.yaml

```

### Options

```
  -f, --file string                         The name of the file containing the build config.
      --parent string                       The name or id of the parent location to apply build config. Defaults to the default.group config value (env: CHAINGUARD_DEFAULT_GROUP).
      --repo string                         The name or id of the repo to apply build config.
      --save-as string                      Create a new repo with the edited configuration instead of updating the existing one.
      --with-certificates strings           Comma separated list of files to read the custom certificates from.
      --with-runtime-keys strings           Comma separated list of files to read customer APK signing public keys from. Each file becomes a key in /etc/apk/keys named after the file's basename, which must match the filename referenced by the repository's APKINDEX signature (.SIGN.RSA256.<name>).
      --with-runtime-repositories strings   Comma separated list of runtime APK repository URLs to write to /etc/apk/repositories in the image.
```

### Options inherited from parent commands

```
      --api string         The url of the Chainguard platform API. (default "https://console-api.enforce.dev")
      --audience string    The Chainguard token audience to request. (default "https://console-api.enforce.dev")
      --config string      A specific chainctl config file. Uses CHAINCTL_CONFIG environment variable if a file is not passed explicitly.
      --console string     The url of the Chainguard platform Console. (default "https://console.chainguard.dev")
      --force-color        Force color output even when stdout is not a TTY.
  -h, --help               Help for chainctl
      --issuer string      The url of the Chainguard STS endpoint. (default "https://issuer.enforce.dev")
      --log-level string   Set the log level (debug, info) (default "ERROR")
  -o, --output string      Output format. One of: [csv, env, go-template, id, json, markdown, none, table, terse, tree, wide]
  -v, --v int              Set the log verbosity level.
```

### SEE ALSO

* [chainctl images repos build](/platform/chainctl/chainctl-docs/chainctl_images_repos_build/)	 - Manage custom image builds