Getting Started

How to get started

Getting started with Steampunk Spotter is simple.

Create your account

To start using Steampunk Spotter, head over to the registration page, sign up for an account and verify your email.

Scan your playbooks

With Spotter you can scan different Ansible content, such as Ansible Playbooks, collections, roles and task files.

Decide on how to use the Steampunk Spotter:
- CLI
- App
- Integrations
- GitHub Actions
- GitLab
- VS Code

Decide on how to use the Steampunk Spotter:
- CLI
- App
- Integrations
- GitHub Actions
- GitLab

Scan from
command-line

1. Install CLI

Install the steampunk-spotter CLI tool as a Python package (Python 3 is required).

$ pip install steampunk-spotter

After the CLI is installed, you can explore all available commands and options of Spotter by running spotter --help.

2. Scan

To start checking Ansible content straight from the terminal, run the following command:

$ spotter scan /path/to/your/playbooks

The first time you run the scan command you will also have to provide your username and password for Steampunk Spotter:

- via --username/-u and --password/-p global optional arguments,
- by setting SPOTTER_USERNAME and SPOTTER_PASSWORD environment variables.

Running the scan command will show you the output that looks like this:

Spotter CLI screenshot

And if you get back nothing? Well, good for you. We found no issues with your playbooks ;)

3. Advanced usage

For more information on how to use Steampunk Spotter, run spotter scan --help or explore further instructions in the README.md.

Scan public Git repositories from the Spotter app

When you log in to the Spotter app, you will find that your personal organization with one default project has already been created for you.

Spotter projects screenshot

The project acts as a container for user's code with Ansible content and allows separating individual scans. To track the progress of individual projects over time, separate them by creating a new project for each one.

1. Create a new project

You can either create an empty project or import your code from the Git repository (by pasting its URL into the form).

Spotter projects screenshot

2. Scan

After the project from Git gets created, the Ansible content from repository will be automatically scanned. If the user has created an empty project, the scans can be initiated from the CLI.

Spotter new project screenshot

3. Get results

Check your scan results and explore how to incorporate discovered HINTS, WARNINGS and ERRORS to improve your Ansible content.

Spotter scan details screenshot

4. Collaborate with your team

Add users to your organization to create a shared workspace for your team so you can all keep up with the progress on shared projects and enable collaboration across projects. You can have one organization and include up to 3 users with one PRO subscription.

Spotter invite new user screenshot

Integrations

Scan using GitHub Actions

Steampunk Spotter GitHub Action enables scanning of Ansible content within the GitHub CI/CD workflows. When you have your Steampunk Spotter account, you can integrate Steampunk Spotter with your GitHub repository.

In your CI/CD pipeline you can specify the name of the Spotter GitHub Action xlab-steampunk/[email protected] with a tag number as a step within your YAML workflow file.

For comprehensive usage and more examples refer to Steampunk Spotter on GitHub Marketplace and Steampunk Spotter GitHub Action repository.

Scan using GitLab

Steampunk Spotter can be integrated with GitLab to display scan result as GitLab’s unit test reports. This means that you will be quickly able to see which checks have failed within your CI/CD pipeline.

This is done by using Spotter CLI tool directly in the CI/CD configuration and configuring it to output your scan result in JUnit XML format, which allows GitLab to display check results as green check marks for successful checks and red crosses for unsuccessful checks.

To do so, you should use spotter scan CLI command along with --junit-xml <path-junit-xml> optional argument that will create JUnit XML report at the specified location. Assuming that you already have your GitLab CI/CD configuration, you can create a new CI job, where you call the aforementioned CLI command and then upload the created JUnit report format XML file as an artifact to GitLab, which will then display it within your pipeline details page or merge request widget.

You can find more information on how to integrate Spotter with GitLab CI/CD in README.md.

Scan from Visual Studio Code

The Steampunk Spotter VSC extension integrates with Steampunk Spotter CLI and enables scanning and rewriting of Ansible content directly from VS Code.

You can install the extension from the Visual Studio Marketplace or Open VSX Registry. The extension requires a Steampunk Spotter user account and the Steampunk Spotter CLI installed in the console that you use with VS Code by default. You can customise the path to Steampunk Spotter CLI in the extension settings. You will be prompted to log in with your Steampunk Spotter credentials when you first activate any extension action.

Visit README.md to see the exact actions that can be performed with the Spotter VSC plugin.