Using the ARM CLI to Render Pipline JSON

This guide assumes that you are familiar with the Pipelines as Code feature. If you are not, see Use Pipelines as Code in Armory Enterprise.

Requirements

Before you start, make sure Pipelines as Code is enabled for your Armory instance. For information about how to do that, see Enable Pipelines as Code in Armory Enterprise.

Additionally, the dinghyfile and module repo must be available locally so that the ARM CLI can reference them.

Installing the ARM CLI

You can either run the ARM CLI in a Docker container or install and run it locally.

Docker container

The ARM CLI is available on Docker Hub. To download and run the ARMO CLI, use the following commands:

# Pull the latest container for the CLI
docker pull armory/arm-cli:latest
# Run the container
docker run -it armory/arm-cli /bin/sh

You can use the CLI by running the arm command in the container. For example, arm help

Download and install

To install the ARM CLI, perform the following steps:

1. Download the latest for your operating system: https://github.com/armory-io/arm/releases.

2. Unzip the package.

3. Add the ARM CLI to your $PATH by creating a symbolic link:

   For example, the following command adds arm-2.1.1-darwin-amd64 in the root directory of the user milton to the $PATH:

   ln -sf /Users/milton/arm-2.1.1-darwin-amd64 /usr/local/bin/arm
   

   Adjust the example for your environment and version.

You can now run the CLI by using the arm command. For example: arm help

MacOS: The first time you run the ARM CLI, you may encounter several warning messages depending on your security settings. These messages appear because the ARM CLI is not signed. To resolve the issue, open your Security & Privacy > General > Allow apps downladed from: and select Allow Anyway for the ARM CLI.

Integrating with IntelliJ

Optionally, you can integrate the ARM CLI with IntelliJ. This integration allows you to edit and then validate pipeline JSON directly in IntelliJ instead of having to switch to the command line. This process involves adding the CLI as an external tool to IntelliJ:

1. Open IntelliJ and go to Preferences > Tools > External Tools.

2. Add an External Tool.

3. Complete the Create Tool wizard using the following values for Tool Settings:

   • Name: Name it something descriptive, such as “ARM”
   • Program: Use the path to where the CLI is installed
   • Arguments: Use the following snippet and substitute the value for your module directory: dinghy render $FilePathRelativeToProjectRoot$ --modules <directory where templates repository checked out locally>
   • Working directory:: Use the following value: $ProjectFileDir$

4. Add a keyboard shortcut for the ARM CLI.

   1. Go to Preferences > Keymap > External Tools > Tool_Name > Add Keyboard Shortcut.
   2. Map the CLI to a shortcut.

You can now run the CLI on open any dinghyfile you have open in IntelliJ.

Using the ARM CLI

You can watch a video walk through of how to use the ARM CLI:

There is an example folder build in the release zip file.

The command you run changes slightly based on whether the dinghyfile uses modules (or other templating files) or rawdata (git push information). You can execute dinghy render --help anytime to get current supported parameters.

JSON Example files:

YAML Example files:

Example

The zip file that you downloaded for the ARM CLI includes several example dinghyfiles that you can modify to meet your needs. The following example shows what happens when you render the dinghyfile_globals example file:

$ arm dinghy render ./examples/dinghyfile_globals --modules ./examples/modules --rawdata ./examples/RawData.json --output ./testing
INFO[2020-05-08 15:49:29] Checking dinghyfile                          
INFO[2020-05-08 15:49:29] Reading rawdata file                         
INFO[2020-05-08 15:49:29] Parsing rawdata json                         
INFO[2020-05-08 15:49:29] Parsing dinghyfile                           
INFO[2020-05-08 15:49:29] Parsed dinghyfile                            
INFO[2020-05-08 15:49:29] Output:                                      
{
  "application": "global_vars",
  "globals": {
    "waitTime": "42",
    "waitname": "default-name"
  },
  "pipelines": [
    {
      "application": "global_vars",
      "name": "Made By Armory Pipeline Templates",
      "stages": [
        {
          "name": "default-name",
          "waitTime": "42",
          "type": "wait"
        },
        {
          "name": "overwrite-name",
          "waitTime": "100",
          "type": "wait"
        }
      ]
    }
  ]
}
INFO[2020-05-08 15:49:29] Final dinghyfile is a valid JSON Object. 

If the final JSON file is valid, the following message appears: Final dinghyfile is a valid JSON Object.