GitForge

GitForge.jl is a unified interface for interacting with Git "forges".

GitForge.Forge — Type

A forge is an online platform for Git repositories. The most common example is GitHub.

Forge subtypes can access their respective web APIs.

Supported Forges

GitHub

GitForge.GitHub.GitHubAPI — Type

GitHubAPI(;
    token::AbstractToken=NoToken(),
    url::AbstractString="https://api.github.com",
    has_rate_limits::Bool=true,
    on_rate_limit::OnRateLimit=ORL_THROW,
)

Create a GitHub API client.

Keywords

token::AbstractToken=NoToken(): Authorization token (or lack thereof).
url::AbstractString="https://api.github.com": Base URL of the target GitHub instance.
has_rate_limits::Bool=true: Whether or not the GitHub server has rate limits.
on_rate_limit::OnRateLimit=ORL_THROW: Behaviour on exceeded rate limits.

source

GitForge.GitHub.NoToken — Type

NoToken()

Represents no authentication. Only public data will be available.

source

GitForge.GitHub.Token — Type

Token(token::AbstractString)

An OAuth2 token, or a personal access token.

source

GitForge.GitHub.JWT — Type

JWT(token::AbstractString)

A JWT signed by a private key for GitHub Apps.

source

API

Each API function (get_user, get_repo, etc.) returns a Tuple{T, HTTP.Response}. The value of T depends on what function you've called. For example, get_user will generally return some User type for your forge.

When things go wrong, exceptions are thrown. They will always be one of the following types:

GitForge.ForgeError — Type

The supertype of all other exceptions raised by API functions.

source

GitForge.HTTPError — Type

An error encountered during the HTTP request.

Fields

response::Union{HTTP.Response, Nothing}: Set for status exceptions.
exception::Exception
stacktrace::StackTrace

source

GitForge.PostProcessorError — Type

An error encountered during response postprocessing.

Fields

response::HTTP.Response
exception::Exception
stacktrace::StackTrace

source

GitForge.RateLimitedError — Type

A signal that a rate limit has been exceeded.

Fields

period::Union{Period, Nothing} Amount of time until rate limit expiry, if known.

source

GitForge.@paginate — Macro

@paginate fun(args...; kwargs...) page=1 per_page=100 -> Paginator

Create an iterator that paginates the results of repeatedly calling fun(args...; kwargs...). The first argument of fun must be a Forge and it must return a Tuple{Vector{T}, HTTP.Response}.

Keywords

page::Int=1: Starting page.
per_page::Int=100: Number of entries per page.

source

Endpoints

These functions all allow any number of trailing keywords. For more information on these keywords, see request.

GitForge.get_user — Function

get_user(::Forge[, name_or_id::Union{AbstractString, Integer, UUID}])

Get the currently authenticated user, or a user by name or ID.

source

GitForge.get_users — Function

get_users(::Forge)

Get all users.

source

GitForge.update_user — Function

update_user(::Forge[, id::Union{Integer, UUID}]; kwargs...)

Update the currently authenticated user, or a user by ID.

source

GitForge.create_user — Function

create_user(::Forge; kwargs...)

Create a new user.

source

GitForge.delete_user — Function

delete_user(::Forge, id::Union{Integer, UUID})

Delete a user by ID.

source

GitForge.get_user_repos — Function

get_user_repos(::Forge[, name_or_id::Union{AbstractString, Integer, UUID}])

Get the currently authenticated user's repositories, or those of a user by name or ID.

source

GitForge.get_repo — Function

get_repo(::Forge, owner_repo::AbstractString)
get_repo(::Forge, owner::AbstractString, repo::AbstractString)
get_repo(::Forge, id::Integer)
get_repo(::Forge, id::UUID)
get_repo(::Forge, owner::AbstractString, subgroup::AbstractString, repo::AbstractString)

Get a repository by owner and name or ID.

source

GitForge.get_branch — Function

get_branch(::Forge, owner::AbstractString, repo::AbstractString, branch::AbstractString)

Get a branch from a repository.

source

GitForge.get_file_contents — Function

get_file_contents(
    ::Forge,
    owner::AbstractString,
    repo::AbstractString,
    path::AbstractString,
)
get_file_contents(f::Forge, id::Integer, path::AbstractString)

Get a file from a repository.

source

GitForge.get_pull_request — Function

get_pull_request(::Forge, owner::AbstractString, repo::AbstractString, number::Integer)
get_pull_request(::Forge, project::Integer, number::Integer)

Get a specific pull request.

source

GitForge.get_pull_requests — Function

get_pull_requests(::Forge, owner::AbstractString, repo::AbstractString)
get_pull_requests(::Forge, project::Integer)

List a repository's pull requests.

source

GitForge.create_pull_request — Function

create_pull_request(::Forge, owner::AbstractString, repo::AbstractString; kwargs...)
create_pull_request(::Forge, project::Integer; kwargs...)

Create a pull request.

source

GitForge.update_pull_request — Function

update_pull_request(::Forge, owner::AbstractString, repo::AbstractString, number::Integer; kwargs...)
update_pull_request(::Forge, project::Integer, number::Integer; kwargs...)

Update a pull request.

source

GitForge.get_commit — Function

get_commit(::Forge, owner::AbstractString, repo::AbstractString, ref::AbstractString)
get_commit(::Forge, project::Integer, ref::AbstractString)

Get a commit from a repository.

source

GitForge.get_tags — Function

get_tags(::Forge, owner::AbstractString, repo::AbstractString)
get_tags(::Forge, project::Integer)

Get a list of tags from a repository.

source

GitForge.is_collaborator — Function

is_collaborator(
    ::Forge,
    owner::AbstractString,
    repo::AbstractString,
    name_or_id::Union{AbstractString, Integer, UUID},
)

Check whether or not a user is a collaborator on a repository.

source

GitForge.is_member — Function

is_member(::Forge, org::AbstractString, name_or_id::Union{AbstractString, Integer, UUID})

Check whether or not a user is a member of an organization.

source

Internals

The following resources are useful for implementing new forges, or customizing behaviour.

Many functions take a Function argument, which can be used to limit the affected API functions. To make a method specific to a single function, use ::typeof(fun).

URLs

These functions set request URLs. To determine the full URL for a given request, they are concatenated together.

GitForge.base_url — Function

base_url(::Forge) -> String

Returns the base URL of all API endpoints.

source

GitForge.endpoint — Function

endpoint(::Forge, ::Function, args...) -> Endpoint

Returns an Endpoint for a given function. Trailing arguments are usually important for routing. For example, get_user can take some ID parameter which becomes part of the URL.

source

GitForge.Endpoint — Type

Endpoint(
    method::Symbol,
    url::AbstractString;
    headers::Vector{<:Pair}=HTTP.Header[],
    query::Dict=Dict(),
    allow_404::Bool=false,
) -> Endpoint

Contains information on how to call an endpoint.

Arguments

method::Symbol: HTTP request method to use.
url::AbstractString: Endpoint URL, relative to the base URL.

Keywords

headers::Vector{<:Pair}=HTTP.Header[]: Request headers to add.
query::Dict=Dict(): Query string parameters to add.
allow_404::Bool=false: Sends responses with 404 statuses to the postprocessor.

source

Request Options

These functions set parts of HTTP requests.

GitForge.request_headers — Function

request_headers(::Forge, ::Function) -> Vector{Pair}

Returns the headers that should be added to each request.

source

GitForge.request_query — Function

request_query(::Forge, ::Function) -> Dict

Returns the query string parameters that should be added to each request.

source

GitForge.request_kwargs — Function

request_kwargs(::Forge, ::Function) -> Dict{Symbol}

Returns the extra keyword arguments that should be passed to HTTP.request.

source

Requests

This function makes the actual HTTP requests.

GitForge.request — Function

request(
    f::Forge, fun::Function, ep::Endpoint;
    headers::Vector{<:Pair}=HTTP.Header[],
    query::AbstractDict=Dict(),
    request_opts=Dict(),
    kwargs...,
) -> T, HTTP.Response

Make an HTTP request and return T and the response, where T is determined by into.

Arguments

f::Forge A Forge subtype.
fun::Function: The API function being called.
ep::Endpoint: The endpoint information.

Keywords

query::AbstractDict=Dict(): Query string parameters to add to the request.
headers::Vector{<:Pair}=HTTP.Header[]: Headers to add to the request.
request_opts=Dict(): Keywords passed into HTTP.request.

Trailing keywords are sent as a JSON body for PATCH, POST, and PUT requests. For other request types, the keywords are sent as query string parameters.

Note

Every API function passes its keyword arguments into this function. Therefore, to customize behaviour for a single request, pass the above keywords to the API function.

source

Rate Limiting

These functions and types handle certain generic rate limiters.

GitForge.RateLimiter — Type

A generic rate limiter using the [X-]RateLimit-Remaining and [X-]RateLimit-Reset response headers. The reset header is assumed to be a Unix timestamp in seconds.

source

GitForge.OnRateLimit — Type

Determines how to react to an exceeded rate limit.

ORL_THROW: Throw a RateLimitedError.
ORL_WAIT: Block and wait for the rate limit to expire.

source

GitForge.has_rate_limits — Function

has_rate_limits(::Forge, ::Function) -> Bool

Returns whether or not the forge server uses rate limiting.

source

GitForge.rate_limit_check — Function

rate_limit_check(::Forge, ::Function) -> Bool

Returns whether or not there is an active rate limit. If one is found, on_rate_limit is called to determine how to react.

source

GitForge.on_rate_limit — Function

on_rate_limit(::Forge, ::Function) -> OnRateLimit

Returns an OnRateLimit that determines how to react to an exceeded rate limit.

source

GitForge.rate_limit_wait — Function

rate_limit_wait(::Forge, ::Function)

Wait for a rate limit to expire.

source

GitForge.rate_limit_period — Function

rate_limit_period(::Forge, ::Function) -> Period

Compute the amount of time until a rate limit expires.

source

GitForge.rate_limit_update! — Function

rate_limit_update!(::Forge, ::Function, ::HTTP.Response)

Update the rate limiter with a new response.

source

Post Processing

These functions and types process HTTP responses.

GitForge.postprocessor — Function

postprocessor(::Forge, ::Function) -> PostProcessor

Returns the PostProcessor to be used.

source

GitForge.into — Function

into(::Forge, ::Function) -> Type

Returns the type that the PostProcessor should create from the response.

source

GitForge.PostProcessor — Type

Determines the behaviour of postprocess.

source

GitForge.postprocess — Function

postprocess(::PostProcessor, ::HTTP.Response, ::Type{T})

Computes a value to be returned from an HTTP response.

source

GitForge.DoNothing — Type

Does nothing and always returns nothing.

source

GitForge.DoSomething — Type

DoSomething(::Function) -> DoSomething

Runs a user-defined postprocessor.

source

GitForge.JSON — Type

JSON(f::Function=identity) -> JSON

Parses a JSON response into a given type and runs f on that object.

source

GitForge.@json — Macro

@json struct T ... end
@json FORGETYPE struct T ... end

Create a type that can be parsed from JSON.

Optionally accept a forge type for struct names that do not follow the ModuleAPI convention

source