Pulpogato is a java client for GitHub. Pulpogato is Spanish for Octopus-Cat.
For releases, you can use Maven Central, GitHub Packages, or JitPack.
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 the artifact pulpogato-bom.
Look at the demo project for a working example.
This would be the URL for GitHub Packages.
https://maven.pkg.github.com/pulpogato/pulpogatoThis would be the URL for Jitpack.
https://jitpack.io/Jitpack uses a different groupId for the artifact, though.
Instead of io.github.pulpogato, you would use com.github.pulpogato.pulpogato.
Also, prefix the version with v, for example v3.2.0 instead of 3.2.0.
For snapshots, use this url.
https://central.sonatype.com/repository/maven-snapshots/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")
}
repositories {
mavenCentral()
}
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 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
EOL Versions
| 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.
Laptop and PR builds are tuned for speed, so two pieces of optional work are off by default.
-Pcodegen.format=true runs Palantir Java Format over the generated sources.
Formatting is cosmetic and only affects the readability of the published sources jar, so it is skipped by default and saves roughly 13-15 seconds per REST module.
CI turns it on automatically when building snapshot, candidate, and final artifacts.
-Pcoverage=true enables JaCoCo.
Coverage collection and its report are a CI/reporting concern, so they stay off the default critical path.
Tests run in parallel across forked JVMs (maxParallelForks), which the data-driven generated tests benefit from the most.
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.
![renovate[bot]](https://avatars.githubusercontent.com/u/29139614?size=120)
![github-actions[bot]](https://avatars.githubusercontent.com/u/41898282?size=120)
![google-labs-jules[bot]](https://avatars.githubusercontent.com/u/161369871?size=120)
![dependabot[bot]](https://avatars.githubusercontent.com/u/49699333?size=120)
