{"id":13609129,"url":"https://github.com/btkelly/gnag","last_synced_at":"2025-04-05T05:08:46.372Z","repository":{"id":48029464,"uuid":"45197311","full_name":"btkelly/gnag","owner":"btkelly","description":"A Gradle plugin that helps facilitate GitHub PR checking and automatic commenting of violations.","archived":false,"fork":false,"pushed_at":"2024-11-04T16:19:40.000Z","size":1016,"stargazers_count":125,"open_issues_count":17,"forks_count":14,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-29T04:11:18.416Z","etag":null,"topics":["android","android-lint","checkstyle","findbugs","github-pr","gradle","pmd","reporting-violations","violations"],"latest_commit_sha":null,"homepage":"http://gnag.watch","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/btkelly.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-29T16:52:59.000Z","updated_at":"2024-11-01T15:41:40.000Z","dependencies_parsed_at":"2025-01-04T20:11:14.725Z","dependency_job_id":null,"html_url":"https://github.com/btkelly/gnag","commit_stats":{"total_commits":342,"total_committers":14,"mean_commits":"24.428571428571427","dds":"0.36549707602339176","last_synced_commit":"c102bd3d1456aa03e40778471bf694aace9915ff"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btkelly%2Fgnag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btkelly%2Fgnag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btkelly%2Fgnag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btkelly%2Fgnag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/btkelly","download_url":"https://codeload.github.com/btkelly/gnag/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289428,"owners_count":20914464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-lint","checkstyle","findbugs","github-pr","gradle","pmd","reporting-violations","violations"],"created_at":"2024-08-01T19:01:32.681Z","updated_at":"2025-04-05T05:08:46.352Z","avatar_url":"https://github.com/btkelly.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"# Gnag \u003ca href=\"https://travis-ci.org/btkelly/gnag\"\u003e\u003cimg src=\"https://travis-ci.org/btkelly/gnag.svg\" /\u003e\u003c/a\u003e [![Coverage Status](https://coveralls.io/repos/btkelly/gnag/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/btkelly/gnag?branch=master) \u003ca href=\"http://www.detroitlabs.com/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Sponsor-Detroit%20Labs-000000.svg\" /\u003e\u003c/a\u003e \u003ca href='https://bintray.com/btkelly/maven/gnag-gradle-plugin/_latestVersion'\u003e\u003cimg src='https://api.bintray.com/packages/btkelly/maven/gnag-gradle-plugin/images/download.svg'\u003e\u003c/a\u003e [![Android Arsenal](https://img.shields.io/badge/Android%20Arsenal-gnag-green.svg?style=true)](https://android-arsenal.com/details/1/3128)\nGnag is a Gradle plugin that helps facilitate GitHub PR checking and automatic commenting of violations for Android projects.\n\nIt can be used in Java-only, Kotlin-only, and mixed Java/Kotlin codebases.\n\nThe name is a portmanteau of the words [\"Gradle\"](https://gradle.org/) and [\"nag\"](https://en.wiktionary.org/wiki/nag#Verb). The first \"g\" is silent!\n\n## Example Output\n\nBelow are examples of output posted to a GitHub PR on a project using Gnag to enforce quality checks.\n\nViolations associated with a specific line in your PR will be posted as comments **on that line**:\n\n![](assets/comments-inline.png)\n\nViolations that are not associated with a specific line in your PR will be aggregated and posted in a **single top-level PR comment**:\n\n![](assets/comments-aggregated.png)\n\n## Usage\n\n**Requires JDK 11 or Higher**\n\nGnag is meant to be simple to use and easy to drop in to any JVM based project. Shown below is the simplest\nGnag setup that will report violations to GitHub. By default this config will report PMD, Checkstyle, ktlint, detekt and\nAndroid Lint to GitHub.\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cb\u003ebuild.gradle (Groovy)\u003c/b\u003e\u003c/summary\u003e\n\n```groovy\nplugins {\n  id \"com.btkelly.gnag\" version \"{current version}\"\n}\n\ngnag {\n    github {\n        repoName 'btkelly/repo'\n        authToken '0000000000000'\n        issueNumber '1'\n    }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ebuild.gradle.kts (Kotlin)\u003c/b\u003e\u003c/summary\u003e\n\n```kotlin\nplugins {\n  id(\"com.btkelly.gnag\") version \"{current version}\"\n}\n\ngnag {\n    github {\n        repoName(\"btkelly/repo\")\n        authToken(\"0000000000000\")\n        issueNumber(\"1\")\n    }\n}\n```\n\n\u003c/details\u003e\n\nThis 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.\n\n### Tasks\n\nYou can use the gnagCheck gradle task to run Gnag locally and generate an HTML report in the build directory.\n```groovy\n./gradlew clean gnagCheck\n```\n\nYou can use the gnagReport task which will first run gnagCheck and then report detected violations to the GitHub issue specified.\nIn this example the issue number and authtoken for the comment user are passed as commandline arguments.\n```groovy\n./gradlew clean gnagReport -PissueNumber=11 -PauthToken=iu2n3iu2nfjknfjk23nfkj23nk\n```\n\n### Customization\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cb\u003ebuild.gradle (Groovy)\u003c/b\u003e\u003c/summary\u003e\n\n```groovy\ngnag {\n    enabled true\n    failOnError true\n\n    checkstyle {\n        enabled true\n        toolVersion \"8.45.1\"\n        reporterConfig project.file('config/checkstyle.xml')\n    }\n\n    pmd {\n        enabled true\n        toolVersion \"6.22.0\"\n        reporterConfig project.file('config/pmd.xml')\n    }\n\n    ktlint {\n        enabled true\n        toolVersion \"0.42.0\"\n    }\n\n    detekt {\n        enabled true\n        reporterConfig project.file('config/detekt.yml')\n        toolVersion \"1.17.1\"\n    }\n\n    androidLint {\n        enabled true\n        severity 'Error'\n    }\n\n    github {\n        rootUrl 'https://my.githubinstall.com/repos/'\n        repoName 'btkelly/repo'\n        authToken '0000000000000'\n        issueNumber '1'\n        setCommentInline true\n        setCommentOnSuccess true\n        useGitHubStatuses true\n    }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ebuild.gradle.kts (Kotlin)\u003c/b\u003e\u003c/summary\u003e\n\n```kotlin\ngnag {\n    isEnabled = true\n    setFailOnError(true)\n\n    checkstyle {\n        isEnabled = true\n        toolVersion(\"8.45.1\")\n        reporterConfig(project.file(\"config/checkstyle.xml\"))\n    }\n\n    pmd {\n        isEnabled = true\n        toolVersion(\"6.22.0\")\n        reporterConfig(project.file(\"config/pmd.xml\"))\n    }\n\n    ktlint {\n        isEnabled = true\n        toolVersion(\"0.35.0\")\n    }\n\n    detekt {\n        isEnabled = true\n        reporterConfig(project.file(\"config/detekt.yml\"))\n    }\n\n    androidLint {\n        isEnabled = true\n        severity(\"Error\")\n    }\n\n    github {\n        rootUrl(\"https://my.githubinstall.com/repos/\")\n        repoName(\"btkelly/repo\")\n        authToken(\"0000000000000\")\n        issueNumber(\"1\")\n        setCommentInline(true)\n        setCommentOnSuccess(true)\n        useGitHubStatuses(true)\n    }\n}\n```\n\n\u003c/details\u003e\n\n***NOTE:*** All reporters are enabled by default\n\n- ***enabled*** - easily disable Gnag in specific situations\n- ***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:\n\n    \u003cdetails open\u003e\n    \u003csummary\u003e\u003cb\u003ebuild.gradle (Groovy)\u003c/b\u003e\u003c/summary\u003e\n\n    ```\n    android {\n        lintOptions {\n            abortOnError false\n        }\n    }\n    ```\n\n    \u003c/details\u003e\n\n    \u003cdetails\u003e\n    \u003csummary\u003e\u003cb\u003ebuild.gradle.kts (Kotlin)\u003c/b\u003e\u003c/summary\u003e\n\n    ```\n    android {\n        lintOptions {\n            abortOnError(false)\n        }\n    }\n    ```\n\n    \u003c/details\u003e\n\n- ***checkstyle*** - block to customize the checkstyle reporter\n  - ***enabled*** - set if checkstyle should execute\n  - ***toolVersion*** - override the checkstyle version\n  - ***reporterConfig*** - provide a custom [checkstyle config](http://checkstyle.sourceforge.net/config.html) (see the default config [here](/plugin/src/main/resources/checkstyle.xml))\n- ***pmd*** - block to customize the PMD reporter\n  - ***enabled*** - set if PMD should execute\n  - ***toolVersion*** - override the PMD version\n  - ***reporterConfig*** - provide a custom [PMD config](http://pmd.sourceforge.net/pmd-5.1.1/howtomakearuleset.html) (see the default config [here](/plugin/src/main/resources/pmd.xml))\n- ***ktlint*** - block to customize the ktlint reporter\n  - ***enabled*** - set if ktlint should execute\n  - ***toolVersion*** - override the ktlint version\n- ***detekt*** - block to customize the detekt reporter\n  - ***enabled*** - set if detekt should execute\n  - ***reporterConfig*** - provide a custom [detekt config](https://arturbosch.github.io/detekt/configurations.html)\n  - ***toolVersion*** - override the detekt version\n- ***androidLint*** - block to customize the android lint reporter\n  - ***enabled*** - set if the android lint reporter should look for a lint report\n  - ***severity*** - can be 'Error' or 'Warning' (case insensitive) depending on which severity you want Gnag to check\n- ***github*** - block to customize GitHub reporting (only used during the `gnagReport` task\n  - ***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/\"\n  - ***repoName*** - account and repo name to report violations to\n  - ***authToken*** - a GitHub token for a user that has access to comment on issues to the specified repo\n  - ***issueNumber*** - the issue or PR number currently being built\n  - ***setCommentInline*** - whether or not comments posted to GitHub should be placed inline where possible\n  - ***setCommentOnSuccess*** - whether or not a comment should be posted to GitHub when no violations exist\n  - ***useGitHubStatuses*** - should report GitHub status on each module in the PR or just fail if ***failOnError*** enabled\n\n### Multi-Module Projects\n\nTo enforce the same quality checks across multiple Gradle modules, apply and configure Gnag in your root `build.gradle` file as follows (you can remove the equivalent code from submobule `build.gradle` files):\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cb\u003ebuild.gradle (Groovy)\u003c/b\u003e\u003c/summary\u003e\n\n```groovy\nplugins {\n  id \"com.btkelly.gnag\" version \"{current version}\" apply false\n}\n\nsubprojects {\n    plugins {\n      id \"com.btkelly.gnag\"\n    }\n\n    gnag {\n        // Standard Gnag configuration goes here.\n        //\n        // Reference tool configuration files using the rootProject:\n        //   reporterConfig rootProject.file('config/toolrules.xml')\n    }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ebuild.gradle.kts (Kotlin)\u003c/b\u003e\u003c/summary\u003e\n\n```kotlin\nplugins {\n  id(\"com.btkelly.gnag\") version \"{current version}\" apply false\n}\n\nsubprojects {\n    plugins {\n      id(\"com.btkelly.gnag\")\n    }\n\n    configure\u003ccom.btkelly.gnag.extensions.GnagPluginExtension\u003e {\n        // Standard Gnag configuration goes here.\n        //\n        // Reference tool configuration files using the rootProject:\n        //   reporterConfig(rootProject.file(\"config/toolrules.xml\"))\n    }\n}\n\n```\n\n\u003c/details\u003e\n\nYou may need to keep the Android lint portions of your configuration in submodule `build.gradle` files if your project includes non-Android submodules. In this case, you should also use the `rootProject` to reference any shared lint configuration file.\n\n## Example [Travis CI](http://travis-ci.org) Usage\n\nTravis 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.\n\nYou must set an environment variable on your Travis instance for the `PR_BOT_AUTH_TOKEN` used to post comments back to GitHub.\n\n***.travis.yml***\n\n```yml\nlanguage: android\nandroid:\n  components:\n  - platform-tools\n  - tools\n  - build-tools-25.0.3\n  - android-25\njdk:\n  - openjdk8\nbranches:\n  only:\n  - master\nscript: \"./travis-build.sh\"\n```\n\n***travis-build.sh***\n\n```bash\n#!/bin/bash\nset -ev\n\nif [ \"${TRAVIS_PULL_REQUEST}\" = \"false\" ]; then\n\t./gradlew clean gnagCheck\nelse\n\t./gradlew clean gnagReport -PauthToken=\"${PR_BOT_AUTH_TOKEN}\" -PissueNumber=\"${TRAVIS_PULL_REQUEST}\"\nfi\n```\n\n## License\n\n```\nCopyright 2016 Bryan Kelly\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbtkelly%2Fgnag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbtkelly%2Fgnag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbtkelly%2Fgnag/lists"}