CLI Command Summaries

Overview

The Command Summaries feature records JFrog CLI command outputs into the local file system. This functionality can be used to generate a summary in the context of an entire workflow (a sequence of JFrog CLI commands) and not only in the scope of a specific command.

For example, the setup-cli GitHub action uses the compiled markdown to generate a comprehensive summary of the entire workflow.

Currently Supported Commands

Command summaries are organized by operation categories. Commands that perform operations in these categories will automatically generate summaries when the JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR environment variable is set.

Security Operations

Commands that perform security scanning operations generate summaries in the Security section:

jf scan

Scans files and directories for security vulnerabilities with JFrog Xray.

Example: jf scan path/to/files --watches=watch-name

jf build-scan

Scans build-info for security vulnerabilities.

Example: jf build-scan build-name build-number

jf docker scan

Scans Docker images for security vulnerabilities with JFrog Xray.

Example: jf docker scan my-image:tag --watches=watch-name

Build-Info Operations

Commands that publish build-info generate summaries in the BuildInfo section:

jf rt build-publish

Publishes build-info to Artifactory.

Example: jf rt build-publish build-name build-number

Upload Operations

Commands that upload files or artifacts generate summaries in the Upload section:

jf rt upload

Uploads files to Artifactory repositories.

Example: jf rt upload local-path repo-name/remote-path

jf docker push

Pushes Docker images to Artifactory.

Example: jf docker push my-image:tag

jf docker pull

Pulls Docker images from Artifactory. May generate summaries when configured.

Example: jf docker pull my-image:tag

Evidence Operations

Commands that collect evidence generate summaries in the Evidence section:

Evidence collection commands (specific commands depend on your JFrog Platform configuration)

Commands That Do Not Generate Summaries

Configuration and management commands do not generate command summaries, as they don't perform operational tasks that produce artifacts or scan results:

Note: The command summary feature aggregates results from multiple commands executed in a workflow. Each command that supports summaries will contribute to its respective section in the final markdown output generated by jf generate-summary-markdown (or jf gsm).

Configuration

To use Command Summaries, you will need to set the JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR environment variable. This variable designates the directory where the data files and markdown files will be stored.

Warning: Files Remain After CLI Execution

The CLI does not automatically remove the files as they are designed to remain beyond a single execution. It is your responsibility to manage your pipelines and delete files as necessary. You can clear the entire directory of JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR that you have configured to activate this feature.

Notes for Developers

Each command execution that incorporates this feature can save data files to the file system. These files are then used to create an aggregated summary in Markdown format.

Saving data to the file system is essential because each CLI command executes in a separate context. Consequently, each command that records new data should also incorporate any existing data into the aggregated markdown. This is required because the CLI cannot determine when a command will be the last one executed in a sequence.

Warning: Files Remain After CLI Execution

The CLI does not automatically remove the files, as they are designed to remain beyond a single execution. As a result, it is your responsibility to manage your pipelines and delete files as necessary. You can clear the entire directory of JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR that you have configured to activate this feature.

How to Implement

To contribute a new CLI command summary, follow these implementation guidelines and then submit a pull request.

Implement the CommandSummaryInterface

Record data during runtime

Implement the CommandSummaryInterface

type CommandSummaryInterface interface {
   GenerateMarkdownFromFiles(dataFilePaths []string) (finalMarkdown string, err error)
}

Record Data During Runtime

// Initialize your implementation
myNewCommandSummary, err := commandsummary.New(&MyCommandStruct{}, "myNewCommandSummary")
if err != nil {
    return
}
// Record
return myNewCommandSummary.Record(data)

The GenerateMarkdownFromFiles function needs to process multiple data files, which are the results of previous command executions, and generate a single markdown string content. As each CLI command has its own context, we need to regenerate the entire markdown with the newly added results each time.

Example Implementation

// Step 1. Implement the CommandSummaryInterface
type CommandStruct struct{}

type singleRecordedObject struct {
	Name string
}

func (cs *CommandStruct) GenerateMarkdownFromFiles(dataFilePaths []string) (markdown string, err error) {
	// Aggregate all the results into a slice
	var recordedObjects []*singleRecordedObject
	for _, path := range dataFilePaths {
		var singleObject singleRecordedObject
		if err = commandsummary.UnmarshalFromFilePath(path, &singleObject); err != nil {
			return
		}
		recordedObjects = append(recordedObjects, &singleObject)
	}

	// Create markdown
	markdown = results.String()
	return
}

// Step 2. Record data during runtime
func recordCommandSummary(data any) (err error) {
	if !commandsummary.ShouldRecordSummary() {
		return
	}

	commandSummaryImplementation, err := commandsummary.New(&CommandStruct{}, "CommandName")
	if err != nil {
		return
	}

	return commandSummaryImplementation.Record(data)
}

How Does It Work?

Each command that implements the CommandSummaryInterface will have its own subdirectory inside the JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR/JFROG_COMMAND_SUMMARY directory.

Every subdirectory will house data files, each one corresponding to a command recording, along with a markdown file that has been created from all the data files. The function you implement is responsible for processing all the data files within its subdirectory and generating a markdown string.

The directory structure looks like this:

JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR/JFROG_COMMAND_SUMMARY  
│
└─── Command1
│       datafile1.txt
│       datafile2.txt
│       markdown.txt
│   
└─── Command2
        datafile1.txt
        datafile2.txt
        markdown.txt