jonaspammer.shellcheck

// This file is auto-generated by .github/workflows/gh-pages.yml - any local changes will eventually be lost!
= ansible-role-shellcheck
Jonas Pammer <[email protected]>;
:toc: left
:toclevels: 2
:toc-placement!:
:source-highlighter: rouge

https://galaxy.ansible.com/jonaspammer/shellcheck[image:https://img.shields.io/badge/available%20on%20ansible%20galaxy-jonaspammer.shellcheck-brightgreen[Version on Galaxy]]
// Important Status Badges
https://github.com/JonasPammer/ansible-role-shellcheck/actions/workflows/ci.yml[image:https://github.com/JonasPammer/ansible-role-shellcheck/actions/workflows/ci.yml/badge.svg[Testing CI]]

An Ansible role for installing shellcheck, a tool that analyzes shell scripts for errors.

[quote]
____
At first, you think "shellcheck is great," but then you wonder "why are we still using bash?"
____

toc::[]

[[meta]]
== 🔎 Metadata
Here you will find information about:

* The Ansible version required for this role
* The platforms supported by this role
* The role dependencies

.link:meta/main.yml[]
[source,yaml]
----
---
galaxy_info:
  role_name: "shellcheck"
  description: "An ansible role for installing shellcheck, a static analysis tool for shell scripts."

  author: "jonaspammer"
  license: "MIT"

  min_ansible_version: "2.11"
  platforms:
    - name: EL # (Enterprise Linux)
      versions:
        - "9" # actively tested: rockylinux9
    - name: Fedora
      versions:
        - "38" # actively tested: fedora38
        - "39" # actively tested: fedora39
    - name: Debian
      versions:
        - bullseye # actively tested: debian11
        - bookworm # actively tested: debian12
    - name: Ubuntu
      versions:
        - focal # actively tested: ubuntu2004
        - jammy # actively tested: ubuntu2204

  galaxy_tags: []

dependencies: []
----

[[requirements]]
== 📌 Requirements
Ensure that the Ansible User can `become`.

The https://galaxy.ansible.com/community/general[`community.general` collection] needs to be installed on the Ansible controller.

[[variables]]
== 📜 Role Variables
Here are the configurable variables for this role and any dependencies.

[source,yaml]
----
shellcheck_install_method: release
----
Ways to install shellcheck:
"`system`":: Use the system's package manager.
"`release`":: Link an official pre-compiled binary to `/usr/local/bin/shellcheck`.
"`source`":: Build it from source on the host.
+
[IMPORTANT]
NOT YET IMPLEMENTED.

=== Role Variables for `release` Installation Method
[source,yaml]
----
shellcheck_release: stable
----
Choose the shellcheck version to use from the releases. Use "latest" or "stable" for special values.

[source,yaml]
----
shellcheck_release_checksum_check: false
----
Enables checking the checksum of the downloaded release file.

[source,yaml]
----
shellcheck_release_checksums:
  "darwin.x86_64":
  "linux.aarch64":
  "linux.armv6hf":
  "linux.x86_64":
----
Checksum format:
`<algorithm>:<checksum|url>`, e.g. `checksum="sha256:D98291AC[...]B6DC7B97"`.

[[public_vars]]
== 📜 Facts/Variables Defined by This Role

Each variable listed here is defined when running this role and can only be overwritten using `ansible.builtin.set_facts`.

[[tags]]
== 🏷️ Tags

Tasks are tagged with the following tags:

[cols="1,1"]
|===
|Tag | Purpose

2+| This role does not have officially documented tags yet.
|===

Tags allow you to skip or run specific tasks, with all tasks running by default when no tags are provided.

[[dependencies]]
== 👫 Dependencies
List of other roles may be added here.

[[example_playbooks]]
== 📚 Example Playbook Usages
Examples on how to use this role will be provided below.

[NOTE]
====
This role is part of https://github.com/JonasPammer/ansible-roles[a collection of purpose-specific roles].

The machine needs to be set up first.
In CI, this is done in `molecule/default/prepare.yml`.

.link:molecule/default/prepare.yml[]
[source,yaml]
----
Unresolved directive in README.orig.adoc - include::molecule/default/prepare.yml[]
----

Here's a graphic showing the dependencies of this role and their soft dependencies:
image:https://raw.githubusercontent.com/JonasPammer/ansible-roles/master/graphs/dependencies_shellcheck.svg[Dependency graph of jonaspammer.shellcheck]
====

.Minimum Viable Play (Install default version)
====
[source,yaml]
----
roles:
    - role: jonaspammer.shellcheck
----
====

.To install a specific version of shellcheck
====
[source,yaml]
----
roles:
    - role: jonaspammer.shellcheck

vars:
    shellcheck_release: v0.8.0
    shellcheck_release_checksum_check: true
    shellcheck_release_checksums:
        "darwin.x86_64": "sha1:9bc3fce6784be81a2e6dc8a6019258ebb6782081"
        "linux.aarch64": "sha1:cf996b7980ac32ddf75b5f45e9f249501907082e"
        "linux.armv6hf": "sha1:9586a4a84185828cb285f1b743d88a317171f74f"
        "linux.x86_64": "sha1:c4a6087437fe65aacd8ec588ccf47574a5dc4254"
----
====

.To install shellcheck using the system package manager
====
[source,yaml]
----
roles:
    - role: jonaspammer.shellcheck

vars:
    shellcheck_install_method: system
----
====

.To build shellcheck from source
====
[source,yaml]
----
roles:
    - role: jonaspammer.shellcheck

vars:
    shellcheck_install_method: source
----
====


[[tested-distributions]]
== 🧪 Tested Distributions

This role may work on various distributions, such as Red Hat Enterprise Linux (RHEL).

|===
| OS Family | Distribution | Release Date | End of Life | Docker Image

| Rocky
| Rocky Linux 8
| 2021-06
| 2029-05
| https://github.com/geerlingguy/docker-rockylinux8-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-rockylinux8-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Rocky
| Rocky Linux 9
| 2022-07
| 2032-05
| https://github.com/geerlingguy/docker-rockylinux9-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-rockylinux9-ansible/workflows/Build/badge.svg?branch=master[CI]]

| RedHat
| Fedora 39
| 2023-11
| 2024-12
| https://github.com/geerlingguy/docker-fedora39-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-fedora39-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Debian
| Ubuntu 20.04 LTS
| 2021-04
| 2025-04
| https://github.com/geerlingguy/docker-ubuntu2004-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-ubuntu2004-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Debian
| Ubuntu 22.04 LTS
| 2022-04
| 2027-04
| https://github.com/geerlingguy/docker-ubuntu2204-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-ubuntu2204-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Debian
| Debian 11
| 2021-08
| 2024-06
| https://github.com/geerlingguy/docker-debian11-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-debian11-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Debian
| Debian 12
| 2023-06
| 2026-06
| https://github.com/geerlingguy/docker-debian12-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-debian12-ansible/workflows/Build/badge.svg?branch=master[CI]]
|===


[[tested-ansible-versions]]
== 🧪 Tested Ansible Versions

Lately, the tested Ansible versions match those found in the
https://github.com/ansible-collections/community.general#tested-with-ansible[support pattern for Ansible's `community.general` collection].
As of now:

* 2.13 (Ansible 6)
* 2.14 (Ansible 7)
* 2.15 (Ansible 8)
* 2.16 (Ansible 9)


[[development]]
== 📝 Development
// Badges about Project Conventions
https://conventionalcommits.org[image:https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg[Conventional Commits]]
https://results.pre-commit.ci/latest/github/JonasPammer/ansible-role-shellcheck/master[image:https://results.pre-commit.ci/badge/github/JonasPammer/ansible-role-shellcheck/master.svg[pre-commit.ci status]]

[[development-system-dependencies]]
=== 📌 Development Machine Dependencies

* Python 3.10 or higher
* Docker

[[development-dependencies]]
=== 📌 Development Dependencies
Development Dependencies are listed in a
https://pip.pypa.io/en/stable/user_guide/#requirements-files[pip requirements file] named `requirements-dev.txt`.
Installation instructions for Linux are as follows:

----
# Optional: create a Python virtual env and activate it for the current shell session
$ python3 -m venv venv
$ source venv/bin/activate

$ python3 -m pip install -r requirements-dev.txt
----

[[development-guidelines]]
=== ℹ️ Ansible Role Development Guidelines

Please review my https://github.com/JonasPammer/cookiecutter-ansible-role/blob/master/ROLE_DEVELOPMENT_GUIDELINES.adoc[Ansible Role Development Guidelines].

I've also shared general https://github.com/JonasPammer/cookiecutter-ansible-role/blob/master/ROLE_DEVELOPMENT_TIPS.adoc[development best practices].

[[versioning]]
=== 🔢 Versioning

Versions are defined using https://git-scm.com/book/en/v2/Git-Basics-Tagging[Tags].
These are recognized and used by Ansible Galaxy.

*Versions must not begin with `v`.*

When a new tag is made, https://github.com/JonasPammer/ansible-role-shellcheck/actions/workflows/release-to-galaxy.yml[a GitHub CI workflow]
(image:https://github.com/JonasPammer/ansible-role-shellcheck/actions/workflows/release-to-galaxy.yml/badge.svg[Release CI])
handles importing the role into my Ansible Galaxy account.

[[testing]]
=== 🧪 Testing
Automated tests run on every contribution via GitHub Workflows.

Tests cover various Linux distributions and Ansible versions.

The molecule test includes linting of all Ansible playbooks using https://github.com/ansible/ansible-lint#readme[`ansible-lint`] to ensure best practices.

To run the tests, simply execute `tox` in the command line. You can use an optional environment variable to define the Docker container distribution used by molecule:

----
$ MOLECULE_DISTRO=ubuntu2204 tox
----

For possible `MOLECULE_DISTRO` values, check the matrix in link:.github/workflows/ci.yml[].

==== 🐛 Debugging a Molecule Container

1. Execute your molecule tests with the option `MOLECULE_DESTROY=never`, e.g.:
+
[subs="quotes,macros"]
----
$ *MOLECULE_DESTROY=never MOLECULE_DISTRO=#ubuntu1604# tox -e py3-ansible-#5#*
...
  TASK [ansible-role-pip : (redacted).] pass:[************************]
  failed: [instance-py3-ansible-9] => changed=false
...
 pass:[___________________________________ summary ____________________________________]
  pre-commit: commands succeeded
ERROR:   py3-ansible-9: commands failed
----

2. Identify the name of the molecule-provisioned Docker container:
+
[subs="quotes"]
----
$ *docker ps*
#30e9b8d59cdf#   geerlingguy/docker-debian12-ansible:latest   "/lib/systemd/systemd"   8 minutes ago   Up 8 minutes                                                                                                    instance-py3-ansible-9
----

3. Access the Docker container's bash shell for debugging:
+
[subs="quotes"]
----
$ *docker exec -it #30e9b8d59cdf# /bin/bash*

root@instance-py3-ansible-2:/#
----
+
[TIP]
====
If the failure occurs during your `verify.yml` step and not the actual `converge.yml`,
the output of Ansible modules (`vars`), hosts (`hostvars`), and environment variables will be kept in files on both the provisioner and the Docker machine:
* `/var/tmp/vars.yml` (contains host variables)
* `/var/tmp/environment.yml`
Use `grep`, `cat` or transfer these as needed!
====
+
[TIP]
=====
These files are also attached to *GitHub CI Artifacts* after a workflow run, helping check differences between runs to assist debugging any issues.

image::https://user-images.githubusercontent.com/32995541/178442403-e15264ca-433a-4bc7-95db-cfadb573db3c.png[]
=====

4. Once done with debugging, exit and remove the container:
+
[subs="quotes"]
----
root@instance-py3-ansible-2:/# *exit*

$ *docker stop #30e9b8d59cdf#*

$ *docker container rm #30e9b8d59cdf#*
_or_
$ *docker container prune*
----

==== 🐛 Debugging Installed Package Versions Locally

To debug locally using tox, use the following command:
----
$ CI=true tox
----

[[development-container-extra]]
=== 🧃 TIP: Containerized Ideal Development Environment

This project provides a "1-Click Containerized Development Environment".

This container supports running Docker containers inside it (Docker-in-Docker), which is helpful for executing molecule.

To use it:

1. Make sure to meet the link:https://code.visualstudio.com/docs/remote/containers#_system-requirements[system requirements for Visual Studio Code Development Containers]. 
2. Clone the project to your machine.
3. Open the project folder in Visual Studio Code (_File - Open Folder…_).
4. If prompted about the devcontainer definition, select the option to enter it.
*If not,* execute the Visual Studio Command `Remote-Containers: Open Folder in Container` or access the Command Palette to use this command.

[TIP]
====
Consider using `Remote-Containers: Rebuild Without Cache and Reopen in Container` occasionally, as the devcontainer feature may have issues recognizing changes to its definition.
====

[NOTE]
=====
You may need to configure your host system to allow the container to use your SSH/GPG Keys. This is described in the official devcontainer docs under "Sharing Git credentials with your container."

[[cookiecutter]]
=== 🍪 CookieCutter

This project keeps in sync with
https://github.com/JonasPammer/cookiecutter-ansible-role[the original CookieCutter template]
using https://github.com/cruft/cruft[cruft] or manual adjustments as needed.

.Official Example Usage of `cruft update`
____
image::https://raw.githubusercontent.com/cruft/cruft/master/art/example_update.gif[Official Example Usage of `cruft update`]
____

==== 🕗 Changelog
Upon pushing a new tag, the Repository Maintainer will create a GitHub Release to provide a human-readable changelog with title and description.

[[pre-commit]]
=== ℹ️ General Linting and Styling Conventions
Linting and styling conventions are enforced through various pre-commit hooks.

Automatic execution of pre-commit occurs for each contribution using https://pre-commit.ci[`pre-commit.ci`].

[NOTE]
====
These pre-commit hooks may check syntax or code issues, but they do not run actual test suites. For information on testing, refer to <<testing>>.
====

[TIP]
====
[[note_pre-commit-ci]]
To integrate pre-commit into your local development workflow, change to the cloned project directory and execute `pre-commit install`. This will ensure that pre-commit checks run on every commit, aborting the commit if any hook fails.

You can also run pre-commit hooks on all files at any time with `pre-commit run --all-files`.
====

[[contributing]]
== 💪 Contributing
https://open.vscode.dev/JonasPammer/ansible-role-shellcheck[image:https://img.shields.io/static/v1?logo=visualstudiocode&label=&message=Open%20in%20Visual%20Studio%20Code&labelColor=2c2c32&color=007acc&logoColor=007acc[Open in Visual Studio Code]]
image:https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square[PRs Welcome]

:toc:
:toclevels: 3

The following sections aim to help new contributors. For detailed "Development Documentation," see <<development>>.

=== 🤝 Preamble
Thank you for considering contributing to this Project.

Following these guidelines shows respect for the developers' time who manage this open-source project. In return, they will address your issues and review changes promptly.

[[cookiecutter--contributing]]
=== 🍪 CookieCutter
Many files in this project stem from
https://github.com/JonasPammer/cookiecutter-ansible-role[the original CookieCutter template].

Verify if your proposed change applies to the template. If so, please update the template instead. You may need to submit multiple pull requests if changes apply to both the template and this project.

=== 💬 Conventional Commits

Casual contributors need not worry about following
https://www.conventionalcommits.org/en/v1.0.0/[__the spec__],
as pull requests will be squash merged into one commit. Only core contributors are required to do so to facilitate automatic version management and changelog creation.

=== 🚀 Getting Started

Contributions are made through Issues and Pull Requests (PRs). Here are some general guidelines:

* Check for existing Issues and PRs before creating yours.
* If you're new to contributions, see https://auth0.com/blog/a-first-timers-guide-to-an-open-source-project/[Auth0's first timer's guide] for tips.

==== Issues

Issues are for reporting problems or requesting new features. When you create a new Issue, a template will guide you in providing necessary information.

If you find an existing Issue relevant to your problem, add your information there instead of creating a new one.

==== Pull Requests

PRs are welcome and can quickly get your changes included in the next release. Generally, PRs should:

* Address only one concern.
* Include unit or integration tests for added or modified functionality (if tests exist).
* Be accompanied by proper documentation.
* Use the provided Pull Request template for efficient review.

For significant changes requiring discussions, open an Issue first.

The typical "fork-and-pull" workflow is:

1. Fork the repository on GitHub.
2. Clone it to your local machine.
3. Create a new branch with a clear, descriptive name.
4. Make your changes and commit them.
5. Follow the project's formatting and testing guidelines.
6. Push your changes to your fork.
7. Open a PR against the main repository and fill out the template for review.


[[changelog]]
== 🗒 Changelog
Refer to the
https://github.com/JonasPammer/ansible-role-shellcheck/releases[Release Page] for a human-readable changelog corresponding to the tags (versions) of this project.

This project follows Semantic Versioning. Report any unintended breaking changes of a minor version update.

[[license]]
== ⚖️ License

.link:LICENSE[]
----
MIT License

Copyright (c) 2022, Jonas Pammer

Permission is granted to anyone obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to allow others to do so, with the following conditions:

The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS," WITHOUT ANY WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from or in connection with the software or its use.
----