gh-cli-auth

GitHub CLI Auth Gradle Plugin

Gradle plugin that automatically configures access to GitHub organization maven plugins and packages. Authenticates using credentials from GitHub CLI and removes the need to store personal access tokens (PATs) in your project, environment or gradle configuration.

Prerequisites

You need to have GitHub CLI installed on your system and be logged in to your GitHub account:

gh auth login --scopes "read:packages,repo,read:org"

If you’re already logged in but don’t have the required scopes, you can refresh your authentication using:

gh auth refresh --scopes "read:packages,repo,read:org"

To check your current GitHub CLI authentication status, do:

gh auth status

Usage

This plugin is split into two: one for settings and the other for project. Depending on your solution repository management, you can choose to use either one or both.

1. Setup for settings:

   In your settings.gradle file, add the following:

   # settings.gradle
      
   # to ensure that the repositories are resolved from settings.gradle
   dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    }
   
   plugins {
       id 'io.github.adelinosousa.gradle.plugins.settings.gh-cli-auth' version '1.0.4'
   }
   

2. Setup for project:

   In your build.gradle file, add the following:

   # build.gradle
   
   plugins {
       id 'io.github.adelinosousa.gradle.plugins.project.gh-cli-auth' version '1.0.4'
   }
   

   This plugin also exposes a ghCliAuth extension to access the token, if needed:

   # build.gradle
   
   val ghToken = ghCliAuth.token.get()
   

NOTE: When using both plugins, ensure that you only apply the plugin version to settings plugin block and not to the project plugin block, as it will lead to a conflict. You also won’t be able to obtain GitHub token from the ghCliAuth extension if you’re setting RepositoriesMode as FAIL_ON_PROJECT_REPOS, as it is only currently available in the project plugin. This plugin is also not compatible with locally precompiled plugin scripts in your settings.gradle.kts file, due to the way Gradle handles plugin resolution during the initialization phase.

Configuration

Regardless of which one you use, you need to specify your GitHub organization, where the plugins or packages are hosted, in the gradle.properties file:

# gradle.properties

gh.cli.auth.github.org=<your-organization>

You can also specify custom environment variable name for the GitHub CLI authentication token. Defaults GITHUB_TOKEN.

# gradle.properties

gh.cli.auth.env.name=<environment-variable-name>

NOTE: Environment variable takes precedence over the GitHub CLI token mechanism. GitHub CLI is used as a fallback if the environment variable is not set. This is by design, to ensure that the plugin remains performant and skips unnecessary checks/steps during CI/CD runs.

Notes

Currently not supported:

• Dedicated GitHub Enterprise Servers or Hosts
• Profile selection (the plugin uses the default from gh)
• Only Maven repositories are supported (no Ivy or other types)

Contributing

Contributions are welcome! Please read the contributing guidelines.

License

This project is licensed under the AGPL-3.0 License - see the LICENSE for details.

This site is open source. Improve this page.