Skip to content

Commit 788cc1a

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

1 file changed

Lines changed: 170 additions & 71 deletions

File tree

‎README.md‎

Lines changed: 170 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,115 +1,214 @@
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+
[![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)
6+
[![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)
7+
8+
1. [Overview](#overview)
9+
2. [Features](#features)
10+
3. [Installation](#installation)
11+
- [A) Settings Plugin (Recommended)](#a-settings-plugin-recommended)
12+
- [B) Project Plugin (Per Project)](#b-project-plugin-per-project)
13+
4. [Usage](#usage)
14+
- [1) Required: Set Your GitHub Organization](#1-required-tell-the-plugin-which-organization-to-use)
15+
- [2) Choose How to Provide Credentials](#2-choose-how-you-want-to-provide-credentials)
16+
5. [Configuration Options](#configuration-options)
17+
- [Token Resolution Order](#token-resolution-order)
18+
- [GitHub CLI Scopes](#github-cli-scopes-cli-fallback)
19+
- [Repository Configuration](#repository-thats-registered)
20+
6. [CI Tips](#ci-tips)
21+
7. [Troubleshooting](#troubleshooting)
22+
8. [Limitations](#limitations)
23+
9. [Contributing](#contributing)
24+
10. [License](#license)
25+
26+
## Overview
27+
28+
**Zero‑boilerplate access to GitHub Packages (Maven) for your organization.**
29+
30+
This plugin family configures the GitHub Packages Maven repository for your org and provides credentials automatically from one of three sources (in order):
31+
32+
1. **Environment variable** (name configurable, default `GITHUB_TOKEN`)
33+
2. **Gradle property** (key configurable, default `gpr.token`)
34+
3. **GitHub CLI**: parses `gh auth status --show-token` (requires `read:packages, read:org`)
35+
36+
> [!NOTE]
37+
> 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.
38+
39+
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).
40+
41+
## Features
42+
43+
- Registers your authenticated GitHub Packages Maven repository for your organization automatically.
44+
- Complete backwards compatibility with existing environment-based and Gradle property-based token provisioning.
45+
- Ensures common “trusted” repos are present at settings level (added *only if missing*) such as Maven Central and Gradle Plugin Portal.
46+
- Most importantly, No need to rely on hardcoded tokens local configs anymore, just use the GitHub CLI for local dev!
747

8-
## Prerequisites
48+
## Installation
949

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

12-
```bash
13-
gh auth login --scopes "read:packages,read:org"
52+
> [!TIP]
53+
> **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`.
54+
55+
### A) Settings plugin (recommended)
56+
57+
**Kotlin DSL – `settings.gradle.kts`**
58+
59+
```kotlin
60+
plugins {
61+
id("io.github.adelinosousa.gradle.plugins.settings.gh-cli-auth") version "2.0.0"
62+
}
63+
```
64+
65+
**Groovy DSL – `settings.gradle`**
66+
67+
```groovy
68+
plugins {
69+
id 'io.github.adelinosousa.gradle.plugins.settings.gh-cli-auth' version '2.0.0'
70+
}
1471
```
1572

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

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

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

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

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

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

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

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

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-
}
113+
### 2) Choose how you want to provide credentials
43114

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:
115+
You can do nothing (and rely on the GitHub CLI path below), or pick one of these:
50116

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-
```
117+
- **Environment variable** (fastest for CI):
118+
- Leave default: export `GITHUB_TOKEN`
119+
- Or choose a name: set `gh.cli.auth.env.name` in `gradle.properties` and export that variable.
56120

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

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

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

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

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

71-
```shell
72-
# build.gradle
140+
| Key / Surface | Where to set/read | Default | Purpose |
141+
|-------------------------------------|-------------------------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------|
142+
| `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>/*`). |
143+
| `gh.cli.auth.env.name` | `gradle.properties` | `GITHUB_TOKEN` | Name of the environment variable the plugin checks **first** for the token. |
144+
| `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). |
145+
| `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. |
146+
| `ghCliAuth.token` | **read** in `build.gradle(.kts)` | n/a | Token exposed by the **project** plugin’s extension. |
147+
| `-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). |
73148

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

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.
151+
```
152+
ENV (name = gh.cli.auth.env.name, default GITHUB_TOKEN)
153+
└── if unset/empty → GRADLE PROPERTY (key = gh.cli.auth.property.name, default gpr.token)
154+
└── if unset/empty → GitHub CLI: gh auth status --show-token
155+
```
81156
82-
### Configuration
157+
### GitHub CLI scopes (CLI fallback):
83158
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:
159+
Below is the required scopes for the token retrieved via the GitHub CLI:
85160
86-
```properties
87-
# gradle.properties
161+
- `read:packages`
162+
- `read:org`
88163
89-
gh.cli.auth.github.org=<your-organization>
90-
```
164+
If the token lacks these scopes, the plugin will fail with an error message prompting you to refresh your authentication.
91165
92-
You can also specify custom environment variable name for the GitHub CLI authentication token. Defaults `GITHUB_TOKEN`.
166+
### Repository that’s registered:
93167
94-
```properties
95-
# gradle.properties
168+
`https://maven.pkg.github.com/<org>/*` (name = `<org>`), with credentials automatically supplied by the selected token source.
96169
97-
gh.cli.auth.env.name=<environment-variable-name>
98-
```
170+
> [!NOTE]
171+
> 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.
172+
173+
## CI tips
99174
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.
175+
- **GitHub Actions**: the default `GITHUB_TOKEN` environment variable is already present → no extra config needed; just set `gh.cli.auth.github.org`.
176+
- **Local development**: Rely on the GitHub CLI route (make sure you’ve logged in with the correct scopes).
102177
103-
## Notes
178+
## Troubleshooting
104179
105-
Currently **not** supported:
180+
- **“Please set `gh.cli.auth.github.org` in gradle.properties.”**
181+
Add `gh.cli.auth.github.org=<your-org>` to `gradle.properties`.
106182
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)
183+
- **“GitHub CLI token is missing required scopes …”**
184+
Run:
185+
186+
```bash
187+
gh auth refresh --scopes "read:packages,read:org"
188+
gh auth status
189+
```
190+
191+
- **Custom `gh` install not found**
192+
Point the plugin at your binary:
193+
194+
```
195+
./gradlew -Dgh.cli.binary.path=/absolute/path/to/gh <task>
196+
```
197+
198+
- **Using `RepositoriesMode.FAIL_ON_PROJECT_REPOS`**
199+
Prefer the **settings** plugin (the project plugin adds repositories at the project level and may conflict with this mode).
200+
201+
## Limitations
202+
203+
- Only **Maven** repositories are configured.
204+
- GitHub **Enterprise**/custom hosts and CLI **profile selection** are not supported; the CLI path expects `github.com` default auth.
110205
111206
## Contributing
112-
Contributions are welcome! Please read the contributing [guidelines](CONTRIBUTING.md).
207+
208+
PRs and issues are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
113209
114210
## License
211+
115212
This project is licensed under the AGPL-3.0 License - see the [LICENSE](LICENSE) for details.
213+
214+
___

0 commit comments

Comments
 (0)