Menu

Caution

Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.

This is documentation for the next version of Agent. For the latest stable release, go to the latest version.

Beta

module.git (deprecated)

Caution

Starting with release v0.40, module.git is deprecated and is replaced by import.git. module.git will be removed in a future release.

BETA: This is a beta component. Beta components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case.

module.git is a module loader component. A module loader is a Grafana Agent Flow component which retrieves a module and runs the components defined inside of it.

module.git retrieves a module source from a file in a Git repository.

Usage

river
module.git "LABEL" {
  repository = "GIT_REPOSTORY"
  path       = "PATH_TO_MODULE"

  arguments {
    MODULE_ARGUMENT_1 = VALUE_1
    MODULE_ARGUMENT_2 = VALUE_2
    ...
  }
}

Arguments

The following arguments are supported:

NameTypeDescriptionDefaultRequired
repositorystringThe Git repository address to retrieve the module from.yes
revisionstringThe Git revision to retrieve the module from."HEAD"no
pathstringThe path in the repository where the module is stored.yes
pull_frequencydurationThe frequency to pull the repository for updates."60s"no

The repository attribute must be set to a repository address that would be recognized by Git with a git clone REPOSITORY_ADDRESS command, such as htts://github.com/grafana/agent.git.

The revision attribute, when provided, must be set to a valid branch, tag, or commit SHA within the repository.

The path attribute must be set to a path which is accessible from the root of the repository, such as FILE_NAME.river or FOLDER_NAME/FILE_NAME.river.

If pull_frequency is not "0s", the Git repository will be pulled for updates at the frequency specified, causing the loaded module to update with the retrieved changes.

Blocks

The following blocks are supported inside the definition of module.git:

HierarchyBlockDescriptionRequired
basic_authbasic_authConfigure basic_auth for authenticating to the repo.no
ssh_keyssh_keyConfigure a SSH Key for authenticating to the repo.no
argumentsargumentsArguments to pass to the module.no

basic_auth block

NameTypeDescriptionDefaultRequired
password_filestringFile containing the basic auth password.no
passwordsecretBasic auth password.no
usernamestringBasic auth username.no

password and password_file are mutually exclusive, and only one can be provided inside a basic_auth block.

ssh_key block

NameTypeDescriptionDefaultRequired
usernamestringSSH username.yes
keysecretSSH private keyno
key_filestringSSH private key path.no
passphrasesecretPassphrase for SSH key if needed.no

arguments block

The arguments block specifies the list of values to pass to the loaded module.

The attributes provided in the arguments block are validated based on the argument blocks defined in the module source:

  • If a module source marks one of its arguments as required, it must be provided as an attribute in the arguments block of the module loader.

  • Attributes in the argument block of the module loader will be rejected if they are not defined in the module source.

Exported fields

The following fields are exported and can be referenced by other components:

NameTypeDescription
exportsmap(any)The exports of the Module loader.

exports exposes the export config block inside a module. It can be accessed from the parent config via module.git.COMPONENT_LABEL.exports.EXPORT_LABEL.

Values in exports correspond to export blocks defined in the module source.

Component health

module.git is reported as healthy if the repository was cloned successfully and most recent load of the module was successful.

Debug information

module.git includes debug information for:

  • The full SHA of the currently checked out revision.
  • The most recent error when trying to fetch the repository, if any.

Debug metrics

module.git does not expose any component-specific debug metrics.

Examples

This example uses a module loaded from a Git repository which adds two numbers:

river
module.git "add" {
  repository = "https://github.com/rfratto/agent-modules.git"
  revision   = "main"
  path       = "add/module.river"

  arguments {
    a = 15
    b = 45
  }
}

The same example as above using basic auth:

river
module.git "add" {
  repository = "https://github.com/rfratto/agent-modules.git"
  revision   = "main"
  path       = "add/module.river"

  basic_auth {
    username = "USERNAME"
    password = "PASSWORD"
  }

  arguments {
    a = 15
    b = 45
  }
}

Using SSH Key from another component:

river
local.file "ssh_key" {
  filename = "PATH/TO/SSH.KEY"
  is_secret = true
}

module.git "add" {
  repository = "github.com:rfratto/agent-modules.git"
  revision   = "main"
  path       = "add/module.river"

  ssh_key {
    username = "git"
    key = local.file.ssh_key.content
  }

  arguments {
    a = 15
    b = 45
  }
}

The same example as above using SSH Key auth:

river
module.git "add" {
  repository = "github.com:rfratto/agent-modules.git"
  revision   = "main"
  path       = "add/module.river"

  ssh_key {
    username = "git"
    key_file = "PATH/TO/SSH.KEY"
  }

  arguments {
    a = 15
    b = 45
  }
}