class GitHubAppCredential extends Object
Provides GitHub App Credential for API authentication.
import net.gleske.jervis.remotes.creds.EphemeralTokenCache
import net.gleske.jervis.remotes.creds.GitHubAppCredential
import net.gleske.jervis.remotes.creds.GitHubAppRsaCredentialImpl
import java.time.Instant
// Configure the private key downloaded from GitHub App.
GitHubAppRsaCredentialImpl rsaCred = new GitHubAppRsaCredentialImpl('123456', new File('app-private-key.pem').text)
rsaCred.owner = 'gh-organization'
// Configure encrypted token storage
EphemeralTokenCache tokenCred = new EphemeralTokenCache('src/test/resources/rsa_keys/good_id_rsa_4096')
// a small timing function
Long time(Closure c) {
Instant before = Instant.now()
c()
Instant after = Instant.now()
after.epochSecond - before.epochSecond
}
// Issue a token; if called multiple times then this token will retrieve the
// token from the cache. It will issue a new token if the existing token
// expires.
println("Execution time: ${time { println('GitHub token: ' + new GitHubAppCredential(rsaCred, tokenCred).getToken()) }} second(s).")
println('Try again...')
println("Execution time: ${time { println('GitHub token: ' + new GitHubAppCredential(rsaCred, tokenCred).getToken()) }} second(s).")
println('\n' + ['='*80, 'Encrypted cache below', '='*80].join('\n') + '\n')
// Read the encrypted cache which is an encrypted YAML document.
println(new File(tokenCred.cacheFile).text)
Type | Name and description |
---|---|
static String |
DEFAULT_GITHUB_API The public hosted GitHub API URL. |
String |
github_api_url The URL which will be used for API requests to GitHub. |
Map |
headers Pre-defined headers to add to the request. |
String |
installation_id Optionally set an installation ID for a GitHub app. |
Boolean |
ownerIsUser Find app installation for user instead of organization. |
Map |
scope The scope a GitHub token should have when it is created. |
Constructor and description |
---|
GitHubAppCredential
(GitHubAppRsaCredential rsaCredential, EphemeralTokenCredential tokenCredential) Creates a new instance of a GitHubAppCredential meant to serve as an easy to use credential in API clients such as GitHubGraphQL and GitHub. |
Type Params | Return Type | Name and description |
---|---|---|
|
String |
baseUrl() Used for API access to issue tokens. |
|
String |
getHash() A hash of GitHubAppRsaCredential.getId and requested token scope. |
|
String |
getInstallation_id() If installation ID is not set, then it will automatically resolve an ID from app installations. |
|
String |
getToken() Get a valid GitHub App API token meant for cloning code or interacting with GitHub APIs. |
|
Map |
header(Map headers = [:]) Headers used for authentication. |
|
void |
setHash(String hash) This method will throw an exception because the hash calculation is dynamic and must not be set. |
|
void |
setRsaCredential(GitHubAppRsaCredential cred) Sets the RSA credential used for authentication. |
|
void |
setScope(Map scope) Sets the scope for issuing tokens. |
The public hosted GitHub API URL.
The URL which will be used for API requests to GitHub.
Pre-defined headers to add to the request.
Optionally set an installation ID for a GitHub app. Set this to avoid extra API calls. Querying for the app installation. This ID is used when issuing ephemeral GitHub API tokens.
Find app installation for user instead of organization.
The scope a GitHub token should have when it is created. By default, full GitHub app scope. Learn more about available scopes when creating a token for a GitHub app.
// Limit scope to readonly access to two repositories
github_app.scope = [repositories: ['repo1', 'repo2'], permissions: [contents: 'read']]
Creates a new instance of a GitHubAppCredential meant to serve as an easy to use credential in API clients such as GitHubGraphQL and GitHub.
rsaCredential
- Is an RSA private key with other GitHub app details
such as GitHub App ID and owner of an installation
which would be use to retrieve the
installation_id.tokenCredential
- This will be used to store ephemeral tokens issued
by the GitHub App. This parameter is provided as
a means to securely store the token in any
credential backend of choice. As opposed to
storing the token within this class instance.
This is necessary due Jenkins serialization of
data to disk in Jenkins pipelines. Refer to the
interface for a recommended example.Used for API access to issue tokens.
A hash of GitHubAppRsaCredential.getId and requested token scope.
If installation ID is not set, then it will automatically resolve an ID from app installations. Automatic resolution will be attempted from the list of app installations based on the owner. If owner is not set then the first item in the list of installations is selected.
Get a valid GitHub App API token meant for cloning code or interacting with GitHub APIs.
Headers used for authentication.
headers
- Custom headers can be provided and combined with default
and pre-defined headers.This method will throw an exception because the hash calculation is dynamic and must not be set.
hash
- An empty string or null is allowed to force hash
recalculation. Any other value will throw an exception.Sets the RSA credential used for authentication.
cred
- A GitHub App RSA key used to generate a JSON Web Token (JWT)
for issuing API credentials.Jervis API documentation.