Skip to content

Commit d0abd79

Browse files
u-ways-eu-ways-e
committed
docs: update README to enhance structure and clarify plugin usage
1 parent be66c92 commit d0abd79

1 file changed

Lines changed: 171 additions & 71 deletions

File tree

‎README.md‎

Lines changed: 171 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,115 +1,215 @@
1-
[![Gradle Plugin Portal](https://img.shields.io/gradle-plugin-portal/v/io.github.adelinosousa.gradle.plugins.settings.gh-cli-auth.svg?label=gh-cli-auth%20Settings%20Plugin)](https://plugins.gradle.org/plugin/io.github.adelinosousa.gradle.plugins.settings.gh-cli-auth)
2-
[![Gradle Plugin Portal](https://img.shields.io/gradle-plugin-portal/v/io.github.adelinosousa.gradle.plugins.project.gh-cli-auth.svg?label=gh-cli-auth%20Project%20Plugin)](https://plugins.gradle.org/plugin/io.github.adelinosousa.gradle.plugins.project.gh-cli-auth)
3-
41
# GitHub CLI Auth Gradle Plugin
52

6-
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.
3+
[![Kotlin](https://img.shields.io/badge/Kotlin-%237F52FF.svg?logo=kotlin&logoColor=white)](#)
4+
[![Continuous Integration](https://github.com/adelinosousa/gh-cli-auth/actions/workflows/pr-checks.yml/badge.svg)](https://github.com/adelinosousa/gh-cli-auth/actions/workflows/pr-checks.yml)
5+
[![Continuous Deployment](https://github.com/adelinosousa/gh-cli-auth/actions/workflows/publish-plugin.yml/badge.svg)](https://github.com/adelinosousa/gh-cli-auth/actions/workflows/publish-plugin.yml)
6+
[![Gradle Plugin Portal](https://img.shields.io/gradle-plugin-portal/v/io.github.adelinosousa.gradle.plugins.settings.gh-cli-auth.svg?label=Settings%20Plugin)](https://plugins.gradle.org/plugin/io.github.adelinosousa.gradle.plugins.settings.gh-cli-auth)
7+
[![Gradle Plugin Portal](https://img.shields.io/gradle-plugin-portal/v/io.github.adelinosousa.gradle.plugins.project.gh-cli-auth.svg?label=Project%20Plugin)](https://plugins.gradle.org/plugin/io.github.adelinosousa.gradle.plugins.project.gh-cli-auth)
8+
9+
1. [Overview](#overview)
10+
2. [Features](#features)
11+
3. [Installation](#installation)
12+
- [A) Settings Plugin (Recommended)](#a-settings-plugin-recommended)
13+
- [B) Project Plugin (Per Project)](#b-project-plugin-per-project)
14+
4. [Usage](#usage)
15+
- [1) Required: Set Your GitHub Organization](#1-required-tell-the-plugin-which-organization-to-use)
16+
- [2) Choose How to Provide Credentials](#2-choose-how-you-want-to-provide-credentials)
17+
5. [Configuration Options](#configuration-options)
18+
- [Token Resolution Order](#token-resolution-order)
19+
- [GitHub CLI Scopes](#github-cli-scopes-cli-fallback)
20+
- [Repository Configuration](#repository-thats-registered)
21+
6. [CI Tips](#ci-tips)
22+
7. [Troubleshooting](#troubleshooting)
23+
8. [Limitations](#limitations)
24+
9. [Contributing](#contributing)
25+
10. [License](#license)
26+
27+
## Overview
28+
29+
**Zero‑boilerplate access to GitHub Packages (Maven) for your organization.**
30+
31+
This plugin family configures the GitHub Packages Maven repository for your org and provides credentials automatically from one of three sources (in order):
32+
33+
1. **Environment variable** (name configurable, default `GITHUB_TOKEN`)
34+
2. **Gradle property** (key configurable, default `gpr.token`)
35+
3. **GitHub CLI**: parses `gh auth status --show-token` (requires `read:packages, read:org`)
36+
37+
> [!NOTE]
38+
> This allows you to onboard this plugin to existing production CI/CD pipelines with minimal changes, while also supporting local development via the GitHub CLI.
39+
40+
It works as a **settings** plugin (centralized repository management for the whole build) and/or a **project** plugin (per‑project repository + a `ghCliAuth` extension to read the token).
41+
42+
## Features
43+
44+
- Registers your authenticated GitHub Packages Maven repository for your organization automatically.
45+
- Complete backwards compatibility with existing environment-based and Gradle property-based token provisioning.
46+
- Ensures common “trusted” repos are present at settings level (added *only if missing*) such as Maven Central and Gradle Plugin Portal.
47+
- Most importantly, No need to rely on hardcoded tokens local configs anymore, just use the GitHub CLI for local dev!
748

8-
## Prerequisites
49+
## Installation
950

10-
You need to have [GitHub CLI](https://cli.github.com/) installed on your system and be logged in to your GitHub account:
51+
You can use **either** plugin—or **both** together.
1152

12-
```bash
13-
gh auth login --scopes "read:packages,read:org"
53+
> [!TIP]
54+
> **Recommendation:** In multi‑module builds (or when using `RepositoriesMode.FAIL_ON_PROJECT_REPOS`), prefer the **settings** plugin to centralize repository configuration. The **project** plugin declares repositories at project level and may conflict with `FAIL_ON_PROJECT_REPOS`.
55+
56+
### A) Settings plugin (recommended)
57+
58+
**Kotlin DSL – `settings.gradle.kts`**
59+
60+
```kotlin
61+
plugins {
62+
id("io.github.adelinosousa.gradle.plugins.settings.gh-cli-auth") version "2.0.0"
63+
}
64+
```
65+
66+
**Groovy DSL – `settings.gradle`**
67+
68+
```groovy
69+
plugins {
70+
id 'io.github.adelinosousa.gradle.plugins.settings.gh-cli-auth' version '2.0.0'
71+
}
1472
```
1573

16-
If you're already logged in but don't have the required scopes, you can refresh your authentication using:
74+
With the settings plugin applied, your build will have:
75+
76+
- **GitHub Packages** repo for your org in both `pluginManagement` and `dependencyResolutionManagement`.
77+
- **Default** repos added if missing: Gradle Plugin Portal, Google, Maven Central.
78+
- A shared token available at `gradle.extra["gh.cli.auth.token"]`.
79+
80+
### B) Project plugin (per project)
1781

18-
```bash
19-
gh auth refresh --scopes "read:packages,read:org"
82+
**Kotlin DSL – `build.gradle.kts`**
83+
84+
```kotlin
85+
plugins {
86+
id("io.github.adelinosousa.gradle.plugins.project.gh-cli-auth") version "2.0.0"
87+
}
2088
```
2189

22-
To check your current GitHub CLI authentication status, do:
90+
**Groovy DSL – `build.gradle`**
2391

24-
```bash
25-
gh auth status
92+
```groovy
93+
plugins {
94+
id 'io.github.adelinosousa.gradle.plugins.project.gh-cli-auth' version '2.0.0'
95+
}
2696
```
2797

98+
With the project plugin applied, your project will have:
99+
- **GitHub Packages** repo for your org at `project.repositories`.
100+
- The **`ghCliAuth`** extension exposing the token:
101+
- Kotlin: `val token: String? = extensions.getByName("ghCliAuth") as io.github.adelinosousa.gradle.extensions.GhCliAuthExtension; token.token.get()`
102+
- Groovy: `def token = extensions.getByName("ghCliAuth").token.get()`
103+
28104
## Usage
29105

30-
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.
106+
### 1) Required: Tell the plugin which **organization** to use
31107

32-
1. Setup for `settings`:
108+
Add this to your **`gradle.properties`** (root of the build):
33109

34-
In your `settings.gradle` file, add the following:
110+
```properties
111+
gh.cli.auth.github.org=<your-organization>
112+
````
35113

36-
```shell
37-
# settings.gradle
38-
39-
# (optional) ensure that the repositories are resolved from settings.gradle
40-
dependencyResolutionManagement {
41-
repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
42-
}
114+
### 2) Choose how you want to provide credentials
43115

44-
plugins {
45-
id 'io.github.adelinosousa.gradle.plugins.settings.gh-cli-auth' version '1.1.0'
46-
}
47-
```
48-
49-
If you need to consume the token in your own settings plugin, you can access it via gradle extra properties:
116+
You can do nothing (and rely on the GitHub CLI path below), or pick one of these:
50117

51-
```shell
52-
if (settings.gradle.extra.has("gh.cli.auth.token")) {
53-
val ghToken = settings.gradle.extra["gh.cli.auth.token"] as String
54-
}
55-
```
118+
- **Environment variable** (fastest for CI):
119+
- Leave default: export `GITHUB_TOKEN`
120+
- Or choose a name: set `gh.cli.auth.env.name` in `gradle.properties` and export that variable.
56121

57-
2. Setup for `project`:
122+
- **Gradle property** (CLI args or `gradle.properties`):
123+
- Leave default key: `gpr.token`
124+
- Or choose a key: set `gh.cli.auth.property.name` and pass `-P<that-key>=<token>` (or define it in `gradle.properties`).
58125

59-
In your `build.gradle` file, add the following:
126+
- **GitHub CLI** fallback:
127+
- Make sure `gh` is installed and authenticated with the required scopes:
60128

61-
```shell
62-
# build.gradle
129+
```bash
130+
gh auth login --scopes "read:packages,read:org"
131+
# or, if already logged in:
132+
gh auth refresh --scopes "read:packages,read:org"
133+
gh auth status
134+
```
63135

64-
plugins {
65-
id 'io.github.adelinosousa.gradle.plugins.project.gh-cli-auth' version '1.1.0'
66-
}
67-
```
136+
> [!WARNING]
137+
> If both ENV and Gradle property are absent, the plugin automatically falls back to the GitHub CLI route.
68138

69-
This plugin exposes a `ghCliAuth` extension to access the token, if needed:
139+
## Configuration Options
70140

71-
```shell
72-
# build.gradle
141+
| Key / Surface | Where to set/read | Default | Purpose |
142+
|-------------------------------------|-------------------------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------|
143+
| `gh.cli.auth.github.org` | `gradle.properties` | **(required)** | GitHub Organization used to build the repo URL and name the repo entry (`https://maven.pkg.github.com/<org>/*`). |
144+
| `gh.cli.auth.env.name` | `gradle.properties` | `GITHUB_TOKEN` | Name of the environment variable the plugin checks **first** for the token. |
145+
| `gh.cli.auth.property.name` | `gradle.properties` | `gpr.token` | Name of the Gradle property the plugin checks **second** for the token (e.g., pass `-Pgpr.token=...` or define in properties). |
146+
| `gradle.extra["gh.cli.auth.token"]` | **read** in `settings.gradle(.kts)` | n/a | Token shared by the **settings** plugin for use by other settings logic/plugins. |
147+
| `ghCliAuth.token` | **read** in `build.gradle(.kts)` | n/a | Token exposed by the **project** plugin’s extension. |
148+
| `-Dgh.cli.binary.path=/path/to/gh` | JVM/system property | auto‑detect | Override the `gh` binary path used by the CLI fallback. Useful for custom installs (e.g., Homebrew prefix, Nix). |
73149

74-
val ghToken = ghCliAuth.token.get()
75-
```
150+
### Token resolution order
76151

77-
### Important Notes
78-
- When using both plugins, ensure that you **only** apply the plugin version to <u>settings</u> plugin block and not to the <u>project</u> plugin block, as it will lead to a conflict.
79-
- 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.
80-
- 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.
152+
```
153+
ENV (name = gh.cli.auth.env.name, default GITHUB_TOKEN)
154+
└── if unset/empty → GRADLE PROPERTY (key = gh.cli.auth.property.name, default gpr.token)
155+
└── if unset/empty → GitHub CLI: gh auth status --show-token
156+
```
81157
82-
### Configuration
158+
### GitHub CLI scopes (CLI fallback):
83159
84-
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:
160+
Below is the required scopes for the token retrieved via the GitHub CLI:
85161
86-
```properties
87-
# gradle.properties
162+
- `read:packages`
163+
- `read:org`
88164
89-
gh.cli.auth.github.org=<your-organization>
90-
```
165+
If the token lacks these scopes, the plugin will fail with an error message prompting you to refresh your authentication.
91166
92-
You can also specify custom environment variable name for the GitHub CLI authentication token. Defaults `GITHUB_TOKEN`.
167+
### Repository that’s registered:
93168
94-
```properties
95-
# gradle.properties
169+
`https://maven.pkg.github.com/<org>/*` (name = `<org>`), with credentials automatically supplied by the selected token source.
96170
97-
gh.cli.auth.env.name=<environment-variable-name>
98-
```
171+
> [!NOTE]
172+
> Note on username: when the **CLI** path is used, the plugin extracts your GitHub login and uses it as the repository credential username; when **ENV/Gradle property** is used, the username is left empty.
173+
174+
## CI tips
99175
100-
**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.
101-
This is by design, to ensure that the plugin remains performant and skips unnecessary checks/steps during CI/CD runs.
176+
- **GitHub Actions**: the default `GITHUB_TOKEN` environment variable is already present → no extra config needed; just set `gh.cli.auth.github.org`.
177+
- **Local development**: Rely on the GitHub CLI route (make sure you’ve logged in with the correct scopes).
102178
103-
## Notes
179+
## Troubleshooting
104180
105-
Currently **not** supported:
181+
- **“Please set `gh.cli.auth.github.org` in gradle.properties.”**
182+
Add `gh.cli.auth.github.org=<your-org>` to `gradle.properties`.
106183
107-
- Dedicated GitHub Enterprise Servers or Hosts
108-
- Profile selection (the plugin uses the default from `gh`)
109-
- Only Maven repositories are supported (no Ivy or other types)
184+
- **“GitHub CLI token is missing required scopes …”**
185+
Run:
186+
187+
```bash
188+
gh auth refresh --scopes "read:packages,read:org"
189+
gh auth status
190+
```
191+
192+
- **Custom `gh` install not found**
193+
Point the plugin at your binary:
194+
195+
```
196+
./gradlew -Dgh.cli.binary.path=/absolute/path/to/gh <task>
197+
```
198+
199+
- **Using `RepositoriesMode.FAIL_ON_PROJECT_REPOS`**
200+
Prefer the **settings** plugin (the project plugin adds repositories at the project level and may conflict with this mode).
201+
202+
## Limitations
203+
204+
- Only **Maven** repositories are configured.
205+
- GitHub **Enterprise**/custom hosts and CLI **profile selection** are not supported; the CLI path expects `github.com` default auth.
110206
111207
## Contributing
112-
Contributions are welcome! Please read the contributing [guidelines](CONTRIBUTING.md).
208+
209+
PRs and issues are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
113210
114211
## License
212+
115213
This project is licensed under the AGPL-3.0 License - see the [LICENSE](LICENSE) for details.
214+
215+
___

0 commit comments

Comments
 (0)