{"id":18753011,"url":"https://github.com/spotify/github-java-client","last_synced_at":"2025-12-11T18:35:36.499Z","repository":{"id":37279588,"uuid":"254401089","full_name":"spotify/github-java-client","owner":"spotify","description":"A Java client to Github API","archived":false,"fork":false,"pushed_at":"2025-04-28T10:24:29.000Z","size":3102,"stargazers_count":144,"open_issues_count":20,"forks_count":92,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-04-28T11:29:17.565Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spotify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-04-09T14:55:56.000Z","updated_at":"2025-04-10T11:37:24.000Z","dependencies_parsed_at":"2024-03-18T15:06:41.823Z","dependency_job_id":"218eeeca-0966-49f1-b542-5150e41c42af","html_url":"https://github.com/spotify/github-java-client","commit_stats":null,"previous_names":[],"tags_count":105,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spotify%2Fgithub-java-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spotify%2Fgithub-java-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spotify%2Fgithub-java-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spotify%2Fgithub-java-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spotify","download_url":"https://codeload.github.com/spotify/github-java-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493378,"owners_count":22080126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T17:23:46.516Z","updated_at":"2025-12-11T18:35:36.492Z","avatar_url":"https://github.com/spotify.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"![release pipeline](https://github.com/spotify/github-java-client/actions/workflows/release.yml/badge.svg)\n[![codecov](https://codecov.io/gh/spotify/github-java-client/branch/master/graph/badge.svg?token=ADHNCIESSL)](https://codecov.io/gh/spotify/github-java-client)[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n![lifecycle: beta](https://img.shields.io/badge/lifecycle-beta-509bf5.svg)\n[![Maven Central](https://img.shields.io/maven-central/v/com.spotify/github-client)](https://mvnrepository.com/artifact/com.spotify/github-client)\n\n# github-java-client\n\nA small Java library for talking to GitHub/GitHub Enterprise and interacting with projects.\n\nIt supports authentication via simple access tokens, JWT endpoints and GitHub Apps (via private key).\n\nIt is also very light on GitHub, doing as few requests as necessary.\n\nThis library is maintained by @spotify/gjc-maintainers. If you have any questions, issues or need a\nreview, please tag this team in the relevant PR/issue.\n\n## Getting Started\n\nYou can find this library in [maven central repository](https://mvnrepository.com/artifact/com.spotify/github-client).\n\nInclude the latest version of github-client into your project:\n\nIn Maven:\n\n```xml\n\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.spotify\u003c/groupId\u003e\n    \u003cartifactId\u003egithub-client\u003c/artifactId\u003e\n    \u003cversion\u003eversion\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Authenticating\n\n### Simple access token\n\n```java\nfinal GitHubClient githubClient = GitHubClient.create(URI.create(\"https://api.github.com/\"), \"my-access-token\");\n```\n\n### Private key\n\nTo authenticate as a GitHub App, you must provide a private key and the App ID, together with the API URL.\n\n```java\nfinal GitHubClient githubClient =\n        GitHubClient.create(\n                URI.create(\"https://api.github.com/\"),\n                new File(\"/path-to-the/private-key.pem\"),\n                APP_ID);\n```\n\nThen, you can scope the client for a specific Installation ID, to do the operations at the installation level.\nThe client will manage the generation of JWT tokens, as well as requesting and caching the installation tokens\nfrom GitHub.\n\n```java\nfinal GitHubClient scopedClient = GitHubClient.scopeForInstallationId(githubClient, INSTALLATION_ID);\n```\n\nIt is also possible to provide the installation to the root client.\n\nRefer\nto [GitHub App Authentication Guide](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/)\nfor more information.\n\n## Usage\n\nThis library attempts to mirror the structure of GitHub API endpoints. As an example, to get details of a Commit, there\nis\nthe `GET /repos/:owner/:repo/commits` API call, under the `repos` API. Therefore, the `getCommit` method lives in the\nRepositoryClient.\n\n```java\nfinal RepositoryClient repositoryClient = githubClient.createRepositoryClient(\"my-org\", \"my-repo\");\nlog.info(repositoryClient.getCommit(\"sha\").get().htmlUrl());\n```\n\nAnother example of the mirrored structure is that some of the APIs are nested under a parent API.\nFor example, endpoints related to check runs or issues are nested under the Repository client:\n\n```java\nfinal ChecksClient checksClient = repositoryClient.createChecksApiClient();\nchecksClient.createCheckRun(CHECK_RUN_REQUEST);\n\nfinal IssueClient issueClient = repositoryClient.createIssueClient();\nissueClient\n        .createComment(ISSUE_ID, \"comment body\")\n        .thenAccept(comment -\u003elog.info(\"created comment \"+comment.htmlUrl()));\n\n``` \n\nAnd endpoints related to teams and memberships are nested under the Organisation client:\n\n```java\nfinal TeamClient teamClient = organisationClient.createTeamClient();\nteamClient.getMembership(\"username\");\n```\n\n## Tracing\n\nThe GitHub client supports tracing via both OpenCensus and OpenTelemetry. Since OpenCensus is deprecated, we recommend\nusing OpenTelemetry. Using OpenTelemetry also enables context propagation when using this library.  \nTo enable tracing, you need to provide a tracer when initializing the client.\n\n### OpenTelemetry\n\n```java\nimport com.spotify.github.tracing.opentelemetry.OpenTelemetryTracer;\n\nfinal GitHubClient githubClient =\n        GitHubClient.create(baseUri, accessToken)\n                // Uses GlobalOpenTelemetry.get() to fetch the default tracer\n                .withTracer(new OpenTelemetryTracer());\n```\n\nYou can also provide a custom `OpenTelemetry` object if you want to use a specific one.\n\n```java\nimport com.spotify.github.tracing.opentelemetry.OpenTelemetryTracer;\n\nfinal GitHubClient githubClient =\n        GitHubClient.create(baseUri, accessToken)\n                // Uses custom openTelemetry object to fetch the tracer\n                .withTracer(new OpenTelemetryTracer(openTelemetry));\n```\n\n### OpenCensus\n\n```java\nimport com.spotify.github.tracing.opencensus.OpenCensusTracer;\n\nfinal GitHubClient githubClient =\n        GitHubClient.create(baseUri, accessToken)\n                // Uses Tracing.getTracer() to fetch the default tracer\n                .withTracer(new OpenCensusTracer());\n```\n\n## Supported Java versions\n\nThis library is written and published with Java version 11. In our CI workflows, we execute\nautomated tests with the Java LTS versions 11, 17 and 21. Due to Java's backward compatibility,\nthis library can definitely be used in all the tested versions.\n\n## Contributing\n\nThis project uses Maven. To run the tests locally, just run:\n\n```bash\nmvn clean verify\n```\n\n### Maintainers\n\n#### Publishing a new version\n\nIf you are a maintainer, you can release a new version by just triggering the workflow\n[prepare-release](./.github/workflows/prepare-release.yml) through the\n[web UI](https://github.com/spotify/github-java-client/actions/workflows/prepare-release.yml).\n\n- Select whether the new release should be a `major`, `minor` or `patch` release\n- Trigger the release preparation on the `master` branch\n- Pushes of this workflow will trigger runs of the\n  [maven-release](https://github.com/spotify/github-java-client/actions/workflows/release.yml)\n  workflow, which in turn will trigger the\n  [github-release](https://github.com/spotify/github-java-client/actions/workflows/release-on-github.yml)\n  workflow with the automatically created tag\n\nThe `prepare-release` workflow will also update the snapshot version in the `pom.xml` file to the next version. The\nversion which will be published to Maven Central will be the one specified in the `pom.xml` file (without the\n`-SNAPSHOT` suffix).\n\n#### Updating the GPG signing key\n\nIf you need to update the GPG signing key used for signing the releases when the existing key expires, you can do so by\nfollowing these steps:\n\n1. Generate a new GPG key pair or use an existing one.\n   If you don't have a GPG key pair, you can generate one using the following command:\n    ```bash\n    gpg --full-generate-key\n    ```\n   Follow the prompts to create your key pair. Make sure to remember the passphrase you set.\n2. List your GPG keys to find the key ID:\n   ```bash\n   gpg --list-keys\n   ```\n   Look for the `pub` line, which will show the key ID in the format `XXXXXXXX`.\n3. Export the public key to a file:\n   ```bash\n   gpg --armor --export \u003cKEY_ID\u003e \u003e publickey.asc\n    ```\n4. export the private key to a file:\n   ```bash\n   gpg --armor --export-secret-key \u003cKEY_ID\u003e \u003e privatekey.asc\n    ```\n5. Upload the private key to the GitHub repository secrets in `GPG_PRIVATE_KEY` and paste the contents of\n   `privatekey.asc`.\n6. Update the passphrase in the `GPG_PASSPHRASE` secret with the passphrase you set when generating the key.\n7. Upload the public key to the OpenGpg key server at https://keys.openpgp.org/\n8. Make sure to verify the public key with your email address on OpenGPG and that it is available on the key server.\n9. Make sure that the release workflow is configured to use the `GPG_PRIVATE_KEY` and `GPG_PASSPHRASE` secrets.\n10. Run the release workflow to publish a new version of the library.\n\n## Notes about maturity\n\nThis module was created after existing libraries were evaluated and dismissed, and we found that we were writing similar\ncode in multiple projects. As such, it at least initially only contains enough functionality for our internal\nrequirements\nwhich reflects that we were working on build system integration with the GitHub pull requests. It has been widely used\nfor 4+\nyears. It's important to notice that it does not cover all GitHub v3 API. Adding missing endpoints should be very\nstraightforward.\nPull Requests are welcome.\n\n## Code of conduct\n\nThis project adheres to the [Open Code of Conduct][code-of-conduct]. By participating, you are expected to honor this\ncode.\n\n[code-of-conduct]: https://github.com/spotify/code-of-conduct/blob/master/code-of-conduct.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspotify%2Fgithub-java-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspotify%2Fgithub-java-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspotify%2Fgithub-java-client/lists"}