Skip to content
A Gradle plugin that helps facilitate GitHub PR checking and automatic commenting of violations.
Java Groovy Kotlin Shell
Branch: master
Clone or download
btkelly Merge pull request #230 from bmunzenb/upgrade-detekt
Provide configuration option to override version of detekt
Latest commit c3de8d0 Sep 11, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets Add new screenshots for inline/aggregate comments Jun 1, 2016
example-android-kts Add Android example using Kotlin build scripts Apr 2, 2019
example-android Merge pull request #201 from btkelly/update-gradles Jan 10, 2019
example-java-kotlin-kts Add example configured using Kotlin Gradle DSL Jan 10, 2019
example-java-kotlin Add example configured using Kotlin Gradle DSL Jan 10, 2019
example-reports Add detekt to Gnag Jul 28, 2018
gradle/wrapper Update all Gradle wrapper versions Jan 8, 2019
plugin Provide configuration option to override version of detekt Sep 10, 2019
.gitignore Ignore root iml file Apr 4, 2019
.travis.yml Switching over to open JDK 8 Aug 9, 2019
CONTRIBUTING.md Update CONTRIBUTING doc for multiple examples Aug 8, 2019
LICENSE.txt Update LICENSE.txt Oct 16, 2016
LICENSE_HEADER.txt Fix license headers Oct 24, 2016
README.md Provide configuration option to override version of detekt Sep 10, 2019
build.gradle Added example Android app which can be used to test the Gnag plugin Apr 15, 2016
buildAndRunAndroidExample.sh Added a basic example java application Feb 7, 2017
buildAndRunAndroidKtsExample.sh Add Android example using Kotlin build scripts Apr 2, 2019
buildAndRunJavaKotlinExample.sh Replace java/kotlin examples with mixed source example Oct 27, 2017
buildAndRunJavaKotlinKtsExample.sh Add example configured using Kotlin Gradle DSL Jan 10, 2019
gradlew Bump Gradle wrapper versions to latest Jul 9, 2018
gradlew.bat Update Gradle wrapper to 3.4 Mar 1, 2017
settings.gradle Fix whitespace errors Jun 23, 2016
version.gradle Version bump Apr 19, 2019

README.md

Gnag Coverage Status Android Arsenal

Gnag is a Gradle plugin that helps facilitate GitHub PR checking and automatic commenting of violations for Android projects.

It can be used in Java-only, Kotlin-only, and mixed Java/Kotlin codebases.

The name is a portmanteau of the words "Gradle" and "nag". The first "g" is silent!

Usage

Requires JDK 8

Gnag is meant to be simple to use and easy to drop in to any Android project. Shown below is the simplest Gnag setup that will report violations to GitHub. By default this config will report PMD, Findbugs, Checkstyle and Android Lint to GitHub.

groovy
buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'com.btkelly:gnag:{current version}'
    }
}

apply plugin: 'gnag'

gnag {
    github {
        repoName 'btkelly/repo'
        authToken '0000000000000'
        issueNumber '1'
    }
}
kotlin
buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath("com.btkelly:gnag:{current version}")
    }
}

plugins {
    id("gnag")
}

gnag {
    github {
        repoName("btkelly/repo")
        authToken("0000000000000")
        issueNumber("1")
    }
}

This is the simplest way to add automatic PR checking and commenting to your project. The options defined in the github closure can be overridden by passing command line parameters with the same name to your build. This is helpful when using in conjunction with a CI system to allow automated builds.

Tasks

You can use the gnagCheck gradle task to run Gnag locally and generate an HTML report in the build directory.

./gradlew clean gnagCheck

You can use the gnagReport task which will first run gnagCheck and then report detected violations to the GitHub issue specified. In this example the issue number and authtoken for the comment user are passed as commandline arguments.

./gradlew clean gnagReport -PissueNumber=11 -PauthToken=iu2n3iu2nfjknfjk23nfkj23nk

Customization

groovy
gnag {
    enabled true
    failOnError true

    checkstyle {
        enabled true
        reporterConfig project.file('config/checkstyle.xml')
    }

    pmd {
        enabled true
        reporterConfig project.file('config/pmd.xml')
    }

    findbugs {
        enabled true
        reporterConfig project.file('config/findbugs.xml')
    }

    ktlint {
        enabled true
        toolVersion "0.24.0"
    }

    detekt {
        enabled true
        reporterConfig project.file('config/detekt.yml')
        toolVersion "1.0.1"
    }

    androidLint {
        enabled true
        severity 'Error'
    }

    github {
        rootUrl 'https://my.githubinstall.com/repos/'
        repoName 'btkelly/repo'
        authToken '0000000000000'
        issueNumber '1'
        setCommentInline true
        setCommentOnSuccess true
        useGitHubStatuses true
    }
}
kotlin
gnag {
    isEnabled = true
    setFailOnError(true)

    checkstyle {
        isEnabled = true
        reporterConfig(project.file("config/checkstyle.xml"))
    }

    pmd {
        isEnabled = true
        reporterConfig(project.file("config/pmd.xml"))
    }

    findbugs {
        isEnabled = true
        reporterConfig(project.file("config/findbugs.xml"))
    }

    ktlint {
        isEnabled = true
        toolVersion("0.24.0")
    }

    detekt {
        isEnabled = true
        reporterConfig(project.file("config/detekt.yml"))
    }

    androidLint {
        isEnabled = true
        severity("Error")
    }

    github {
        rootUrl("https://my.githubinstall.com/repos/")
        repoName("btkelly/repo")
        authToken("0000000000000")
        issueNumber("1")
        setCommentInline(true)
        setCommentOnSuccess(true)
        useGitHubStatuses(true)
    }
}

NOTE: All reporters are enabled by default

  • enabled - easily disable Gnag in specific situations

  • failOnError - should violations cause the build to fail or just generate a report; if set to false, you may need to add the following to prevent your build still failing from Android Lint errors:

    groovy
    android {
        lintOptions {
            abortOnError false
        }
    }
    
    kotlin
    android {
        lintOptions {
            abortOnError(false)
        }
    }
    
  • checkstyle - block to customize the checkstyle reporter

    • enabled - set if checkstyle should execute
    • reporterConfig - provide a custom checkstyle config (see the default config here)
  • pmd - block to customize the PMD reporter

    • enabled - set if PMD should execute
    • reporterConfig - provide a custom PMD config (see the default config here)
  • findbugs - block to customize the findbugs reporter

    • enabled - set if findbugs should execute
    • reporterConfig - provide a custom findbugs config
  • ktlint - block to customize the ktlint reporter

    • enabled - set if ktlint should execute
    • toolVersion - override the ktlint version compiled into Gnag
  • detekt - block to customize the detekt reporter

    • enabled - set if detekt should execute
    • reporterConfig - provide a custom detekt config
    • toolVersion - override the detekt version compiled into Gnag
  • androidLint - block to customize the android lint reporter

    • enabled - set if the android lint reporter should look for a lint report
    • severity - can be 'Error' or 'Warning' (case insensitive) depending on which severity you want Gnag to check
  • github - block to customize GitHub reporting (only used during the gnagReport task

    • rootUrl - root URL to use when communicating with the GitHub API (must include trailing slash), if not provided will default to "https://api.github.com/repos/"
    • repoName - account and repo name to report violations to
    • authToken - a GitHub token for a user that has access to comment on issues to the specified repo
    • issueNumber - the issue or PR number currently being built
    • setCommentInline - whether or not comments posted to GitHub should be placed inline where possible
    • setCommentOnSuccess - whether or not a comment should be posted to GitHub when no violations exist
    • useGitHubStatuses - should report GitHub status on each module in the PR or just fail if failOnError enabled

Example Output

Below are examples of output posted to a GitHub PR on a project using Gnag to enforce quality checks.

Inline Comments

Violations associated with a specific line in your PR will be posted as comments on that line:

Aggregated Comments

Violations that cannot be associated with a specific line in your PR will be aggregated and posted in a single top-level PR comment. This will include:

  • violations associated with entire files or projects;
  • violations detected by individual reporters with invalid file location information.

Example Travis CI Usage

Travis is a continuous integration service and is free for open source projects. Below is an example of how to configure Gnag to run on Travis.

You must set an environment variable on your Travis instance for the PR_BOT_AUTH_TOKEN used to post comments back to GitHub.

.travis.yml

language: android
android:
  components:
  - platform-tools
  - tools
  - build-tools-25.0.3
  - android-25
jdk:
  - openjdk8
branches:
  only:
  - master
script: "./travis-build.sh"

travis-build.sh

#!/bin/bash
set -ev

if [ "${TRAVIS_PULL_REQUEST}" = "false" ]; then
	./gradlew clean gnagCheck
else
	./gradlew clean gnagReport -PauthToken="${PR_BOT_AUTH_TOKEN}" -PissueNumber="${TRAVIS_PULL_REQUEST}"
fi

License

Copyright 2016 Bryan Kelly

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
You can’t perform that action at this time.