Skip to content
You're viewing an older version of this GitHub Action. Do you want to see the latest version instead?
target

GitHub Action

Steampunk Spotter

3.2.0

Steampunk Spotter

target

Steampunk Spotter

An Ansible Playbook Scanning Tool that analyzes and offers recommendations for your Ansible Playbooks

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: Steampunk Spotter

              
  uses: xlab-steampunk/spotter-action@3.2.0
Learn more about this action in xlab-steampunk/spotter-action

Choose a version

GitHub Action for Steampunk Spotter

A GitHub Action for scanning your Ansible content with Steampunk Spotter.

Table of Contents

Introduction

Steampunk Spotter is an Ansible Playbook Platform that scans, analyzes, enhances, and provides insights for your playbooks.

This GitHub Action allows you to use steampunk-spotter CLI within GitHub CI/CD workflows.

Prerequisites

You will need to create a new Steampunk Spotter account to be able to use this action.

Usage

To integrate Steampunk Spotter with your GitHub CI/CD pipeline, you have to specify the name of this repository with a tag number as a step within your YAML workflow file.

For example, inside your .github/workflows/ci.yml file:

steps:
- uses: actions/checkout@master
- uses: xlab-steampunk/spotter-action@<version>

Inputs

The action accepts the following inputs:

Name Required Default Description
endpoint no / Steampunk Spotter API endpoint (instead of default https://api.spotter.steampunk.si/api).
api_token no / Steampunk Spotter API token (can be generated in the user settings within the Spotter App).
username no / Steampunk Spotter username (this is an old auth method, use API token if possible).
password no / Steampunk Spotter password (this is an old auth method, use API token if possible).
timeout no / Steampunk Spotter API timeout (in seconds).
config no / Path to JSON/YAML configuration file.
paths no . List of paths to Ansible content files to be scanned. If not specified, the whole repository is scanned.
project_id no / ID of an existing target project in the app, where the scan result will be stored. If not specified, the first project of the user's first organization (in the app) will be used.
exclude_values no false Omits parsing and uploading values from Ansible playbooks.
exclude_metadata no false Omits collecting and uploading metadata (i.e., file names, line and column numbers).
display_level no hint Displays check results with specified level or greater (e.g., warning will show all warnings and errors, but suppress hints). Available options: hint, warning, error.
no_docs_url no false Omits documentation URLs from the output.
no_scan_url no true Omits scan URL from the output.
ansible_version no / Ansible version to use for scanning. If not specified, all Ansible versions are considered for scanning.
profile no / Sets profile with selected set of checks to be used for scanning.
skip_checks no / Skips checks with specified IDs. IDs should be comma-separated, space-separated or newline-separated and can be found in the check catalog within the Spotter App.
enforce_checks no / Enforce checks with specified IDs. IDs should be comma-separated, space-separated or newline-separated and can be found in the check catalog within the Spotter App.
custom_policies_path no / Path to the file or folder with custom OPA policies written in Rego Language (enterprise feature).
custom_policies_clear no / Clears OPA policies for custom Spotter checks after scanning (enterprise feature).
debug no / Enable debug output.
sarif_file no / Sets the name of the SARIF file and triggers the creation of the SARIF report.

Outputs

The action produces the following outputs:

  • output: Scan results from scanning your Ansible content using the spotter scan command.

Environment variables

The action will take into account the following environment variables:

  • SPOTTER_ENDPOINT: Steampunk Spotter API endpoint (instead of default https://api.spotter.steampunk.si/api).
  • SPOTTER_TOKEN: Steampunk Spotter API token (can be generated in the user settings within the Spotter App);
  • SPOTTER_USERNAME: Steampunk Spotter username;
  • SPOTTER_PASSWORD: Steampunk Spotter password.

We encourage you to authenticate by setting SPOTTER_TOKEN instead of old SPOTTER_USERNAME and SPOTTER_PASSWORD environment variables.

Examples

Here are some examples of how to use this GH Action.

Minimal example that scans the whole repository would look like this:

name: Minimal CI/CD workflow for Steampunk Spotter
on: [push]
jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: xlab-steampunk/spotter-action@<version>
        env:
          SPOTTER_TOKEN: ${{ secrets.SPOTTER_TOKEN }}

A more complex example with multiple action inputs is the following:

name: More complex CI/CD workflow for Steampunk Spotter
on: [push]
jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Scan Ansible content with different inputs
        uses: xlab-steampunk/spotter-action@<version>
        with:
          endpoint: https://api.spotter.steampunk.si/api
          api_token: ${{ secrets.SPOTTER_TOKEN }}
          config: config.yaml
          paths: playbook.yaml
          exclude_values: true
          exclude_metadata: true
          display_level: error
          no_docs_url: true
          ansible_version: 2.16
          profile: full
          skip_checks: E001,E903[fqcn=sensu.sensu_go.user]
          enforce_checks: E1300,E1301
          debug: true

Next steps

Please refer to the Steampunk Spotter Documentation for a more comprehensive usage.

Acknowledgement

This GitHub Action was created by XLAB Steampunk, IT automation specialist and leading expert in building Enterprise Ansible Collections.