README
¶
forge-dashboard-sdk-go
A Go client for forge-dashboard's REST API, generated from its OpenAPI spec with oapi-codegen. It saves you from hand-rolling HTTP requests, retries and pagination against the API yourself.
Requirements
- Go 1.27 or later.
- A running forge-dashboard instance.
- A personal API token for that instance (see "Authentication" below) —
every endpoint except
/healthzand/api/versionneeds one.
Installation
go get github.com/alrayyes/forge-dashboard-sdk-go@latest
Pin an exact tagged version (@v0.1.0) once one exists, rather than tracking
@latest in anything but a quick trial.
Authentication
forge-dashboard authenticates browsers with passkeys (WebAuthn) and a
session cookie, but its spec documents a real headless alternative: a
personal API token, generated from the dashboard's own Settings page
(POST /api/tokens, signed in as yourself first) and sent as
Authorization: Bearer <token> on every request after. Pass it to New
or set FORGE_DASHBOARD_TOKEN:
client, err := forgedashboard.New("https://dashboard.example.com",
forgedashboard.WithToken(os.Getenv("FORGE_DASHBOARD_TOKEN")),
)
A token is revocable from Settings at any point; there's nothing in this SDK to refresh one automatically once it's gone.
Usage
GetVersion needs no token and is a good first call to prove the client
reaches the server at all:
package main
import (
"context"
"fmt"
"log"
forgedashboard "github.com/alrayyes/forge-dashboard-sdk-go"
)
func main() {
client, err := forgedashboard.New("https://dashboard.example.com")
if err != nil {
log.Fatal(err)
}
resp, err := client.GetVersionWithResponse(context.Background())
if err != nil {
log.Fatal(err)
}
fmt.Println("server version:", resp.JSON200.Version)
}
Fetching your own dashboard needs a token:
client, err := forgedashboard.New(
"https://dashboard.example.com",
forgedashboard.WithToken(os.Getenv("FORGE_DASHBOARD_TOKEN")),
)
if err != nil {
log.Fatal(err)
}
resp, err := client.GetDashboardWithResponse(context.Background(), nil)
if err != nil {
log.Fatal(err) // transport failure -- already retried
}
if apiErr := forgedashboard.DecodeError(resp.HTTPResponse.StatusCode, resp.Body); apiErr != nil {
log.Fatal(apiErr)
}
for _, pr := range resp.JSON200.PullRequests {
fmt.Printf("%s#%d: %s (%s)\n", pr.Repo, pr.Number, pr.Title, pr.Ci)
}
Every other operation follows the generated ClientWithResponses pattern —
client.<Operation>WithResponse(ctx, ...) returns a typed response whose
JSON200/JSON4xx fields hold the decoded body. DecodeError turns a
failed response into a *forgedashboard.APIError uniformly, as shown above.
The client retries a 429 or 5xx response with exponential backoff and
jitter (honoring a server-sent Retry-After), and never retries any other
4xx. Tune it with WithRetry, or swap the underlying *http.Client
entirely with WithHTTPClient.
Reports
Each green push to main publishes its test and coverage reports at
apis.ryankes.eu/forge-dashboard-sdk-go/reports/:
JUnit XML under tests/, and the HTML view, Cobertura XML and Go profile
under coverage/.
Regenerating the client
See CONTRIBUTING.md — the generated code is pinned to a specific forge-dashboard commit and shouldn't drift from it silently.
Contributing
See CONTRIBUTING.md for building, testing and the release process.
License
MIT — a permissive license for the client, independent of forge-dashboard's own AGPL-3.0.
Documentation
¶
Overview ¶
Package forgedashboard is a client for the forge-dashboard REST API (github.com/alrayyes/forge-dashboard).
Authenticate with a personal API token, generated from the dashboard's own Settings page (POST /api/tokens) -- the alternative forge-dashboard's spec documents to its browser session cookie, and the one this SDK actually uses, since a headless client has no WebAuthn ceremony to run. Pass the token to New or set FORGE_DASHBOARD_TOKEN.
Package forgedashboard is the official Go SDK for forge-dashboard.
Index ¶
Constants ¶
const TokenEnvVar = "FORGE_DASHBOARD_TOKEN"
TokenEnvVar is the environment variable New falls back to when no token is passed explicitly via WithToken.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type APIError ¶
APIError is returned by DecodeError for any forge-dashboard response carrying an error body -- every 4xx/5xx in the spec shares the same {error} shape (components.schemas.Error).
func DecodeError ¶
DecodeError builds an *APIError from a generated response's status and body, or returns nil when statusCode isn't an error. Every operation's generated response type carries these two fields under the same names (StatusCode via HTTPResponse, and Body), so this one helper covers all of them:
resp, err := client.GetDashboardWithResponse(ctx, nil)
if err != nil {
return err // transport failure, already retried
}
if apiErr := forgedashboard.DecodeError(resp.HTTPResponse.StatusCode, resp.Body); apiErr != nil {
return apiErr
}
type Client ¶
type Client struct {
*genclient.ClientWithResponses
}
Client is a forge-dashboard API client. Construct one with New.
type Option ¶
type Option func(*config)
Option configures a Client constructed by New.
func WithHTTPClient ¶
func WithHTTPClient(hc genclient.HttpRequestDoer) Option
WithHTTPClient replaces the underlying HTTP client. The retry transport (WithRetry) wraps whatever Transport this client has set, so pass a client with a custom Transport already configured (proxies, mTLS, ...) rather than replacing RoundTrip yourself afterward.
Source Files
Directories