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. Authenticate

Steampunk Spotter supports two kinds of credentials: 1) API token (can be generated in the user settings within the Spotter app), and 2) username and password.

• Use --api-token/-t global optional argument to supply your token credential. Alternatively, set the SPOTTER_API_TOKEN environment variable to contain the API token.
• Use --username/-u and --password/-p global optional arguments to supply your username and password. Alternatively, set the SPOTTER_USERNAME and SPOTTER_PASSWORD environment variables
• You can run spotter <options> login to persist your credentials in the Steampunk Spotter CLI's local storage, where stand for one of the approaches described above.

3. Scan

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

$ spotter scan /path/to/your/playbooks

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

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

4. Advanced usage

For more information on how to use Steampunk Spotter, run spotter scan --help or explore further instructions in the DOCUMENTATION.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.

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).

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.

3. Get results

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

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.

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/spotter-github-actions@master 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 DOCUMENTATION.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 customize the path to Steampunk Spotter CLI in the extension settings. You can log in to Steampunk Spotter by setting the API token in the extension settings or by activating the login command from the command palette.

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