Pulpogato is a java client for GitHub.
For releases, use mavenCentral.
https://repo.maven.apache.org/maven2/For snapshots, use this url.
https://central.sonatype.com/repository/maven-snapshots/The maven group id is io.github.pulpogato.
Most maven artifact ids are pulpogato-<api-type>-<gh-version>.
The api-type is one of graphql or rest.
The gh-version is one of ghec,fpt, or ghes-<GHES-version>.
To align versions across all Pulpogato modules, use io.github.pulpogato:pulpogato-bom.
Example in a gradle kotlin build script
// These properties can also be set in gradle.properties
ext {
set("netflixDgsVersion", "9.1.2")
set("ghVersion", "fpt")
set("pulpogatoVersion", "2.8.0")
}
val ghVersion: String by project.ext
val pulpogatoVersion: String by project.ext
val netflixDgsVersion: String by project.ext
dependencies {
implementation(platform("io.github.pulpogato:pulpogato-bom:${pulpogatoVersion}"))
// Use enforcedPlatform(...) instead of platform(...) for strict version enforcement.
implementation("io.github.pulpogato:pulpogato-rest-${ghVersion}")
implementation("io.github.pulpogato:pulpogato-graphql-${ghVersion}")
implementation("io.github.pulpogato:pulpogato-github-files")
implementation("org.springframework.boot:spring-boot-starter-webflux:4.0.2")
implementation("com.netflix.graphql.dgs:graphql-dgs-client:11.1.0")
implementation(platform("com.netflix.graphql.dgs:graphql-dgs-platform-dependencies:${netflixDgsVersion}"))
}| GitHub Version | GraphQL | REST |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Module | Version |
|---|---|
pulpogato-common Shared types used by both REST and GraphQL modules, such as common models and utilities. |
|
pulpogato-bom BOM to align versions across all Pulpogato modules. It is recommended to use this BOM in your build system to ensure all Pulpogato modules are on the same version. |
|
pulpogato-github-files Supports parsing Actions, Workflows, and Release configuration files. |
|
Install JDK 21 first.
To build, run ./gradlew build.
If you have low memory or CPU, you can customize parallelism with --max-workers.
When the REST schema contains examples, they are automatically converted to tests in the generated test sources directory.
To contribute a test for the REST API or GraphQL API:
-
Write a test like the ones in
UserApiIntegrationTest. -
Then set up the environment variable
GITHUB_TOKEN. -
If you’re running a test against a GitHub Enterprise instance, set up
GITHUB_HOSTandGITHUB_PORTas well. -
Run a command like
./gradlew :pulpogato-rest-fpt:test --tests AppsApiIntegrationTest.GITHUB_TOKEN=$(gh auth token) \ ./gradlew :pulpogato-rest-fpt:test --tests AppsApiIntegrationTestOr if you’re using GHES:
GITHUB_TOKEN=$(gh auth token) GITHUB_HOST=ghes.example.com GITHUB_PORT=8443 \ ./gradlew :pulpogato-rest-ghes-3.17:test --tests AppsApiIntegrationTest -
That generates a yaml file in
src/test/resources. If it needs cleaning up for sensitive data, do so.
To contribute a Webhook test:
-
Capture the HTTP request from the webhook using any tool. If you’re looking at public data, something like RequestBin is useful.
-
Clean up the data and place it in
pulpogato-rest-tests/src/main/resources/webhooks/under the right directory based on thex-github-eventheader. -
Verify the tests work.
GitHub’s OpenAPI schema may sometimes be incomplete or missing properties that exist in the actual API responses.
Pulpogato supports extending OpenAPI documents through *.schema.json files.
Schema additions are loaded from two locations:
-
pulpogato-common/src/main/resources/- additions that apply to all REST modules -
pulpogato-rest-<version>/src/main/resources/- additions specific to a single version
The files follow the OpenAPI 3.1.0 format and are merged additively with optional deletion markers:
-
components.schemasentries can add new schemas or new properties to existing schemas. -
pathsentries can add missing endpoint details (for example additional response media types). -
Setting any override node to
nulldeletes the corresponding node from the base schema.
Example: user.suspendedAt.schema.json
{
"openapi": "3.1.0",
"info": {
"title": "Additions Schema",
"version": "1.0.0"
},
"components": {
"schemas": {
"public-user": {
"properties": {
"suspended_at": {
"type": ["string", "null"],
"format": "date-time",
"description": "https://github.com/github/rest-api-description/issues/5667"
}
}
}
}
},
"paths": {}
}This adds the suspended_at property to the public-user schema.
The property will be available as suspendedAt in the generated Java code.