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,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,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
      
   # (optional) 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.1.0'
   }
   

   If you need to consume the token in your own settings plugin, you can access it via gradle extra properties:

   if (settings.gradle.extra.has("gh-cli-auth-token")) {
      val ghToken = settings.gradle.extra["gh-cli-auth-token"] as String
   }
   

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.1.0'
   }
   

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

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

Important Notes

• 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 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.
• By default, the settings plugin will configure default repositories for plugins and dependencies (google, mavenCentral, gradlePluginPortal). This is to ensure default repositories are always available.

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.