Agent Metadata Action

This repository hosts two standalone GitHub Actions used by New Relic agent repos:

• send-metadata - reads agent configuration metadata from the calling repository and sends it to New Relic. There are 2 scenarios to use this action:
  1. An agent release - This action parses the configurationDefinitions.yml file (under .fleetControl or .nrcontrol, see Configuration File Format) and makes the configuration data, metadata, and binaries available in New Relic.
  2. A docs update for an agent release - This action parses the frontmatter of the docs mdx files and makes the metadata available in New Relic.
• promote-release-channel - promotes an already-published version onto a release channel. See Promoting a Version to a Release Channel.

Deprecated: the action at the repository root (newrelic/agent-metadata-action@v1, no path) is deprecated in favor of newrelic/agent-metadata-action/send-metadata@v1 - identical inputs and behavior, just a clearer path now that this repo hosts multiple actions. The root action logs a warning on every run and will be removed in a future release.

Installation

Add this action to your workflow:

- name: Read agent metadata
  uses: newrelic/agent-metadata-action/send-metadata@v1

Usage

Prerequisites

This action requires OAuth credentials to authenticate with New Relic services. You must configure the following secrets in your repository:

• OAUTH_CLIENT_ID - Your OAuth client ID for system identity authentication
• OAUTH_CLIENT_SECRET - Your OAuth client secret for system identity authentication (base64 encoded)

These must be passed as action inputs using the with: parameter in your workflow.

Example Workflow For Releasing a New Agent Version

This action automatically checks out your repository at the specified version tag, then reads the configuration definitions file and other associated files from your control directory and saves the agent information in New Relic. By default it looks for .fleetControl, falling back to .nrcontrol if that doesn't exist; set config-directory to use a different directory name instead (this disables the automatic fallback).

name: Process Agent Metadata
on:
  release:
    types:
      - published

jobs:
  read-metadata:
    runs-on: ubuntu-latest
    steps:
      - name: Read agent metadata
        uses: newrelic/agent-metadata-action/send-metadata@v1
        with:
          newrelic-client-id: ${{ secrets.OAUTH_CLIENT_ID }}
          newrelic-private-key: ${{ secrets.OAUTH_CLIENT_SECRET }}
          agent-type: NRDotNetAgent # Required for agent release workflow: The type of agent (e.g., NRJavaAgent, NRNodeAgent)
          version: v1.0.0 # Required for agent release workflow: must match exact git tag name for checkout
          git-ref: v1.0.0 # Optional: git reference to checkout (use if tag differs from version)
          cache: true  # Optional: Enable Go build cache (default: true)
          oci-registry: docker.io/newrelic/agents  # Optional: OCI registry URL for binary uploads
          oci-username: ${{ github.actor }}  # Optional: OCI registry username
          oci-password: ${{ secrets.GITHUB_TOKEN }}  # Optional: OCI registry password/token
          binaries: |  # Optional: JSON array with artifact definitions for binary upload
            [
              {"name": "dotnet-agent", "path": "./dotnet-agent_amd64.tar.gz", "os": "linux", "arch": "amd64", "format": "tar+gzip"},
              {"name": "dotnet-agent", "path": "./dotnet-agent_arm64.tar.gz", "os": "linux", "arch": "arm64", "format": "tar+gzip"},
              {"name": "dotnet-agent", "path": "./NewRelicDotNetAgent.zip", "os": "windows", "arch": "amd64", "format": "zip"}
            ]

Example Workflow For Updating Docs Metadata for a new/existing Agent Version

This action should be triggered on a push to the main docs branch. It will automatically detect the changed release notes in the push and save the agent metadata in New Relic.

name: Process Agent Metadata
on:
  push:
    branches: [main]

jobs:
  read-metadata:
    runs-on: ubuntu-latest
    steps:
      - name: Read agent metadata
        uses: newrelic/agent-metadata-action/send-metadata@v1
        with:
          newrelic-client-id: ${{ secrets.OAUTH_CLIENT_ID }}
          newrelic-private-key: ${{ secrets.OAUTH_CLIENT_SECRET }}
          cache: true  # Optional: Enable Go build cache (default: true)

Configuration File Format (Agent Scenario)

For the agent scenario, the action expects to find two YAML files in your control directory: configurationDefinitions.yml and agentControlDefinitions.yml (an optional agentDefinition.yml is also supported, see below).

The control directory defaults to .fleetControl, falling back to .nrcontrol if that doesn't exist. Set the config-directory input to use a different directory name instead (this disables the automatic fallback). Each of the three filenames above also accepts a kebab-case variant - configuration-definitions.yml, agent-control-definitions.yml, and agent-definition.yml respectively - with the camelCase name taking precedence if both exist in the same directory.

The files have the following structures:

configurationDefinitions:
  - platform: KUBERNETESCLUSTER  # or "HOST" 
    description: Description of the configuration
    type: agent-config
    version: 1.0.0 -- config schema version
    format: yml   -- format of the agent config file
    schema: ./schemas/config-schema.json

agentControlDefinitions:
  - platform: KUBERNETES
    supportFromAgent: 1.0.0
    supportFromAgentControl: 1.0.0
    content: ./agentControl/agent-schema-for-agent-control.yml

**Dec 2025 - schema temporarily optional until full functionality is ready

**Paths must be relative to the resolved control directory and cannot use directory traversal (..) for security.

Artifact Upload

The agent release workflow supports uploading agent binaries to an OCI registry. This feature is optional and only applies to agent releases (when both agent-type and version are provided).

To enable binary uploads, provide the following inputs:

• oci-registry: OCI registry URL (e.g., ghcr.io/newrelic/agents)
• oci-username: Registry username for authentication
• oci-password: Registry password or token for authentication
• binaries: JSON array defining the binaries to upload

Binaries JSON Format:

Each entry in the binaries array must include:

• name: Binary artifact name
• path: Path to the binary file (relative to repository root)
• os: Operating system (e.g., linux, darwin, windows)
• arch: Architecture (e.g., amd64, arm64)
• format: Archive format - supported values: tar, tar+gzip, zip

## Promoting a Version to a Release Channel

A separate action, `newrelic/agent-metadata-action/promote-release-channel`, promotes an
already-published agent version onto a release channel (currently only `REGULAR` is
defined). It's intentionally separate from the main action: it doesn't check out your
repository or touch `.fleetControl` - it's a one-shot call to instrumentation-metadata,
typically triggered manually.

Add a `workflow_dispatch` workflow like this to your repository (`agent-type` is fixed
per repo, same as the release workflow above):

```yaml
name: Promote Release Channel

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Agent version to promote (e.g. 1.2.3) - must already be published to instrumentation-metadata'
        required: true
      channel:
        description: 'Release channel to promote to'
        required: true
        type: choice
        options:
          - REGULAR
      platform:
        description: 'Target platform'
        required: true
        type: choice
        options:
          - HOST
          - KUBERNETESCLUSTER
      operating-system:
        description: 'Target operating system (required when platform is HOST)'
        required: false
        type: choice
        options:
          - LINUX
          - WINDOWS

jobs:
  promote:
    runs-on: ubuntu-latest
    steps:
      - uses: newrelic/agent-metadata-action/promote-release-channel@v1
        with:
          newrelic-client-id: ${{ secrets.OAUTH_CLIENT_ID }}
          newrelic-private-key: ${{ secrets.OAUTH_CLIENT_SECRET }}
          agent-type: NRDotNetAgent # Fixed per repo, same as the release workflow
          version: ${{ inputs.version }}
          channel: ${{ inputs.channel }}
          platform: ${{ inputs.platform }}
          operating-system: ${{ inputs.operating-system }}

Then run it from the Actions tab: Actions → Promote Release Channel → Run workflow.

Building

# Build the binary
go build -o agent-metadata-action ./cmd/agent-metadata-action

# Build the release channel promotion binary (named -bin to avoid colliding
# with the ./promote-release-channel/ action directory at repo root)
go build -o promote-release-channel-bin ./cmd/promote-release-channel

Testing

Run the test suite:

# Run all tests
go test ./...

# Run tests with verbose output
go test -v ./...

Support

New Relic hosts and moderates an online forum where you can interact with New Relic employees as well as other customers to get help and share best practices. Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub. You can find this project's topic/threads here:

Add the url for the support thread here: discuss.newrelic.com

Contribute

We encourage your contributions to improve Agent Metadata Action! Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.

If you have any questions, or to execute our corporate CLA (which is required if your contribution is on behalf of a company), drop us an email at opensource@newrelic.com.

A note about vulnerabilities

As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.

If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through our bug bounty program.

If you would like to contribute to this project, review these guidelines.

To all contributors, we thank you! Without your contribution, this project would not be what it is today.

License

Agent Metadata Action is licensed under the Apache 2.0 License.