sourcehut

builds.sr.ht API Documentation

This is the GraphQL API documentation for the SourceHut service builds.sr.ht. It was generated from the service's GraphQL Schema definition.

To get started, also check out SourceHut's general GraphQL API conventions or try builds.sr.ht's GraphQL playground.

Queries

job

@access(scope:JOBS, kind:RO)

Returns information about a specific job.

Returns Job

Arguments
  1. id - Int!
Example Query 
query job($id: Int!) {
    job(id: $id) {
        id
        created
        updated
        status
        manifest
        note
        tags
        visibility
        image
        runner
        owner {
            ...Entity
        }
        group {
            ...JobGroup
        }
        tasks {
            ...Task
        }
        artifacts {
            ...Artifact
        }
        log {
            ...Log
        }
        secrets {
            ...Secret
        }
    }
}

jobs

@access(scope:JOBS, kind:RO)

Returns jobs submitted by the authenticated user.

Returns JobCursor!

Arguments
  1. cursor - Cursor
Example Query 
query jobs($cursor: Cursor) {
    jobs(cursor: $cursor) {
        results {
            ...Job
        }
        cursor
    }
}

me

@access(scope:PROFILE, kind:RO)

Returns the authenticated user.

Returns User!

Example Query 
query me {
    me {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        jobs {
            ...JobCursor
        }
    }
}

secrets

@access(scope:SECRETS, kind:RO)

Returns secrets owned by the authenticated user.

Returns SecretCursor!

Arguments
  1. cursor - Cursor
Example Query 
query secrets($cursor: Cursor) {
    secrets(cursor: $cursor) {
        results {
            ...Secret
        }
        cursor
    }
}

userByID

@access(scope:PROFILE, kind:RO)

Returns a specific user.

Returns User

Arguments
  1. id - Int!
Example Query 
query userByID($id: Int!) {
    userByID(id: $id) {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        jobs {
            ...JobCursor
        }
    }
}

userByName

@access(scope:PROFILE, kind:RO)

Returns User

Arguments
  1. username - String!
Example Query 
query userByName($username: String!) {
    userByName(username: $username) {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        jobs {
            ...JobCursor
        }
    }
}

userWebhook

Returns details of a user webhook subscription by its ID.

Returns WebhookSubscription

Arguments
  1. id - Int!
Example Query 
query userWebhook($id: Int!) {
    userWebhook(id: $id) {
        id
        events
        query
        url
        client {
            ...OAuthClient
        }
        deliveries {
            ...WebhookDeliveryCursor
        }
        sample
    }
}

userWebhooks

Returns a list of user webhook subscriptions. For clients authenticated with a personal access token, this returns all webhooks configured by all GraphQL clients for your account. For clients authenticated with an OAuth 2.0 access token, this returns only webhooks registered for your client.

Returns WebhookSubscriptionCursor!

Arguments
  1. cursor - Cursor
Example Query 
query userWebhooks($cursor: Cursor) {
    userWebhooks(cursor: $cursor) {
        results {
            ...WebhookSubscription
        }
        cursor
    }
}

version

Returns API version information.

Returns Version!

Example Query 
query version {
    version {
        major
        minor
        patch
        deprecationDate
        settings {
            ...Settings
        }
    }
}

webhook

Returns information about the webhook currently being processed. This is not valid during normal queries over HTTP, and will return an error if used outside of a webhook context.

Returns WebhookPayload!

Example Query 
query webhook {
    webhook {
        uuid
        event
        date
    }
}

Mutations

cancel

@access(scope:JOBS, kind:RW)

Cancels a submitted job.

Returns Job

Arguments
  1. jobId - Int!
Example Query 
query cancel($jobId: Int!) {
    cancel(jobId: $jobId) {
        id
        created
        updated
        status
        manifest
        note
        tags
        visibility
        image
        runner
        owner {
            ...Entity
        }
        group {
            ...JobGroup
        }
        tasks {
            ...Task
        }
        artifacts {
            ...Artifact
        }
        log {
            ...Log
        }
        secrets {
            ...Secret
        }
    }
}

claim

@worker

Claims a job.

Returns Job

Arguments
  1. jobId - Int!
Example Query 
query claim($jobId: Int!) {
    claim(jobId: $jobId) {
        id
        created
        updated
        status
        manifest
        note
        tags
        visibility
        image
        runner
        owner {
            ...Entity
        }
        group {
            ...JobGroup
        }
        tasks {
            ...Task
        }
        artifacts {
            ...Artifact
        }
        log {
            ...Log
        }
        secrets {
            ...Secret
        }
    }
}

createArtifact

@worker

Uploads a build artifact.

Returns Artifact

Arguments
  1. jobId - Int!
  2. path - String!
  3. contents - File!
Example Query 
query createArtifact($jobId: Int!, $path: String!, $contents: File!) {
    createArtifact(jobId: $jobId, path: $path, contents: $contents) {
        id
        created
        path
        size
        url
    }
}

createGroup

@access(scope:JOBS, kind:RW)

Creates a job group from several pending jobs.

'execute' may be set to false to defer queueing this job. The job group is executed immediately if unspecified.

Returns JobGroup!

Arguments
  1. jobIds - [Int]!
  2. triggers - [TriggerInput]
  3. execute - Boolean
  4. note - String
Example Query 
query createGroup($jobIds: [Int!]!, $triggers: [TriggerInput!], $execute: Boolean, $note: String) {
    createGroup(jobIds: $jobIds, triggers: $triggers, execute: $execute, note: $note) {
        id
        created
        note
        owner {
            ...Entity
        }
        jobs {
            ...Job
        }
        triggers {
            ...Trigger
        }
    }
}

createUserWebhook

Creates a new user webhook subscription. When an event from the provided list of events occurs, the 'query' parameter (a GraphQL query) will be evaluated and the results will be sent to the provided URL as the body of an HTTP POST request. The list of events must include at least one event, and no duplicates.

This query is evaluated in the webhook context, such that query { webhook } may be used to access details of the event which trigged the webhook. The query may not make any mutations.

Returns WebhookSubscription!

Arguments
  1. config - UserWebhookInput!
Example Query 
query createUserWebhook($config: UserWebhookInput!) {
    createUserWebhook(config: $config) {
        id
        events
        query
        url
        client {
            ...OAuthClient
        }
        deliveries {
            ...WebhookDeliveryCursor
        }
        sample
    }
}

deleteUser

@internal

Deletes the authenticated user's account. Internal use only.

Returns Int!

Example Query 
query deleteUser {
    deleteUser {
    }
}

deleteUserWebhook

Deletes a user webhook. Any events already queued may still be delivered after this request completes. Clients authenticated with a personal access token may delete any webhook registered for their account, but authorized OAuth 2.0 clients may only delete their own webhooks. Manually deleting a webhook configured by a third-party client may cause unexpected behavior with the third-party integration.

Returns WebhookSubscription!

Arguments
  1. id - Int!
Example Query 
query deleteUserWebhook($id: Int!) {
    deleteUserWebhook(id: $id) {
        id
        events
        query
        url
        client {
            ...OAuthClient
        }
        deliveries {
            ...WebhookDeliveryCursor
        }
        sample
    }
}

shareSecret

@access(scope:SECRETS, kind:RW)

Copies a secret to the target user account.

Returns Secret!

Arguments
  1. uuid - String!
  2. user - String!
Example Query 
query shareSecret($uuid: String!, $user: String!) {
    shareSecret(uuid: $uuid, user: $user) {
        id
        created
        uuid
        name
        fromUser {
            ...Entity
        }
    }
}

start

@access(scope:JOBS, kind:RW)

Queues a pending job.

Returns Job

Arguments
  1. jobID - Int!
Example Query 
query start($jobID: Int!) {
    start(jobID: $jobID) {
        id
        created
        updated
        status
        manifest
        note
        tags
        visibility
        image
        runner
        owner {
            ...Entity
        }
        group {
            ...JobGroup
        }
        tasks {
            ...Task
        }
        artifacts {
            ...Artifact
        }
        log {
            ...Log
        }
        secrets {
            ...Secret
        }
    }
}

startGroup

@access(scope:JOBS, kind:RW)

Starts a pending job group.

Returns JobGroup

Arguments
  1. groupId - Int!
Example Query 
query startGroup($groupId: Int!) {
    startGroup(groupId: $groupId) {
        id
        created
        note
        owner {
            ...Entity
        }
        jobs {
            ...Job
        }
        triggers {
            ...Trigger
        }
    }
}

submit

@access(scope:JOBS, kind:RW)

Submits a new job to the queue.

'secrets' may be set to false to disable secrets for this build. If unspecified, secrets are enabled if at least one is specified in the manifest and the SECRETS:RO grant is available. Enabling secrets requires the SECRETS:RO grant.

'execute' may be set to false to defer queueing this job. Builds are executed immediately if unspecified.

Returns Job!

Arguments
  1. manifest - String!
  2. tags - [String]
  3. note - String
  4. secrets - Boolean
  5. execute - Boolean
  6. visibility - Visibility
Example Query 
query submit($manifest: String!, $tags: [String!], $note: String, $secrets: Boolean, $execute: Boolean, $visibility: Visibility) {
    submit(manifest: $manifest, tags: $tags, note: $note, secrets: $secrets, execute: $execute, visibility: $visibility) {
        id
        created
        updated
        status
        manifest
        note
        tags
        visibility
        image
        runner
        owner {
            ...Entity
        }
        group {
            ...JobGroup
        }
        tasks {
            ...Task
        }
        artifacts {
            ...Artifact
        }
        log {
            ...Log
        }
        secrets {
            ...Secret
        }
    }
}

update

@access(scope:JOBS, kind:RW)

Updates the visibility of a job.

Returns Job

Arguments
  1. jobId - Int!
  2. visibility - Visibility!
Example Query 
query update($jobId: Int!, $visibility: Visibility!) {
    update(jobId: $jobId, visibility: $visibility) {
        id
        created
        updated
        status
        manifest
        note
        tags
        visibility
        image
        runner
        owner {
            ...Entity
        }
        group {
            ...JobGroup
        }
        tasks {
            ...Task
        }
        artifacts {
            ...Artifact
        }
        log {
            ...Log
        }
        secrets {
            ...Secret
        }
    }
}

updateJob

@worker

Updates job status.

Returns Job

Arguments
  1. jobId - Int!
  2. status - JobStatus!
Example Query 
query updateJob($jobId: Int!, $status: JobStatus!) {
    updateJob(jobId: $jobId, status: $status) {
        id
        created
        updated
        status
        manifest
        note
        tags
        visibility
        image
        runner
        owner {
            ...Entity
        }
        group {
            ...JobGroup
        }
        tasks {
            ...Task
        }
        artifacts {
            ...Artifact
        }
        log {
            ...Log
        }
        secrets {
            ...Secret
        }
    }
}

updateTask

@worker

Updates task status.

Returns Job

Arguments
  1. taskId - Int!
  2. status - TaskStatus!
Example Query 
query updateTask($taskId: Int!, $status: TaskStatus!) {
    updateTask(taskId: $taskId, status: $status) {
        id
        created
        updated
        status
        manifest
        note
        tags
        visibility
        image
        runner
        owner {
            ...Entity
        }
        group {
            ...JobGroup
        }
        tasks {
            ...Task
        }
        artifacts {
            ...Artifact
        }
        log {
            ...Log
        }
        secrets {
            ...Secret
        }
    }
}

Definitions

AccessKind

ENUM
Enum Values
  1. RO
  2. RW

AccessScope

ENUM
Enum Values
  1. PROFILE
  2. JOBS
  3. LOGS
  4. SECRETS

Artifact

OBJECT
Fields
  1. id - Int!
  2. created - Time!
  3. path - String!
    • Original path in the guest
  4. size - Int!
    • Size in bytes
  5. url - String
    • URL at which the artifact may be downloaded, or null if pruned

Binary

SCALAR

Boolean

SCALAR

The Boolean scalar type represents true or false.

Cursor

SCALAR

EmailTrigger

OBJECT implements Trigger
Fields
  1. condition - TriggerCondition!
  2. to - String!
  3. cc - String
  4. inReplyTo - String

EmailTriggerInput

INPUT_OBJECT
Fields
  1. to - String!
  2. cc - String
  3. inReplyTo - String

Entity

INTERFACE
Fields
  1. id - Int!
  2. created - Time!
  3. updated - Time!
  4. canonicalName - String!
    • The canonical name of this entity. For users, this is their username prefixed with '~'. Additional entity types will be supported in the future.

File

SCALAR

Float

SCALAR

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

ID

SCALAR

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Int

SCALAR

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Job

OBJECT
Fields
  1. id - Int!
  2. created - Time!
  3. updated - Time!
  4. status - JobStatus!
  5. manifest - String!
  6. note - String
  7. tags - [String]!
  8. visibility - Visibility!
  9. image - String!
    • Name of the build image
  10. runner - String
    • Name of the build runner which picked up this job, or null if the job is pending or queued.
  11. owner - Entity!
  12. group - JobGroup
  13. tasks - [Task]!
  14. artifacts - [Artifact]!
  15. log - Log
    • The job's top-level log file, not associated with any tasks
  16. secrets - [Secret]
    • List of secrets available to this job, or null if they were disabled

JobCursor

OBJECT

A cursor for enumerating a list of jobs

If there are additional results available, the cursor object may be passed back into the same endpoint to retrieve another page. If the cursor is null, there are no remaining results to return.

Fields
  1. results - [Job]!
  2. cursor - Cursor

JobEvent

OBJECT implements WebhookPayload
Fields
  1. uuid - String!
  2. event - WebhookEvent!
  3. date - Time!
  4. job - Job!

JobGroup

OBJECT
Fields
  1. id - Int!
  2. created - Time!
  3. note - String
  4. owner - Entity!
  5. jobs - [Job]!
  6. triggers - [Trigger]!

JobStatus

ENUM
Enum Values
  1. PENDING
  2. QUEUED
  3. RUNNING
  4. SUCCESS
  5. FAILED
  6. TIMEOUT
  7. CANCELLED

Log

OBJECT
Fields
  1. last128KiB - String!
    • The most recently written 128 KiB of the build log.
  2. fullURL - String!
    • The URL at which the full build log can be downloaded with an authenticated GET request (text/plain).

OAuthClient

OBJECT
Fields
  1. uuid - String!

PGPKey

OBJECT implements Secret
Fields
  1. id - Int!
  2. created - Time!
  3. uuid - String!
  4. name - String
  5. fromUser - Entity
  6. privateKey - Binary!

SSHKey

OBJECT implements Secret
Fields
  1. id - Int!
  2. created - Time!
  3. uuid - String!
  4. name - String
  5. fromUser - Entity
  6. privateKey - Binary!

Secret

INTERFACE
Fields
  1. id - Int!
  2. created - Time!
  3. uuid - String!
  4. name - String
  5. fromUser - Entity
    • Set when this secret was copied from another user account

SecretCursor

OBJECT

A cursor for enumerating a list of secrets

If there are additional results available, the cursor object may be passed back into the same endpoint to retrieve another page. If the cursor is null, there are no remaining results to return.

Fields
  1. results - [Secret]!
  2. cursor - Cursor

SecretFile

OBJECT implements Secret
Fields
  1. id - Int!
  2. created - Time!
  3. uuid - String!
  4. name - String
  5. fromUser - Entity
  6. path - String!
  7. mode - Int!
  8. data - Binary!

Settings

OBJECT
Fields
  1. sshUser - String!
  2. buildTimeout - String!

String

SCALAR

The Stringscalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Task

OBJECT
Fields
  1. id - Int!
  2. created - Time!
  3. updated - Time!
  4. name - String!
  5. status - TaskStatus!
  6. log - Log
  7. job - Job!

TaskStatus

ENUM
Enum Values
  1. PENDING
  2. RUNNING
  3. SUCCESS
  4. FAILED
  5. SKIPPED

Time

SCALAR

Trigger

INTERFACE

Triggers run upon the completion of all of the jobs in a job group. Note that these triggers are distinct from the ones defined by an individual job's build manifest, but are similar in functionality.

Fields
  1. condition - TriggerCondition!

TriggerCondition

ENUM
Enum Values
  1. SUCCESS
  2. FAILURE
  3. ALWAYS

TriggerInput

INPUT_OBJECT
Fields
  1. type - TriggerType!
  2. condition - TriggerCondition!
  3. email - EmailTriggerInput
  4. webhook - WebhookTriggerInput

TriggerType

ENUM
Enum Values
  1. EMAIL
  2. WEBHOOK

User

OBJECT implements Entity
Fields
  1. id - Int!
  2. created - Time!
  3. updated - Time!
  4. canonicalName - String!
  5. username - String!
  6. email - String!
  7. url - String
  8. location - String
  9. bio - String
  10. jobs(cursor: Cursor) - JobCursor!
    • Jobs submitted by this user.

UserWebhookInput

INPUT_OBJECT
Fields
  1. url - String!
  2. events - [WebhookEvent]!
  3. query - String!

UserWebhookSubscription

OBJECT implements WebhookSubscription
Fields
  1. id - Int!
  2. events - [WebhookEvent]!
  3. query - String!
  4. url - String!
  5. client - OAuthClient
  6. deliveries(cursor: Cursor) - WebhookDeliveryCursor!
  7. sample(event: WebhookEvent!) - String!

Version

OBJECT
Fields
  1. major - Int!
  2. minor - Int!
  3. patch - Int!
  4. deprecationDate - Time
    • If this API version is scheduled for deprecation, this is the date on which it will stop working; or null if this API version is not scheduled for deprecation.
  5. settings - Settings!

Visibility

ENUM
Enum Values
  1. PUBLIC
  2. UNLISTED
  3. PRIVATE

WebhookDelivery

OBJECT
Fields
  1. uuid - String!
  2. date - Time!
  3. event - WebhookEvent!
  4. subscription - WebhookSubscription!
  5. requestBody - String!
  6. responseBody - String
    • These details are provided only after a response is received from the remote server. If a response is sent whose Content-Type is not text/*, or cannot be decoded as UTF-8, the response body will be null. It will be truncated after 64 KiB.
  7. responseHeaders - String
  8. responseStatus - Int

WebhookDeliveryCursor

OBJECT

A cursor for enumerating a list of webhook deliveries

If there are additional results available, the cursor object may be passed back into the same endpoint to retrieve another page. If the cursor is null, there are no remaining results to return.

Fields
  1. results - [WebhookDelivery]!
  2. cursor - Cursor

WebhookEvent

ENUM
Enum Values
  1. JOB_CREATED
  2. JOB_UPDATED

WebhookPayload

INTERFACE
Fields
  1. uuid - String!
  2. event - WebhookEvent!
  3. date - Time!

WebhookSubscription

INTERFACE
Fields
  1. id - Int!
  2. events - [WebhookEvent]!
  3. query - String!
  4. url - String!
  5. client - OAuthClient
    • If this webhook was registered by an authorized OAuth 2.0 client, this field is non-null.
  6. deliveries(cursor: Cursor) - WebhookDeliveryCursor!
    • All deliveries which have been sent to this webhook.
  7. sample(event: WebhookEvent!) - String!
    • Returns a sample payload for this subscription, for testing purposes

WebhookSubscriptionCursor

OBJECT

A cursor for enumerating a list of webhook subscriptions

If there are additional results available, the cursor object may be passed back into the same endpoint to retrieve another page. If the cursor is null, there are no remaining results to return.

Fields
  1. results - [WebhookSubscription]!
  2. cursor - Cursor

WebhookTrigger

OBJECT implements Trigger
Fields
  1. condition - TriggerCondition!
  2. url - String!

WebhookTriggerInput

INPUT_OBJECT
Fields
  1. url - String!

Directives

@access

Decorates fields for which access requires a particular OAuth 2.0 scope with read or write access.

Arguments
  1. scope - AccessScope!
  2. kind - AccessKind!

@defer

Directs the executor to defer this fragment when the if argument is true or undefined.

Arguments
  1. if - Boolean
    • Deferred when true or undefined.
  2. label - String
    • Unique name

@deprecated

Marks an element of a GraphQL schema as no longer supported.

Arguments
  1. reason - String
    • Explains why this element was deprecated, usually also including a suggestion for how to access supported similar data. Formatted using the Markdown syntax, as specified by [CommonMark](https://commonmark.org/).

@include

Directs the executor to include this field or fragment only when the if argument is true.

Arguments
  1. if - Boolean!
    • Included when true.

@internal

This is used to decorate fields which are for internal use, and are not available to normal API users.

@oneOf

Indicates exactly one field must be supplied and this field must not be null.

@private

This is used to decorate fields which are only accessible with a personal access token, and are not available to clients using OAuth 2.0 access tokens.

@scopehelp

Used to provide a human-friendly description of an access scope

Arguments
  1. details - String!

@skip

Directs the executor to skip this field or fragment when the if argument is true.

Arguments
  1. if - Boolean!
    • Skipped when true.

@specifiedBy

Exposes a URL that specifies the behavior of this scalar.

Arguments
  1. url - String!
    • The URL that specifies the behavior of this scalar.

@worker

This used to decorate private resolvers which are only accessible to build workers, and are used to facilitate the build process.