셸 스크립트 표준 및 스타일 가이드라인

GitLab은 다양한 서비스와 하위 프로젝트로 구성되어 있습니다. 백엔드 코드의 대다수는 루비 및 Go로 작성되어 있습니다. 그러나 배치, 설치 등 루틴 시스템 관리 작업을 자동화하기 위해 셸 스크립트를 사용하는 경우도 있습니다. 이는 주로 역사적인 이유로 또는 Docker 이미지를 위해 종속성을 최소화하기 위한 노력으로 이루어집니다.

본 페이지는 우리의 다양한 경험을 기반으로 셸 스크립트 가이드라인을 정의하고 조직화하는 것을 목표로 합니다. GitLab 프로젝트 전체의 셸 스크립트는 결국 이 가이드에 맞춰 일관성 있게 작성되어야 합니다. 이 가이드에서 벗어나는 경우 해당 프로젝트의 README.md 또는 PROCESS.md 파일에 설명되어야 합니다.

셸 스크립트 사용 피하기

경고: 반드시 읽어야 합니다.

위에서 말한 모든 내용을 고려할 때, 가능한 한 셸 스크립트 사용을 피하는 것이 좋습니다. 루비나 파이썬과 같은 언어(우리가 활용하는 코드베이스와 일관성을 유지해야 하는 경우)가 거의 항상 더 나은 선택입니다. 고수준의 해석 언어는 더 가독성이 높고 단위 테스트, 린팅, 오류 보고 등에 대한 성숙한 기능을 제공합니다.

특정한 경우에 프로젝트의 의존성 크기에 강력한 제약이 있거나 다른 중요한 요구 사항이 있을 때만 셸 스크립트를 사용하세요.

이 안내의 범위

GitLab 설치 요구 사항에 따르면, 이 가이드는 지원되는 Linux 배포판에서 사용되는 셸에 대해서만 다룹니다. 즉,

셸 언어 선택

종속성 목록을 줄이려면 환경에서 제공되는 것을 사용하세요. 예를 들어, 대부분의 도구 이미지의 기본 이미지인 alpine의 sh를 사용하세요.
다른 경우에는 가능하다면 bash를 사용하세요. sh보다 강력하지만 여전히 널리 퍼진 셸입니다.

코드 스타일 및 형식

이 부분에서는 프로젝트의 CI 파이프라인의 의무적인 부분이어야 하는 도구들에 대해 설명합니다. 이러한 도구들은 셸 코드 서식 지정, 오류 또는 취약점 확인 등을 자동화합니다.

린팅

우리는 ShellCheck 유틸리티의 기본 구성을 사용하여 셸 스크립트를 린트합니다.

셸 스크립트를 사용하는 모든 프로젝트는 다음과 같은 GitLab CI/CD 작업을 사용해야 합니다.

shell check:
  image: koalaman/shellcheck-alpine:stable
  stage: test
  before_script:
    - shellcheck --version
  script:
    - shellcheck scripts/**/*.sh  # 셸 스크립트 경로

참고: 기본적으로 ShellCheck는 셸 방언을 결정하기 위해 셸 탐지를 사용합니다. 셸 파일이 내용에 따라 변경되고 ShellCheck가 방언을 감지하지 못하는 경우 -s 플래그를 사용하여 지정하세요: -s sh 또는 -s bash.

서식 지정

일관된 서식을 유지하기 위해 shfmt 도구를 사용하는 것이 좋습니다. 우리는 프로젝트의 스크립트 파일에 대해 Google Shell Style Guide에 따라 셸 스크립트를 서식 지정합니다.

다음과 같은 shfmt 호출을 적용해야 합니다.

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

린팅 GitLab CI/CD 작업에 추가로, 셸 스크립트를 사용하는 모든 프로젝트는 다음 작업을 사용해야 합니다.

shfmt:
  image: mvdan/shfmt:v3.2.0-alpine
  stage: test
  before_script:
    - shfmt -version
  script:
    - shfmt -i 2 -ci -d scripts  # 셸 스크립트 경로

참고: 기본적으로, shfmt는 ShellCheck와 비슷한 셸 탐지를 사용하고 점으로 시작하는 파일을 무시합니다. 이를 재정의하려면 셸 방언을 지정하기 위해 -ln 플래그를 사용하세요: -ln posix 또는 -ln bash.

테스트

참고: 이 부분은 작업 중입니다.

셸 스크립트의 자동화된 테스트를 평가하기 위한 지속적인 노력이 이루어지고 있습니다(BATS와 같은 도구가 포함됨).

코드 리뷰

코드 리뷰는 다음에 따라 수행되어야 합니다:

그러나 권장하는 조치는 상기 도구를 사용하고 보고된 위반 사항에 대처하는 것입니다. 이로써 코드 리뷰가 필요 없게 될 것입니다.

개발 문서로 돌아가기.