Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs: Update the docs about GPG keys #249

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 28, 2025
Merged

docs: Update the docs about GPG keys #249

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 71 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,13 @@ You can find this library in [maven central repository](https://mvnrepository.co
Include the latest version of github-client into your project:

In Maven:

```xml

<dependency>
<groupId>com.spotify</groupId>
<artifactId>github-client</artifactId>
<version>version</version>
<groupId>com.spotify</groupId>
<artifactId>github-client</artifactId>
<version>version</version>
</dependency>
```

Expand All @@ -43,10 +45,10 @@ To authenticate as a GitHub App, you must provide a private key and the App ID,

```java
final GitHubClient githubClient =
GitHubClient.create(
URI.create("https://api.github.com/"),
new File("/path-to-the/private-key.pem"),
APP_ID);
GitHubClient.create(
URI.create("https://api.github.com/"),
new File("/path-to-the/private-key.pem"),
APP_ID);
```

Then, you can scope the client for a specific Installation ID, to do the operations at the installation level.
Expand All @@ -59,12 +61,16 @@ final GitHubClient scopedClient = GitHubClient.scopeForInstallationId(githubClie

It is also possible to provide the installation to the root client.

Refer to [GitHub App Authentication Guide](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/) for more information.
Refer
to [GitHub App Authentication Guide](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/)
for more information.

## Usage

This library attempts to mirror the structure of GitHub API endpoints. As an example, to get details of a Commit, there is
the `GET /repos/:owner/:repo/commits` API call, under the `repos` API. Therefore, the `getCommit` method lives in the RepositoryClient.
This library attempts to mirror the structure of GitHub API endpoints. As an example, to get details of a Commit, there
is
the `GET /repos/:owner/:repo/commits` API call, under the `repos` API. Therefore, the `getCommit` method lives in the
RepositoryClient.

```java
final RepositoryClient repositoryClient = githubClient.createRepositoryClient("my-org", "my-repo");
Expand All @@ -79,16 +85,17 @@ final ChecksClient checksClient = repositoryClient.createChecksApiClient();
checksClient.createCheckRun(CHECK_RUN_REQUEST);

final IssueClient issueClient = repositoryClient.createIssueClient();
issueClient.createComment(ISSUE_ID, "comment body")
.thenAccept(comment -> log.info("created comment " + comment.htmlUrl()));
issueClient
.createComment(ISSUE_ID, "comment body")
.thenAccept(comment ->log.info("created comment "+comment.htmlUrl()));

```

And endpoints related to teams and memberships are nested under the Organisation client:

```java
final TeamClient teamClient = organisationClient.createTeamClient();
teamClient.getMembership("username");
teamClient.getMembership("username");
```

## Tracing
Expand Down Expand Up @@ -144,8 +151,12 @@ This project uses Maven. To run the tests locally, just run:
mvn clean verify
```

If you are a maintainer, you can release a new version by just triggering the workflow
[prepare-release](./.github/workflows/prepare-release.yml) through the
### Maintainers

#### Publishing a new version

If you are a maintainer, you can release a new version by just triggering the workflow
[prepare-release](./.github/workflows/prepare-release.yml) through the
[web UI](https://github.com/spotify/github-java-client/actions/workflows/prepare-release.yml).

- Select whether the new release should be a `major`, `minor` or `patch` release
Expand All @@ -156,15 +167,56 @@ If you are a maintainer, you can release a new version by just triggering the wo
[github-release](https://github.com/spotify/github-java-client/actions/workflows/release-on-github.yml)
workflow with the automatically created tag

The `prepare-release` workflow will also update the snapshot version in the `pom.xml` file to the next version. The
version which will be published to Maven Central will be the one specified in the `pom.xml` file (without the
`-SNAPSHOT` suffix).

#### Updating the GPG signing key

If you need to update the GPG signing key used for signing the releases when the existing key expires, you can do so by
following these steps:

1. Generate a new GPG key pair or use an existing one.
If you don't have a GPG key pair, you can generate one using the following command:
```bash
gpg --full-generate-key
```
Follow the prompts to create your key pair. Make sure to remember the passphrase you set.
2. List your GPG keys to find the key ID:
```bash
gpg --list-keys
```
Look for the `pub` line, which will show the key ID in the format `XXXXXXXX`.
3. Export the public key to a file:
```bash
gpg --armor --export <KEY_ID> > publickey.asc
```
4. export the private key to a file:
```bash
gpg --armor --export-secret-key <KEY_ID> > privatekey.asc
```
5. Upload the private key to the GitHub repository secrets in `GPG_PRIVATE_KEY` and paste the contents of
`privatekey.asc`.
6. Update the passphrase in the `GPG_PASSPHRASE` secret with the passphrase you set when generating the key.
7. Upload the public key to the OpenGpg key server at https://keys.openpgp.org/
8. Make sure to verify the public key with your email address on OpenGPG and that it is available on the key server.
9. Make sure that the release workflow is configured to use the `GPG_PRIVATE_KEY` and `GPG_PASSPHRASE` secrets.
10. Run the release workflow to publish a new version of the library.

## Notes about maturity

This module was created after existing libraries were evaluated and dismissed, and we found that we were writing similar
code in multiple projects. As such, it at least initially only contains enough functionality for our internal requirements
which reflects that we were working on build system integration with the GitHub pull requests. It has been widely used for 4+
years. It's important to notice that it does not cover all GitHub v3 API. Adding missing endpoints should be very straightforward.
code in multiple projects. As such, it at least initially only contains enough functionality for our internal
requirements
which reflects that we were working on build system integration with the GitHub pull requests. It has been widely used
for 4+
years. It's important to notice that it does not cover all GitHub v3 API. Adding missing endpoints should be very
straightforward.
Pull Requests are welcome.

## Code of conduct
This project adheres to the [Open Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code.

This project adheres to the [Open Code of Conduct][code-of-conduct]. By participating, you are expected to honor this
code.

[code-of-conduct]: https://github.com/spotify/code-of-conduct/blob/master/code-of-conduct.md