Actions in Git

For this example we'll be using Github and Github Actions to store and deploy our Actions.

Repository Structure

There are plenty of ways to organize your own Actions repository, this CI/CD overview covers how we at BrazenCloud manage our own Actions Git repository. Everything is sorted into folders to automatically generate a naming convention.

For reference, our public Actions repository is located on Github.

Each folder in the root of the repository is considered a root level name space that is then further divided up into categories by utilizing subfolders underneath the root folders. For example, we'll look at the inventory:netstat Action. Going by its name, we know that it is located in the inventory\netstat folder:

.\inventory\netstat\manifest.txt

You do have to be careful about nesting folders too far using this naming convention as the name can get a bit long.

Workflow

The Github Actions workflow consists of 5 steps:

1. Check out the code, default first step.

2. Download the BrazenCloud utility

3. Download any external executables (we choose not to store binary files in Git, this is NOT a requirement)

4. Authenticate to BrazenCloud using repository secrets

5. Run a script to build each Action with the BrazenCloud utility.

First, we'll be running this on Ubuntu, so we'll use:

runs-on: ubuntu-latest

Step 1 is to check out the code from the Git repository:

- uses: actions/checkout@v2

Step 2 currently requires you to upload the BrazenCloud utility to a place accessible to your workflow, however we plan on providing an official link in the near future. In the meantime, you can use the link in this step. We'll also chmod +x in order to make it executable:

- name: Download runway.bin
  run: |
    wget https://runwaydownloads.blob.core.windows.net/appdl/runway.bin
    chmod +x ./runway.bin

Step 3 is to replace any executables that are represented by empty files with a name that starts with a period. This is NOT a required step. For simplicity, you can store binary files in Git. However, we've designed our Actions repository so that we don't have to store them in Git for the sake of keeping the size of the repository in check.

We have a PowerShell script that finds all of the empty files with names that start with a period and replaces them with the appropriate binary file.

Here is that step in the workflow:

- name: Download any executables
  shell: pwsh
  run: ./reposcripts/replaceExecutables.ps1

Step 4 is to run the login command referencing your BrazenCloud email and password stored as repository secrets:

- name: Auth to BrazenCloud
  run: |
    ./runway.bin login -u ${{ secrets.RUNWAY_EMAIL }} -p ${{ secrets.RUNWAY_PASSWORD }}

And finally, we run a PowerShell script that looks for all the manifest.txt files in the repository and assumes that each folder containing one of those, is an Action. It then uses the relative path of that folder to name the Action when running the build command:

- name: Publish Each Action on Push
  if: ${{ github.event_name == 'push' }}
  shell: pwsh
  run: ./reposcripts/publish.ps1

One thing to notice on this final step is that with the if statement, this will only run when there is a push to the branches specified in the on: block. In this case main. On a PR, the publish script will only do local compiles of each Action which does a small amount of verification.