assembler.yml

The assembler.yml file defines the global documentation site:

  • environments.
  • shared_configuration.
  • narrative repository configuration.
  • reference repository configurations.

This section defines different build environments for the documentation site.

Each environment specifies configuration details such as the site URI, content source, path prefix, Google Tag Manager settings, and feature flags.

Example:

environments:
  prod:
    uri: https://www.elastic.co
    path_prefix: docs
    content_source: current
    allow_indexing: true
    google_tag_manager:
      enabled: true
      id: GTM-KNJMG2M

This section defines YAML anchors for common settings shared among multiple repositories and deployment environments.

The following example sets a unique stack version for each of the three defined deployment environments:

stack: &stack
  current:  9.0
  next: 9.1
  edge: main

Configures the main docs-content repository.

Example:

narrative:
  checkout_strategy: full

Configures all other repositories whose docs content should be included or referenced in the build. Each can have custom settings for branch, checkout method, etc.

Example:

references:
  apm-server:

How you add a reference repository depends on its branching strategy.

To add a continuous deployment repository, define the name of the repository:

references:
  my-repository:

The above configuration is equivalent to specifying.

references:
  my-repository:
    next: main
    current: main

To add a tagged repository, configure the repo to have a fixed git reference (typically a branch) deploy the current content source to production.

references:
  my-other-repository:
    next: main
    current: 9.0

The following settings can be specified on any entry under narrative or references:

Key Type Default Description
current string main Git ref (branch, tag, or commit) used for the current content source.
next string main Git ref used for the next content source.
edge string main Git ref used for the edge content source.
checkout_strategy full | partial partial full clones the entire repository; partial uses a sparse checkout of docs/ only.
sparse_paths list of strings ["docs"] Directories to include when checkout_strategy: partial.
skip bool false Exclude this repository from the build.
private bool false Mark repository as private; excluded from public builds when --skip-private is set.
path string — Override the local filesystem path to use instead of cloning. Respected locally only (ignored in CI).
clone_timeout duration 10m in CI Per-attempt timeout for network git operations (fetch, pull) in CI. Accepts a positive integer followed by s (seconds) or m (minutes), e.g. 30s or 15m. Unbounded when not in CI. When omitted, the global default of 10 minutes applies. 
narrative:
  checkout_strategy: full
  clone_timeout: 15m

references:
  my-fast-repo:
    clone_timeout: 30s
  1. large repo — give each fetch attempt extra headroom
  2. small repo — fail quickly and retry