シェルスクリプトの標準とスタイルガイドライン

GitLabは様々なサービスやサブプロジェクトから構成されています。バックエンドのコードの大部分はRubyと Goで書かれています。しかし、デプロイやインストールなどの日常的なシステム管理作業の自動化のためにシェルスクリプトを使っているものもあります。これは歴史的な理由か、インスタンスンスンスやDockerイメージなどの依存関係を最小限にするための努力として行われています。

このページは、私たちの様々な経験に基づき、シェルスクリプトのガイドラインを定義し、整理することを目的としています。GitLabプロジェクト全体のすべてのシェルスクリプトは、最終的にこのガイドに調和するはずです。このガイドからプロジェクトごとに逸脱するものがある場合は、そのプロジェクトのREADME.mdPROCESS.md ファイルに記述してください。

シェルスクリプトの使用を避ける

caution
これは必読のセクションです。

以上、シェルスクリプトはできるだけ使わないことをお勧めします。RubyやPythonのような言語(私たちが活用しているコードベースとの整合性のために必要な場合)の方が、ほとんどの場合良い選択です。高水準のインタープリタ型言語は、より読みやすい構文を持ち、ユニットテスト、リント、エラーレポートなどの機能がより成熟しています。

シェルスクリプトを使うのは、プロジェクトの依存関係のサイズに強い制限がある場合や、特定のケースでより重要な他の要件がある場合に限られます。

このガイドの範囲

GitLabのインストール要件によると、このガイドではサポートされているLinuxディストリビューションで使われるシェル、つまり

シェル言語の選択

  • 依存リストを減らす必要がある場合は、環境から提供されているものを使用してください。alpine 例えば、Dockerイメージの場合、sh 。これは私たちのほとんどのツールイメージのベースイメージです。
  • それ以外の場所では、可能であればbashsh よりも強力ですが、それでも一般的なシェルです。

コードのスタイルとフォーマット

このセクションでは、プロジェクトにシェルスクリプトが含まれている場合に、プロジェクトのCIパイプラインに必須となるツールについて説明します。これらのツールは、シェルコードのフォーマット、エラーや脆弱性のチェックなどを自動化します。

リンティング

ShellCheckユーティリティをデフォルト設定で使用して、シェルスクリプトのlintを行っています。

シェルスクリプトを使うすべてのプロジェクトは、この GitLab CI/CD ジョブを使うべきです:

shell check:
  image: koalaman/shellcheck-alpine:stable
  stage: test
  before_script:
    - shellcheck --version
  script:
    - shellcheck scripts/**/*.sh  # path to your shell scripts
note
デフォルトでは、ShellCheck はシェルの検出を使用して使用中のシェル方言を判断します。シェルファイルが制御不能であり、ShellCheckが方言を検出できない場合は、-s フラグを使用して指定します:-s sh または-s bash

書式設定

一貫した書式を維持するためにshfmtツールを使うことをお勧めします。Google Shell Style Guide に従ってシェルスクリプトをフォーマットするので、プロジェクトのスクリプトファイルには次のshfmt を適用してください:

shfmt -i 2 -ci -w scripts/**/*.sh

LintingGitLab CI/CDジョブに加えて、シェルスクリプトを持つすべてのプロジェクトはこのジョブも使うべきです:

shfmt:
  image: mvdan/shfmt:v3.2.0-alpine
  stage: test
  before_script:
    - shfmt -version
  script:
    - shfmt -i 2 -ci -d scripts  # path to your shell scripts
note
デフォルトでは、shfmtはShellCheckと同様のシェル検出を行い、ピリオドで始まるファイルを無視します。これをオーバーライドするには、-ln フラグでシェルの方言を指定します:-ln posix または-ln bash

テスト

note
これは現在進行中です。

シェルスクリプト(BATSのような)の自動テストのためのさまざまなツールを評価するための進行中の取り組みです。

コードレビュー

レビュアーは、以下の手順で実施します:

しかし、推奨されるアクションは、前述のツールを使い、報告された違反にアドレスすることです。これにより、コードレビューの必要性がなくなるはずです。


開発者のドキュメントに戻る