Reference
Provider API
Every namespace on a provider, and the methods in each.
Every provider has the namespaces below. A method for an operation that the forge lacks rejects with UnsupportedOperationError. Check can() first.
Listings come in pairs. list() returns an async iterable, and listPage() returns one Page. The tables show the iterable name and leave out its Page twin. See Page through results.
Provider
| Member | Description |
|---|---|
kind, instance, baseUrl | The forge and deployment that the provider sends requests to |
capabilities | What the provider supports, computed without a request |
can(verb, kind?) | Whether an operation is supported |
refreshCapabilities() | Reads the instance version and updates capabilities |
scopesFor(verb) | The scopes or permissions an operation needs |
request() | A request with the provider's auth, for endpoints the model doesn't cover |
urlFor(target) | The web URL of a repo, thread, comment, release, file or comparison |
parseUrl(url) | Reads a web URL on this instance into refs |
referenceTo(ref, options?) | How to mention a thread in Markdown, such as #42 or !42 |
normaliseMarkdown(body) | Rewrites Markdown into the dialect the forge renders |
repos
| Method | Description |
|---|---|
get(ref) | One repository |
list(options?) | The account's repositories, or the installation's under app auth |
labels(repo), createLabel(repo, label) | Labels defined on a repository |
milestones(repo) | Milestones |
collaborators(repo), addCollaborator(repo, actor, role) | Collaborators |
permissionFor(repo, actor) | One account's role, or 'none' |
assignableUsers(repo) | Accounts that can be assigned |
reviewerCandidates(ref) | Accounts that can review a pull request |
threads
Reads:
| Method | Description |
|---|---|
get(ref), getMany(refs) | One thread, or several in a batch |
list(repo, query?) | Threads in a repository |
events(ref) | Events on a thread |
comments(ref) | Conversation comments |
reactions(target) | Reactions on a thread or a comment |
checks(ref) | Every check on a pull request's head |
reviews(ref) | Reviews on a pull request |
files(ref), commits(ref) | Files and commits of a pull request |
subscription(ref) | The account's subscription to a thread |
Writes:
| Method | Description |
|---|---|
create(repo, input), update(ref, input) | Create or edit an issue or pull request |
comment(ref, body), editComment(), deleteComment() | Comments |
upsertComment(ref, { key, body }) | Create a comment, or edit the one an earlier call left behind |
close(ref, options?), reopen(ref) | Thread state |
setLabels(), addLabels(), removeLabels() | Labels |
setMilestone(), setAssignees(), requestReview() | Planning |
react(), unreact() | Reactions |
merge(ref, options?), approveAndMerge(ref, options?) | Merge a pull request |
createReview(), submitReview(), approve() | Reviews |
resolveReviewThread(), unresolveReviewThread() | Review conversations |
transfer(), markDuplicate() | Move or deduplicate |
subscribe(), unsubscribe() | Change the account's subscription |
notifications
list(), markRead(), markDone(), unsubscribe(), markAllRead(), markAllDone() and unreadCount().
checks and ci
| Method | Description |
|---|---|
checks.list(repo, sha) | Every check on a commit |
checks.report(repo, sha, input) | Write a commit status, or a check run under GitHub App auth |
checks.rerun(ref) | Re-run a check |
ci.runs(repo, query?), ci.run(ref) | Workflow or pipeline runs |
ci.jobs(ref), ci.log(ref) | Jobs of a run, and a job's log as a stream |
CI is read-only. There is no workflow dispatch.
contents
| Method | Description |
|---|---|
file(repo, path, options?) | One file, as text or bytes |
tree(repo, options?) | A directory, or every descendant with recursive |
branches(repo), tags(repo) | Branches and tags |
resolveRef(repo, ref) | A branch, tag or sha as a full sha |
commits(repo, query?), commit(repo, sha) | History, and one commit with its files |
compare(repo, base, head) | Commits and files between two refs |
releases
list(), get(), getByTag(), latest() and downloadAsset(). latest() returns the most recent release that isn't a draft or prerelease.
webhooks
| Method | Description |
|---|---|
ingest(delivery) | Verify a delivery and translate it into events |
verify(delivery) | Check the signature only |
events | Kinds and actions this provider can deliver |
list(target), create(), update(), delete() | Manage registered hooks |
rotateSecret(ref, secret) | Replace a hook's signing secret |
deliveries(ref), redeliver(ref) | Read the delivery log, and send a delivery again |
search
threads(), repos() and commits() search across repositories. A filter that the forge can't apply comes back as a filter_unsupported warning.
Other namespaces
| Namespace | Description |
|---|---|
securityAlerts.list(repo, options?) | Dependency, code scanning and secret alerts |
installations | List app installations, mint tokens and get a provider for each installation |
users.get(login) | One account by login |
sources.subscribe(options?) | Live events over a long-lived connection |
Forges
createForges() returns an object that routes calls. See Work with several forges.
| Member | Description |
|---|---|
providers, get(), all(), for(), forUrl() | Find providers |
parseUrl(url) | Read a web URL on any registered instance |
notifications.list() | Notifications from every provider |
repos.get(), threads.get(), threads.getMany() | Reads routed by ref |
releases.list(), releases.latest() | Releases routed by repo |
securityAlerts.list() | Alerts routed by repo |
search.threads(), search.repos() | Search fanned out to every provider that supports it |