Code Genie

Code Genie automatically triggers on PR creation in a Control repository. It launches a dev container, clones the repo to the PR source branch, executes one or many commands, collects JSON results per a standardized schema, maps them to PR comments, and may approve or reject the PR.

It's a general-purpose feature for any PR automation task. Trivy security scanning is one example of a feature that uses Code Genie.

You can use Code Genie for other use cases that include, but are not limited to:

• Run unit tests on the PR source branch and reject the PR if any test fails.
• Let a large language model perform a code review for the PR and reject the PR if severe problems are found.
• Perform language specific static code analysis, such as clang-tidy for C++ or ESLint for TypeScript, and reject the PR if critical problems are found.
• Automatically approve small PRs that only involve certain "low risk" files, such as documentation files, possibly after performing sanity checks like spell checking.

Configuration

When creating a Loop, a Control repo auto-configures Code Genie via .devops-loop/code-config.jsonc. You can use non-IDE dev containers for faster background runs.

{
  "code-genie": {
    "pull-request": {
      "dev-container": "TrivyScan",
      "custom-commands": [
        {
          "run-trivy": "cp /opt/run-trivy.sh /usr/code/ && \
                        chmod +x /usr/code/run-trivy.sh && \
                        REPO_URL=https://${platform-fqdm}/control/${repo-owner}/${repo}/src/branch/${pr-branch}/ \
                        /usr/code/run-trivy.sh ${code-folder} ${result-json} \
                        --reject=high \
                        --trivyArgs=\"--scanners vuln,misconfig,secret,license --license-full --severity UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL\""
        }
      ]
    }
  }
}

The JSON file provides the following key properties:

@pull-request

This property specifies how Code Genie is triggered. Code genie is triggered on PR creation as well as when more commits are added to PR.

@dev-container

This property specifies the name of the dev container to launch. The devcontainer image should be accessible from Code Genie so that it can launch the devcontainer. It's recommended to use a non-IDE dev container since such a dev container launches faster and occupies less resources than a dev container that contains an IDE. Since a Code Genie dev container runs in the background, without user interaction, including an IDE would be unnecessary overhead.

@custom-commands

This is an array of commands to run in the dev container. They run sequentially in the order specified in the JSON file. The current working directory for each command invocation is the folder in the dev container file system where the Control repository was cloned. Each command is represented by a JSON object in the array, with a single property describing what the command does (for example "run-trivy"). The value of the property is the actual Unix command-line to invoke in the dev container. It can use any tool or script that is present in the dev container.

Variables

Before Code Genie executes a command it replaces certain variables with actual values:

${platform-fqdm}

Fully qualified domain name of the Loop installation.

${repo-owner}

Owner of the cloned repository (typically a teamspace).

${repo}

Name of the cloned repository.

${pr-branch}

Name of the PR source branch (currently checked out).

${code-folder}

Folder in dev container where Control repo is cloned.

${result-json}

Path to JSON results file (unique name like cg-result-10-1.json). An invoked command may choose to generate this file, and its contents then has to comply with standardized schema for PR comment translation.

In addition to the configuration file, Code Genie requires a webhook to be present on the Control repository. For a repository that is created as part of loop creation, the webhook is automatically created. If you create a repository manually, you must create the webhook yourself.

JSON Result File

The result of executing a command can be stored in a JSON result file. The variable ${result-json} expands to the full path of that JSON file. The file name is unique for each command invocation, and includes the Control PR number and index within custom-commands array. For example, the file name may be cg-result-10-1.json if the Control PR number is 10 and the command is the first command in the custom-commands array.

After command execution Code Genie checks if a JSON result file is available. If present, it must comply with a standardized JSON schema. The JSON properties mean the following:

@results

This is an array of objects that specify code locations, typically locations within files of the Control repository. Each such object is mapped to a PR comment that is associated with a specific file ("path" property) and a line within that file ("new_position" property). The PR comment text is specified by the "body" property and may use markdown for formatting.

@pr-comments

This is an array of strings, each of which is mapped to a PR comment that is not associated with any particular file. The strings may use markdown for formatting.

@review

This object can be present to specify whether Code Genie should make a review of the PR as either approved (property "approved" set to true) or rejected (property "approved" set to false). In either case the "comment" property can be set to a comment explaining why the PR was approved or rejected.