Gradle build와 GitHub Actions CI에 Checkstyle 추가

코드 품질을 분석하기 위한 도구는 여러가지가 있다. SonarQube 같은 대표적인 정적 코드 분석 도구를 사용해서 다양한 유형의 문제나 취약점 등을 지속적인 모니터링으로 찾아 일정 수준 이상의 코드 품질을 유지하는 것은 엔지니어로서 아주 바람직한 선택이라고 생각한다. 오늘은 SonarQube 같은 다양한 기능의 프로그램이 아닌 간단한 방식으로 코드 분석을 도와줄 수 있는 Checkstyle을 도입한 경험을 포스팅 해보겠다.

Code Quality Tool & Secure Analysis with SonarQube

 

Checkstyle

---

 

Checkstyle은 이름처럼 스타일을 체크해주는 Java 진영의 간단한 코드 분석 도구이다. 프로젝트를 진행하면 팀 별로 코딩 컨벤션을 정하거나 이미 유명한 구글 자바 스타일 가이드나 네이버 자바 코딩 컨벤션 등의 팀의 공통적인 코딩 컨벤션에 어긋나는 코드가 있는지 분석해주는 툴이다.

checkstyle – Checkstyle 10.16.0

 

리포트가 아주 자세히 나오는 것은 아니지만, 팀끼리의 공통적인 컨벤션을 맞추어 무분별하지 않은 협업에 도움이 될 수 있도록 해주는 간편하고 아주 기본적인 툴이 될 수 있기에 자주 적용하는 것 같다. 검사할 수 있는 스타일 또한 매우 다양하다. 너무 많기 때문에 구글 자바 스타일 가이드를 기반으로 약간만 수정해서 사용하게 된다. 어떤 종류가 있는지 궁금하다면 공식 문서에서 확인해보는 것을 추천한다.

 

인텔리제이 Checkstyle 플러그인도 존재한다. UI가 좋아서 이것도 매우 쓸만하지만, 개인 디바이스만 적용하는 사례가 아닌 팀의 공통적인, 특히 자동으로 컨벤션 분석을 해줄 수 있게끔 Gradle과 CI 과정에 적용했던 사례를 공유하고자 한다.

CheckStyle-IDEA - IntelliJ IDEs Plugin | Marketplace

 

Checkstyle Gradle plugin

---

우선 Gradle에 빌드 할 때마다 Checkstyle이 구동되게끔 추가해보겠다. Gradle에 Checkstyle 플러그인이 존재하니 이를 활용하면 간단하다. 먼저 해당 플러그인을 build.gradle에 추가해준다.

plugins {
    id 'checkstyle'
}

 

플러그인을 추가하기만 하면 빌드 시 check 태스크를 실행하게 되는데, 이 때 Checkstyle의 태스크들을 수행한다. 수행되는 태스크들은 다음과 같다.

1. checkstyleMain - main 아래의 코드를 분석
2. checkstyleTest - test 아래의 코드를 분석

어떤 컨벤션을 기준으로 분석을 진행할 것인지 판단할 수 있는 xml 파일이 들어갈 위치는 다음과 같다.

<root>
└── config
    └── checkstyle           
        └── checkstyle.xml   
        └── suppressions.xml

프로젝트 디렉터리 아래에 config/checkstyle에 반드시 들어가야한다. 플러그인이 기본적으로 읽는 장소가 이곳이다. 우리는 구글 자바 스타일 가이드를 기반으로 약간 커스텀해서 사용했었는데, checkstyle.xml에 javadoc도 스캔 대상에 포함되어 애먹었던 적이 있다. javadoc이 없는 메서드들은 모두 Checkstyle 경고가 떴었고 이를 허용해주기 위해 suppressions.xml에 제외할 체크를 지정했지만 전혀 적용되지 않아 한참을 해맸던 적이 있다. 알고보니 checkstyle.xml에 하나가 잘못 쓰여있었기 때문이었다. 공식적으로 제공되는 checkstyle.xml을 커스텀할 땐 조심하자!!

 

그 다음 Checkstyle 태스크 진행 시 발행할 리포트를 정한다.

tasks.withType(Checkstyle) {
    reports {
        xml.required = true
        html.required = true
    }
}

그리고 빌드를 하면 checkstyle 리포트가 생성된다. 리포트가 생성되는 위치는 다음과 같다.

<root>
└── build
    └── reports
        └── checkstyle
                └── main.html
                └── main.xml
                └── test.html
                └── test.xml

요구된 xml과 html 형식의 리포트가 위의 디렉터리에 생성되는 것을 확인할 수 있다.

 

리포트는 아래처럼 생겼다.

이렇게 Gradle로 빌드 시 Checkstyle 리포트를 생성하는 작업을 마쳤다. 하지만 이를 확인할 수 있는 것은 아직 개인 디바이스에서만 직접 확인이 가능하다. 자동화된 스크립트에 해당 스텝을 추가해서 팀원들이 새로운 커밋을 추가하거나 PR을 생성했을 때 확인할 수 있도록 CI에 추가해보자.

 

GitHub Actions에 Checkstyle Report 추가

---

아쉽게도 일반적인 테스트 리포트나 Jacoco 리포트 등을 출력해주는 작업과는 다르게, Checkstyle 리포트를 생성해주는 action은 별로 없었다. 그래도 최근까지 쭉 관리를 해주고 있는 action이 감사하게도 존재하기 때문에 해당 오픈 소스를 사용해보려고 한다.

Publish Checkstyle Code Report - GitHub Marketplace

 

Github Actions에 적당한 위치에 다음과 같이 스텝을 추가했다. permission에 반드시 checks에 작성할 수 있는 권한을 주어야한다.

permissions:
  contents: read
  checks: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      ...
      - name: Flush Checkstyle report on the status checks
        uses: lcollins/checkstyle-github-action@v2.0.0
        with:
          path: '**/build/reports/checkstyle/**.xml'
          title: 📝 Checkstyle report
      ...

이제 Repository 페이지의 Actions 탭으로 이동해 동작하는 것을 지켜보면, 해당 step 실행 시 자동으로 새로운 Job이 등록되는 것을 확인할 수 있다.

해당 Job을 클릭해서 리포트로 생성된 check를 확인할 수 있다.

 

Gradle 빌드에 플러그인 추가 없이 GitHub Actions CI에서 한 번에 진행하기

---

비교적 최근에 나와 꾸준히 관리되고 있는 action이 있다. 이 action을 사용하면 좀 더 간단하게 GitHub Actions YAML만으로도 CI에 추가가 가능하니 활용하는 것도 좋다고 생각한다. 무엇보다 코멘트로 작성해주는 것이 어찌보면 번잡해보일 수도 있지만 눈에 잘 들어오니 괜찮은 것 같다. 이건 나중에 적용해봐야겠다. 이걸 적용했다고 해서 Gradle에 build에서 checkstyle plugin을 무작정 빼면 안된다! 인텔리제이 플러그인으로 돌리거나 Gradle build을 통해 원격 레퍼지터리에 올리기 전에 확인은 꼭 필요하다.

GitHub - dbelyaev/action-checkstyle: reviewdog based GitHub action to run Checkstyle on your Java code.

 

References

---

https://docs.gradle.org/current/userguide/checkstyle_plugin.html

The Checkstyle Plugin