見出し画像

シェルスクリプトのコード品質保全にVSCodeとGitHubActionsにShellCheckを導入してみた！

SHIFT Group 技術ブログ

はじめに

SHIFTで自動化アーキテクトをやっている片山 嘉誉です。

シェルスクリプトは、システム管理や自動化タスクにおいて重要な役割を果たします。しかし、そのコードが複雑になると、メンテナンスが困難になることがあります。

例えば、GitHub Actionsを使用してLinux上で自動化処理を行う場合、新しい実行環境を設定せずに標準で動作するシェルスクリプトが便利です。しかし、YAMLファイルにコードを直接記述すると、シェルスクリプトの静的解析ができなくなり、コードの保守が難しくなります。

そこで、シェルスクリプトを.shファイルに分離し、YAMLファイルからこれを呼び出す方法を推奨します。分離した.shファイルならば、ShellCheckを使用して静的解析を行うことができます。ShellCheckはシェルスクリプトの問題点を指摘し、バグの早期発見やコード品質の向上に役立ちます。

この記事では、VSCodeとGitHub ActionsにShellCheckを組み込む方法を紹介します。この設定を行うことで、VSCodeを通じてコミット前にシェルスクリプトの静的解析を実施し、GitHub Actionsを使用してプルリクエスト時にShellCheckを実行することで、コードレビュー時に問題のないコードであることを保証できます。

ShellCheckとは

まずは大前提としてShellCheckが何なのかを説明したいと思います。

ShellCheckは、bashやshのシェルスクリプトのための静的解析ツールで、シェルスクリプトに対する警告や提案を行います。ShellCheckの目的は以下の通りです。

  • 初心者が直面する一般的なシェルスクリプトの書き方の間違いを見つけて、どうすれば正しく書けるかを教えます。

  • 中級者がよく遭遇する、シェルの予期せぬ挙動の原因となる問題を発見し、その解決策を提供します。

  • 経験豊富なユーザーでも見落としがちな、特定の状況で問題を引き起こす可能性のある細かい点や注意すべき特殊なケースを指摘します。

ShellCheckは、ウェブ上で直接スクリプトを貼り付けて即時フィードバックを得ることができるShellCheck.net や、ターミナル、エディタ、ビルドやテストスイート内で使用することができます。エディタでは、Vim、Emacs、Sublime、VSCodeなど多くのエディタでShellCheckの提案を直接見ることができます。

ShellCheckの詳細や最新のリリース情報は、GitHubの公式リポジトリ で確認することができます。

VSCodeにShellCheckを導入する

それではここからVSCodeでShellCheckを使用するためのセットアップ方法について説明していきたいと思います。今回はGitのリポジトリを使用した場合を想定しており、一部Gitの場合だけ設定できるものが含まれています。

流れとしては以下のようになります。

セットアップの流れ

  1. VSCodeの拡張機能をインストールする：
    VSCodeのマーケットプレイスからShellCheckをインストールします。これにより、VSCode内で直接シェルスクリプトの静的解析が可能になります。

  2. リポジトリ内にファイルを作成してオプションの設定を行う：
    プロジェクト固有の設定を行うために、.vscode/settings.jsonや.shellcheckrcといったファイルをリポジトリ内に作成します。

  3. ShellCheckで指摘される箇所をGitの設定を行うことで回避する：
    .gitattributesファイルを使用して改行コードなどの設定を行い、ShellCheckで指摘されないようにします。

では、それぞれ詳細を見て行きましょう。

拡張機能のインストール

まずは、VSCodeの拡張機能としてShellCheckをインストールします。以下のURLからインストールできます。

https://marketplace.visualstudio.com/items?itemName=timonwong.shellcheck

ShellCheckは多くのカスタマイズオプションを提供しており、開発者はこれを利用して、特定の警告を無視したり、特定のシェル環境に合わせたチェックを行うことができます。これにより、開発者は自分のニーズに合わせてShellCheckを調整することができます。

参考ページ：


外部ファイルもチェック対象にする

共通の処理を外部ファイルで管理するようになると、外部ファイルもチェック対象にする必要性がでてきます。外部ファイルもチェック対象とするためには、.vscode/settings.jsonに以下の設定を追加します。

{
    "shellcheck.customArgs": ["-x"],
}

後述するGitHub ActionsのShellCheckではこのオプションが有効な状態で実行されるため、VSCodeでも同じチェックが行えるようにし、事前に問題を検知できるようにしておきます。

sourceに対する警告の無効化

シェルスクリプトで外部ファイルの読み込みに使用するsourceコマンドですが、ShellCheckとしてファイルの参照が出来ない場合に警告が出てしまいます。この警告は正直不要である場合が多いため、.shellcheckrcに以下の設定を追加して無効化します。

# .shellcheckrc

disable=SC1091

改行コードの設定

異なるオペレーティングシステム間での開発では、改行コードの違いが問題となることがあります。これを解決するために、.gitattributesに以下の設定を追加し、シェルスクリプトファイルと.shellcheckrcファイルの改行コードをLF（Unix形式）に統一します。

.gitattributes

*.sh text eol=lf
.shellcheckrc text eol=lf

これにより、Gitリポジトリをクローンした際に、これらのファイルの改行コードが自動的にLFに設定され、OS間での互換性が保たれます。

GitHub ActionsにShellCheckを導入する

GitHub Actionsを使用して、コードベース内のシェルスクリプトに対して自動的にコード品質チェックを行うことができます。これには、reviewdogというツールを活用することで、プルリクエストに対してコメントを通じてフィードバックを提供することが可能です。


reviewdog/action-shellcheckアクションは、ShellCheckをGitHub Actionsのワークフローに統合するためのものです。このアクションを使用すると、コードレビュー中にシェルスクリプトの問題を自動的に検出し、修正を促すことができます。

以下はreviewdog/action-shellcheckアクションを用いてプルリクエスト時にShellCheckを実行するためのサンプルとなり、例えば.github/workflows/shellcheck.ymlなどのファイルに記載します。

name: ShellCheck on pull request

on:
  pull_request:
    branches:
      - main
    paths:
      - '**/*.sh'

jobs:
  shellcheck:
    name: ShellCheck
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: shellcheck
        uses: reviewdog/action-shellcheck@v1
        with:
          level: warning

このワークフローは、プルリクエストがmainブランチに対して作成された際にトリガーされます。また、pathsセクションで指定されたパターンにマッチするファイル（この場合は**/*.shなので全てのシェルスクリプトファイル）が対象となります。

jobsセクションではreviewdog/action-shellcheckを使用してShellCheckを実行し、withセクションでは、ShellCheckの警告レベルを設定しています。今回はwarningで設定していますが、warningであれば仮に問題が検出されてもマージ禁止には成らないため、既存の問題を抱えたシェルスクリプトが多数ある場合はひとまずこの設定を行っておくと良いと思います。

おわりに

以上、VSCodeとGitHub ActionsにShellCheckを導入する方法を紹介しました。シェルスクリプトはその特性上、バグが混入しやすい言語です。しかし、ShellCheckを導入することで、その問題を大幅に軽減することができます。

また、GitHub Actionsでシェルスクリプトを使用する際には、YAMLファイルに直接コードを書くのではなく、.shファイルとして外だしにすることで、メンテナンス性を向上させることができます。

これらの手法を活用し、より品質の高いシェルスクリプトの開発を行いましょう。

それではまた次の記事で！「スキ」と「フォロー」もお願いします！

執筆者プロフィール：片山 嘉誉 (Katayama Yoshinori)
SIerとして長年AOSP（Android Open Source Project）をベースとしたAndroidスマートフォンの開発に携わり、併せてスマートフォン向けのアプリ開発を行ってきた。 Wi-FiやBluetoothといった無線通信機能の担当が長かったため通信系のシステムに強く、AWSを使用したシステム開発の経験もある。 生産性向上や自動化というワードが大好きでSHIFTでは自動化アーキテクトとして参画、GitHub ActionsやJenkinsを用いた自動化環境の構築を行っている。 最近のマイブームは生成AIの活用方法を考えることで、ニュースや記事の要約を呟くBOTなどを作成している。

お問合せはお気軽に
https://service.shiftinc.jp/contact/

SHIFTについて（コーポレートサイト）
https://www.shiftinc.jp/

SHIFTのサービスについて（サービスサイト）
https://service.shiftinc.jp/

SHIFTの導入事例
https://service.shiftinc.jp/case/

お役立ち資料はこちら
https://service.shiftinc.jp/resources/

SHIFTの採用情報はこちら
https://recruit.shiftinc.jp/career/

PHOTO：UnsplashのShahadat Rahman


最後まで読んでくださり、ありがとうございます！

御社サービスのご相談はお気軽に。
ソフトウェア品質のプロがお伺いします。