ActiveState Build Planner GraphQL API

To create new projects, commits, inspect sources and builds, and publish your private ingredients in automated workflows, use the BuildPlanner GraphQL API.

Craft your queries at https://platform.activestate.com/sv/buildplanner/graphql

For information on how to obtain an API token, see the authorization documentation.

Contact

Support

support@activestate.com

https://www.activestate.com/support/

Terms of Service

https://www.activestate.com/support/eulas/

API Endpoints

https://platform.activestate.com/sv/buildplanner/graphql

Headers

# Your API token from the dashboard. Must be included in all API calls.
Authorization: Bearer <YOUR_TOKEN_HERE>
# The content type of the request body. Must be included in all API calls.
Content-Type: application/json; charset=utf-8

Queries

`commit`

Description

Retrieves a commit.

The retrieved commit does not need to be part of any branch or project.

Response

Returns a CommitResult!

Arguments

Name	Description
`commitId` - `ID!`

Example

Query

query commit($commitId: ID!) {
  commit(commitId: $commitId) {
    ... on Commit {
      ...CommitFragment
    }
    ... on NotFound {
      ...NotFoundFragment
    }
  }
}

Variables

{"commitId": "4"}

Response

{"data": {"commit": Commit}}

Queries

`impactReport`

Description

Summarize the differences between two build plans, with a focus on included ingredients, annotated with additional metadata like CVEs.

The build plans can be specified as either commitIDs or literal BuildExprs; in either case the referenced BuildExprs will be solved to get the build plans to compare.

Response

Returns an ImpactReportResult!

Arguments

Name	Description
`before` - `ImpactReportInput!`
`after` - `ImpactReportInput!`

Example

Query

query impactReport(
  $before: ImpactReportInput!,
  $after: ImpactReportInput!
) {
  impactReport(
    before: $before,
    after: $after
  ) {
    ... on ImpactReport {
      ...ImpactReportFragment
    }
    ... on ImpactReportError {
      ...ImpactReportErrorFragment
    }
  }
}

Variables

{
  "before": ImpactReportInput,
  "after": ImpactReportInput
}

Response

{"data": {"impactReport": ImpactReport}}

Queries

`project`

Description

Query a project by organization name and project name.

Returns a GraphQL union type which is either a Project or a NotFound response

Response

Returns a ProjectResult!

Arguments

Name	Description
`organization` - `String!`
`project` - `String!`

Example

Query

query project(
  $organization: String!,
  $project: String!
) {
  project(
    organization: $organization,
    project: $project
  ) {
    ... on Project {
      ...ProjectFragment
    }
    ... on NotFound {
      ...NotFoundFragment
    }
  }
}

Variables

{
  "organization": "abc123",
  "project": "xyz789"
}

Response

{"data": {"project": Project}}

Mutations

`buildCommitTarget`

Description

Build a target.

Starts the build for the target's build plan. Only one build will be started for the target regardless of how many times this mutation is called.

Response

Returns a BuildCommitTargetResult!

Arguments

Name	Description
`input` - `BuildCommitTargetInput!`

Example

Query

mutation buildCommitTarget($input: BuildCommitTargetInput!) {
  buildCommitTarget(input: $input) {
    ... on BuildPlanning {
      ...BuildPlanningFragment
    }
    ... on BuildPlanned {
      ...BuildPlannedFragment
    }
    ... on BuildStarted {
      ...BuildStartedFragment
    }
    ... on BuildPartial {
      ...BuildPartialFragment
    }
    ... on BuildCompleted {
      ...BuildCompletedFragment
    }
    ... on PlanningError {
      ...PlanningErrorFragment
    }
    ... on NotFound {
      ...NotFoundFragment
    }
    ... on InvalidInput {
      ...InvalidInputFragment
    }
  }
}

Variables

{"input": BuildCommitTargetInput}

Response

{"data": {"buildCommitTarget": BuildPlanning}}

Mutations

`createProject`

Description

Create a new project.

The created project will have a main branch and single commit. The commit's content is the build expression.

Response

Returns a CreateProjectResult!

Arguments

Name	Description
`input` - `CreateProjectInput!`

Example

Query

mutation createProject($input: CreateProjectInput!) {
  createProject(input: $input) {
    ... on ProjectCreated {
      ...ProjectCreatedFragment
    }
    ... on AlreadyExists {
      ...AlreadyExistsFragment
    }
    ... on NotFound {
      ...NotFoundFragment
    }
    ... on ParseError {
      ...ParseErrorFragment
    }
    ... on ValidationError {
      ...ValidationErrorFragment
    }
    ... on Forbidden {
      ...ForbiddenFragment
    }
    ... on InvalidInput {
      ...InvalidInputFragment
    }
  }
}

Variables

{"input": CreateProjectInput}

Response

{"data": {"createProject": ProjectCreated}}

Mutations

`mergeCommit`

Description

Merge two commits.

Creates a new commit on top of a target commit with changes from another commit other.

Used for updating a target branch with the changes from the other commit (in which case the target branch name is passed) or staging a new merged commit on top of the target commit (in which case the target commit id is passed).

Different strategies to resolve conflicts can be selected:

Recursive: Applies changesets from both target and other to a common base: if changesets are incompatible, a MergeConflict object is returned.
RecursiveKeepOnConflict: Same as Recursive, but if a changeset conflict arises the changeset from the target reference is applied. Always returns a new commit.
RecursiveOverwriteOnConflict: Same as Recursive, but if a changeset conflict arises the changeset from the other commit is applied. Always returns a new commit.
FastForward: Attempts to apply changesets from the other branch on top of the target branch. This only succeeds if a commit on the other branch is equal to the HEAD commit on the target branch. Returns a FastForwardError on conflict, a Commit on Success.

Response

Returns a MergeCommitResult!

Arguments

Name	Description
`input` - `MergeCommitInput!`

Example

Query

mutation mergeCommit($input: MergeCommitInput!) {
  mergeCommit(input: $input) {
    ... on MergedCommit {
      ...MergedCommitFragment
    }
    ... on MergeConflict {
      ...MergeConflictFragment
    }
    ... on FastForwardError {
      ...FastForwardErrorFragment
    }
    ... on NoCommonBaseFound {
      ...NoCommonBaseFoundFragment
    }
    ... on NotFound {
      ...NotFoundFragment
    }
    ... on ParseError {
      ...ParseErrorFragment
    }
    ... on ValidationError {
      ...ValidationErrorFragment
    }
    ... on Forbidden {
      ...ForbiddenFragment
    }
    ... on HeadOnBranchMoved {
      ...HeadOnBranchMovedFragment
    }
    ... on NoChangeSinceLastCommit {
      ...NoChangeSinceLastCommitFragment
    }
    ... on InvalidInput {
      ...InvalidInputFragment
    }
  }
}

Variables

{"input": MergeCommitInput}

Response

{"data": {"mergeCommit": MergedCommit}}

Mutations

`mergeUpstreamBranch`

Description

Merge changes into a target branch from its upstream branch.

Creates a new HEAD commit for the target branch that contains the changes from the upstream branch.

Used to pull changes from an upstream branch to the target branch.

It is an error if the target branch does not have an upstream branch

Different strategies to resolve conflicts can be selected:

Recursive: Applies changesets from both target and other to a common base: if changesets are incompatible, a MergeConflict object is returned.
RecursiveKeepOnConflict: Same as Recursive, but if a changeset conflict arises the changeset from the target reference is applied. Always returns a new commit.
RecursiveOverwriteOnConflict: Same as Recursive, but if a changeset conflict arises the changeset from the other commit is applied. Always returns a new commit.
FastForward: Attempts to apply changesets from the other branch on top of the target branch. This only succeeds if a commit on the other branch is equal to the HEAD commit on the target branch. Returns a FastForwardError on conflict, a Commit on Success.

Response

Returns a MergeUpstreamBranchResult!

Arguments

Name	Description
`input` - `MergeUpstreamBranchInput!`

Example

Query

mutation mergeUpstreamBranch($input: MergeUpstreamBranchInput!) {
  mergeUpstreamBranch(input: $input) {
    ... on MergedCommit {
      ...MergedCommitFragment
    }
    ... on MergeConflict {
      ...MergeConflictFragment
    }
    ... on FastForwardError {
      ...FastForwardErrorFragment
    }
    ... on NoUpstreamBranch {
      ...NoUpstreamBranchFragment
    }
    ... on NotFound {
      ...NotFoundFragment
    }
    ... on ParseError {
      ...ParseErrorFragment
    }
    ... on ValidationError {
      ...ValidationErrorFragment
    }
    ... on Forbidden {
      ...ForbiddenFragment
    }
    ... on HeadOnBranchMoved {
      ...HeadOnBranchMovedFragment
    }
    ... on NoChangeSinceLastCommit {
      ...NoChangeSinceLastCommitFragment
    }
    ... on InvalidInput {
      ...InvalidInputFragment
    }
  }
}

Variables

{"input": MergeUpstreamBranchInput}

Response

{"data": {"mergeUpstreamBranch": MergedCommit}}

Mutations

`publish`

Description

Publish a single package.

Only authenticated users can publish a package. The package's path must start with 'org/{org_name}', where {org_name} is the name of an organization the user is a member of. If a namespace with the name does not exist, it will be created.

This is an experimental mutation and is likely to change in the future

Response

Returns a PublishResult!

Arguments

Name	Description
`input` - `PublishInput!`

Example

Query

mutation publish($input: PublishInput!) {
  publish(input: $input) {
    ... on CreatedIngredientVersionRevision {
      ...CreatedIngredientVersionRevisionFragment
    }
    ... on Forbidden {
      ...ForbiddenFragment
    }
    ... on MultiPartUploadFileExpected {
      ...MultiPartUploadFileExpectedFragment
    }
    ... on InvalidNamespaceName {
      ...InvalidNamespaceNameFragment
    }
    ... on InvalidIngredientVersion {
      ...InvalidIngredientVersionFragment
    }
    ... on InvalidInput {
      ...InvalidInputFragment
    }
  }
}

Variables

{"input": PublishInput}

Response

{"data": {"publish": CreatedIngredientVersionRevision}}

Mutations

`pushCommit`

Description

Push a new commit that is the head of a branch.

The created commit's content is the build expression.

The branchRef can be either a branch name or id and will be updated to point at the created commit. If branchRef is not specified, the project's main branch will be updated.

Response

Returns a PushCommitResult!

Arguments

Name	Description
`input` - `PushCommitInput!`

Example

Query

mutation pushCommit($input: PushCommitInput!) {
  pushCommit(input: $input) {
    ... on Commit {
      ...CommitFragment
    }
    ... on NotFound {
      ...NotFoundFragment
    }
    ... on ParseError {
      ...ParseErrorFragment
    }
    ... on ValidationError {
      ...ValidationErrorFragment
    }
    ... on Forbidden {
      ...ForbiddenFragment
    }
    ... on HeadOnBranchMoved {
      ...HeadOnBranchMovedFragment
    }
    ... on NoChangeSinceLastCommit {
      ...NoChangeSinceLastCommitFragment
    }
    ... on InvalidInput {
      ...InvalidInputFragment
    }
  }
}

Variables

{"input": PushCommitInput}

Response

{"data": {"pushCommit": Commit}}

Mutations

`revertCommit`

Use only for specific state revert use-case. Will be replaced by more generalized queries

Description

Revert a commit.

Creates a new commit on top of the branch HEAD with the changes from the commit reverted.

Response

Returns a RevertCommitResult!

Arguments

Name	Description
`input` - `RevertCommitInput!`

Example

Query

mutation revertCommit($input: RevertCommitInput!) {
  revertCommit(input: $input) {
    ... on RevertedCommit {
      ...RevertedCommitFragment
    }
    ... on RevertConflict {
      ...RevertConflictFragment
    }
    ... on CommitNotInTargetHistory {
      ...CommitNotInTargetHistoryFragment
    }
    ... on CommitHasNoParent {
      ...CommitHasNoParentFragment
    }
    ... on NotFound {
      ...NotFoundFragment
    }
    ... on ParseError {
      ...ParseErrorFragment
    }
    ... on ValidationError {
      ...ValidationErrorFragment
    }
    ... on Forbidden {
      ...ForbiddenFragment
    }
    ... on HeadOnBranchMoved {
      ...HeadOnBranchMovedFragment
    }
    ... on NoChangeSinceLastCommit {
      ...NoChangeSinceLastCommitFragment
    }
    ... on InvalidInput {
      ...InvalidInputFragment
    }
  }
}

Variables

{"input": RevertCommitInput}

Response

{"data": {"revertCommit": RevertedCommit}}

Mutations

`setVariable`

Description

Create a new commit by setting a variable in the parent commit's build expr.

If the variable does not exist it will be created.

This will only set a variable in the top level let.

Response

Returns a SetVariableResult!

Arguments

Name	Description
`input` - `SetVariableInput!`

Example

Query

mutation setVariable($input: SetVariableInput!) {
  setVariable(input: $input) {
    ... on Commit {
      ...CommitFragment
    }
    ... on NotFound {
      ...NotFoundFragment
    }
    ... on ParseError {
      ...ParseErrorFragment
    }
    ... on ValidationError {
      ...ValidationErrorFragment
    }
    ... on Forbidden {
      ...ForbiddenFragment
    }
    ... on HeadOnBranchMoved {
      ...HeadOnBranchMovedFragment
    }
    ... on NoChangeSinceLastCommit {
      ...NoChangeSinceLastCommitFragment
    }
    ... on InvalidInput {
      ...InvalidInputFragment
    }
  }
}

Variables

{"input": SetVariableInput}

Response

{"data": {"setVariable": Commit}}

Mutations

`stageCommit`

Description

Stage a new commit.

A staged commit is different from a pushed commit in that it is not pointed at by a branch and may not be associated with an organization or project.

Response

Returns a StageCommitResult!

Arguments

Name	Description
`input` - `StageCommitInput!`

Example

Query

mutation stageCommit($input: StageCommitInput!) {
  stageCommit(input: $input) {
    ... on Commit {
      ...CommitFragment
    }
    ... on NotFound {
      ...NotFoundFragment
    }
    ... on ParseError {
      ...ParseErrorFragment
    }
    ... on ValidationError {
      ...ValidationErrorFragment
    }
    ... on Forbidden {
      ...ForbiddenFragment
    }
    ... on HeadOnBranchMoved {
      ...HeadOnBranchMovedFragment
    }
    ... on NoChangeSinceLastCommit {
      ...NoChangeSinceLastCommitFragment
    }
    ... on InvalidInput {
      ...InvalidInputFragment
    }
  }
}

Variables

{"input": StageCommitInput}

Response

{"data": {"stageCommit": Commit}}

Types

AlreadyExists

Description

An error indicating that a resource resource of type type already exists and cannot be created.

Fields

Field Name	Description
`message` - `String!`
`type` - `String!`
`resource` - `String!`

Example

{
  "message": "xyz789",
  "type": "xyz789",
  "resource": "abc123"
}

Types

AltBuildId

Fields

Field Name	Description
`id` - `ID!`

Example

{"id": "4"}

Types

Any

Example

Any

Types

Artifact

Description

Artifact can be specialized based on its state

Fields

Field Name	Description
`nodeId` - `ID!`
`displayName` - `String!`
`mimeType` - `String!`
`generatedBy` - `ID!`
`runtimeDependencies` - `[ID!]!`
`status` - `ArtifactStatus!`
`relatesTo` - `[ComponentRelationship!]!`	The components related to this Artifact.

Possible Types

Artifact Types
`ArtifactSucceeded`
`ArtifactUnbuilt`
`ArtifactStarted`
`ArtifactTransientlyFailed`
`ArtifactPermanentlyFailed`

Example

{
  "nodeId": 4,
  "displayName": "xyz789",
  "mimeType": "xyz789",
  "generatedBy": 4,
  "runtimeDependencies": [4],
  "status": "NOT_SUBMITTED",
  "relatesTo": [ComponentRelationship]
}

Types

ArtifactFailed

Fields

Field Name	Description
`nodeId` - `ID!`
`displayName` - `String!`
`mimeType` - `String!`
`generatedBy` - `ID!`
`runtimeDependencies` - `[ID!]!`
`status` - `ArtifactStatus!`
`lastBuildFinishedAt` - `DateTime!`	timestamp of the most recent change to the ArtifactStatus of this artifact
`buildDuration` - `Float!`	Duration in seconds of the last build attempt
`logURL` - `URI`	logURL points to a log file with information on the build attempt
`errors` - `[String!]!`	relevant error messages that occurred during the last builds or while scheduling them
`relatesTo` - `[ComponentRelationship!]!`	The components related to this Artifact.

Possible Types

ArtifactFailed Types
`ArtifactTransientlyFailed`
`ArtifactPermanentlyFailed`

Example

{
  "nodeId": 4,
  "displayName": "xyz789",
  "mimeType": "xyz789",
  "generatedBy": 4,
  "runtimeDependencies": [4],
  "status": "NOT_SUBMITTED",
  "lastBuildFinishedAt": "2007-12-03T10:15:30Z",
  "buildDuration": 987.65,
  "logURL": URI,
  "errors": ["xyz789"],
  "relatesTo": [ComponentRelationship]
}

Types

ArtifactPermanentlyFailed

Description

ArtifactPermanentlyFailed represents an artifact that is in a FAILED_PERMANENTLY state and cannot be retried.

Fields

Field Name	Description
`nodeId` - `ID!`
`displayName` - `String!`
`mimeType` - `String!`
`generatedBy` - `ID!`
`runtimeDependencies` - `[ID!]!`
`status` - `ArtifactStatus!`	status would always be FAILED_PERMANENTLY for this implementation
`lastBuildFinishedAt` - `DateTime!`	timestamp of the most recent change to the ArtifactStatus of this artifact
`buildDuration` - `Float!`	Duration in seconds of the last build attempt
`logURL` - `URI`	logURL points to a log file with information on the build attempt
`errors` - `[String!]!`	relevant error messages that occurred during the build
`relatesTo` - `[ComponentRelationship!]!`	The components related to this Artifact.

Example

{
  "nodeId": 4,
  "displayName": "abc123",
  "mimeType": "xyz789",
  "generatedBy": "4",
  "runtimeDependencies": ["4"],
  "status": "NOT_SUBMITTED",
  "lastBuildFinishedAt": "2007-12-03T10:15:30Z",
  "buildDuration": 987.65,
  "logURL": URI,
  "errors": ["xyz789"],
  "relatesTo": [ComponentRelationship]
}

Types

ArtifactStarted

Description

ArtifactStarted represents an Artifact that has started building.

Fields

Field Name	Description
`nodeId` - `ID!`
`displayName` - `String!`
`mimeType` - `String!`
`generatedBy` - `ID!`
`runtimeDependencies` - `[ID!]!`
`status` - `ArtifactStatus!`	status would be STARTED for this implementation
`startedAt` - `DateTime!`	startedAt is only populated once the artifact has started building
`relatesTo` - `[ComponentRelationship!]!`	The components related to this Artifact.

Example

{
  "nodeId": "4",
  "displayName": "abc123",
  "mimeType": "xyz789",
  "generatedBy": "4",
  "runtimeDependencies": [4],
  "status": "NOT_SUBMITTED",
  "startedAt": "2007-12-03T10:15:30Z",
  "relatesTo": [ComponentRelationship]
}

Types

ArtifactStatus

Values

Enum Value	Description
`NOT_SUBMITTED`	Artifact has not been submitted to the build backend.
`BLOCKED`	Artifact is waiting for its dependency to be built.
`FAILED_PERMANENTLY`	An error occurred while building the artifact and the build will not be retried.
`FAILED_TRANSIENTLY`	An error occurred while building the artifact and the build will be retried.
`READY`	Artifact is in the queue to be built as soon as a build host is available -- merge into queued?
`SKIPPED`	A transitive dependency failed, so this artifact will not be attempted.
`STARTED`	The artifact's build has started.
`SUCCEEDED`	An Artifact built successfully.

Example

"NOT_SUBMITTED"

Types

ArtifactSucceeded

Description

ArtifactSucceeded represents an Artifact that has been successfully built.

Fields

Field Name	Description
`nodeId` - `ID!`
`displayName` - `String!`
`mimeType` - `String!`
`generatedBy` - `ID!`
`runtimeDependencies` - `[ID!]!`
`status` - `ArtifactStatus!`	status would be SUCCEEDED for this implementation
`lastBuildFinishedAt` - `DateTime!`	timestamp of the most recent change to the ArtifactStatus of this artifact
`buildDuration` - `Float!`	Duration in seconds of the last build attempt
`logURL` - `URI`	logURL is pointing to a log file with information about the successful build
`url` - `URI!`	url is pointing to the build output
`checksum` - `String!`	checksum is a SHA hash of the build output
`attestations` - `AttestationsResult!`
`relatesTo` - `[ComponentRelationship!]!`	The components related to this Artifact.

Example

{
  "nodeId": "4",
  "displayName": "xyz789",
  "mimeType": "xyz789",
  "generatedBy": "4",
  "runtimeDependencies": ["4"],
  "status": "NOT_SUBMITTED",
  "lastBuildFinishedAt": "2007-12-03T10:15:30Z",
  "buildDuration": 987.65,
  "logURL": URI,
  "url": URI,
  "checksum": "xyz789",
  "attestations": Attestations,
  "relatesTo": [ComponentRelationship]
}

Types

ArtifactTransientlyFailed

Description

ArtifactTransientlyFailed represents an artifact that is in a failed state, but will be retried at a later time.

Fields

Field Name	Description
`nodeId` - `ID!`
`displayName` - `String!`
`mimeType` - `String!`
`generatedBy` - `ID!`
`runtimeDependencies` - `[ID!]!`
`status` - `ArtifactStatus!`	status is FAILED_TRANSIENTLY for this implementation
`lastBuildFinishedAt` - `DateTime!`	timestamp of the most recent change to the ArtifactStatus of this artifact
`buildDuration` - `Float!`	Duration in seconds of the last build attempt
`logURL` - `URI`	logURL points to a log file with information on the build attempt
`errors` - `[String!]!`	relevant error messages that occurred during the last builds or while scheduling them
`attempts` - `Int!`	The number of build attempts for the artifact
`nextAttemptAt` - `DateTime!`	timestamp when the next attempt to build the artifact will started
`relatesTo` - `[ComponentRelationship!]!`	The components related to this Artifact.

Example

{
  "nodeId": "4",
  "displayName": "abc123",
  "mimeType": "abc123",
  "generatedBy": 4,
  "runtimeDependencies": [4],
  "status": "NOT_SUBMITTED",
  "lastBuildFinishedAt": "2007-12-03T10:15:30Z",
  "buildDuration": 123.45,
  "logURL": URI,
  "errors": ["abc123"],
  "attempts": 987,
  "nextAttemptAt": "2007-12-03T10:15:30Z",
  "relatesTo": [ComponentRelationship]
}

Types

ArtifactUnbuilt

Description

ArtifactUnbuilt represents an Artifact for which no build has been attempted yet.

Fields

Field Name	Description
`nodeId` - `ID!`
`displayName` - `String!`
`mimeType` - `String!`
`generatedBy` - `ID!`
`runtimeDependencies` - `[ID!]!`
`status` - `ArtifactStatus!`	status would be one of NOT_SUBMITTED, BLOCKED, READY or SKIPPED for this implementation
`relatesTo` - `[ComponentRelationship!]!`	The components related to this Artifact.

Example

{
  "nodeId": "4",
  "displayName": "xyz789",
  "mimeType": "abc123",
  "generatedBy": 4,
  "runtimeDependencies": ["4"],
  "status": "NOT_SUBMITTED",
  "relatesTo": [ComponentRelationship]
}

Types

AtTimeRemediation

Description

EXPERIMENTAL FEATURE: Remediable Error This type may be modified or removed from the schema without notice.

A remediation to update the commit.atTime value to the suggested timestamp.

Fields

Field Name	Description
`description` - `String!`
`suggestedPriority` - `Int!`
`suggestedAtTime` - `DateTime!`

Example

{
  "description": "xyz789",
  "suggestedPriority": 123,
  "suggestedAtTime": "2007-12-03T10:15:30Z"
}

Types

Attestations

Fields

Field Name	Description
`slsa_provenance` - `URI!`
Arguments `version` - `String!`
`slsa_vsa` - `URI!`
Arguments `version` - `String!`
`cves` - `URI!`
Arguments `version` - `String!`

Example

{
  "slsa_provenance": URI,
  "slsa_vsa": URI,
  "cves": URI
}

Types

AttestationsResult

Types

Union Types
`Attestations`
`FeatureNotEnabled`

Example

Attestations

Types

AuthorInput

Fields

Input Field	Description
`name` - `String`
`email` - `String`
`websites` - `[String!]`

Example

{
  "name": "abc123",
  "email": "abc123",
  "websites": ["xyz789"]
}

Types

Boolean

Description

The Boolean scalar type represents true or false.

Types

Branch

Fields

Field Name	Description
`branchId` - `ID!`
`label` - `String!`

Example

{
  "branchId": "4",
  "label": "abc123"
}

Types

Build

Fields

Field Name	Description
`status` - `BuildPlanStatus!`	BuildPlan status
`components` - `[Component!]!`	The components in the BuildPlan. Each component is related to one or more nodes.
`nodes` - `[Node!]!`	The nodes in the BuildPlan. Each node is related to one or more components.
`steps` - `[Step!]!`	The steps in the BuildPlan.
`terminals` - `[TaggedNodes!]!`	List of IDs that are the required items of the given BuildPlan. The primary use-case for the node names is to identify the terminals that have been selected for each platform. TBD: Possible tag values: "platform: 0000-0000-000000000-0000-0000", "kernel:linux", "arch:x86_64", "glibc:2.14
`resolvedRequirements` - `[ResolvedRequirement!]!`	Information specific to the requested requirements from the client

Possible Types

Build Types
`BuildPlanning`
`BuildPlanned`
`BuildStarted`
`BuildPartial`
`BuildCompleted`

Example

{
  "status": "PLANNING",
  "components": [Component],
  "nodes": [Source],
  "steps": [Step],
  "terminals": [TaggedNodes],
  "resolvedRequirements": [ResolvedRequirement]
}

Types

BuildCommitTargetInput

Fields

Input Field	Description
`organization` - `String!`
`project` - `String!`
`commitId` - `String!`
`target` - `String`	The target to build. When the build expression is a Let, the in value is the main target. By providing a target to build, a different target will be executed. The value of target must be a valid value in the Let's arguments or a PlanningError will be returned. For example, given this build expression: let: python = ... perl = ... in: $python Without specifying a target, "python" will be executed and its build returned. Setting target to "perl", will execute the perl target in the Let instead, allowing one build expression to contain multiple builds. If not set commit's main target will be built.

Example

{
  "organization": "abc123",
  "project": "abc123",
  "commitId": "abc123",
  "target": "abc123"
}

Types

BuildCommitTargetResult

Types

Union Types
`BuildPlanning`
`BuildPlanned`
`BuildStarted`
`BuildPartial`
`BuildCompleted`
`PlanningError`
`NotFound`
`InvalidInput`

Example

BuildPlanning

Types

BuildCompleted

Description

The final state for a build plan's build that has finished execution for all parts of the plan.

All artifacts are either successfully built or failed.

Fields

Field Name	Description
`status` - `BuildPlanStatus!`
`buildLogIds` - `[BuildLogId!]!`
`components` - `[Component!]!`
`nodes` - `[Node!]!`
`steps` - `[Step!]!`
`terminals` - `[TaggedNodes!]!`
`resolvedRequirements` - `[ResolvedRequirement!]!`
`startedAt` - `DateTime!`
`finishedAt` - `DateTime!`
`buildDuration` - `Float!`	duration of build in seconds

Example

{
  "status": "PLANNING",
  "buildLogIds": [CamelBuildId],
  "components": [Component],
  "nodes": [Source],
  "steps": [Step],
  "terminals": [TaggedNodes],
  "resolvedRequirements": [ResolvedRequirement],
  "startedAt": "2007-12-03T10:15:30Z",
  "finishedAt": "2007-12-03T10:15:30Z",
  "buildDuration": 987.65
}

Types

BuildExpr

Description

A BuildExpr (build expression) encoded as either JSON dictionary or a GraphQL dictionary.

A build expression is a interpretable script that describes the artifacts to build from one or more sets of requirements.

A build expression is made up of variables and functions. Variables store values and are denoted by a leading $, such as $at_time or $project_name. Functions, also called rules, are executed to produce results which can be assigned to a variable or passed directly to another rule as an argument.

Interpretation

A build expression is executed or interpreted by an interpreter to produce a BuildPlan, which describes the steps necessary to build the artifacts requested by the build expression.

The interpreter executes the build expression by evaluating its rules and variables. Interpreting a build expression involves the following 2 primary steps. The first is constructing a root context, a set of variable and rule definitions, that the interpreter has access to. The second is using this root context to evaluate the build expression.

The Root Context

The root context is the top level context during interpretation. It sets the definitions for variables and rules before interpretation of a build expression has started.

The root context contains a set of variable definitions that can be used in build expressions. The variables defined in the root context are:

$at_time
- The value of $at_time depends on the context provided with the build expression, e.g. Commit.atTime or Project.evaluate()'s atTime parameter.
$commit_id
$organization_id
$organization_name
$project_id
$project_name

These variables can be used in build expressions and often are. For example, rules that have an at_time parameter typically set the default value of that parameter to the $at_time variable, which will use the value defined in the root context unless an $at_time variable is defined in a closer context.

The root context contains definitions for all rules (functions) that are part of the build expression. It is this context that provides the definition of each rule to the interpreter. For example, the root context will contain the definition of the solve() rule.

Rule Versioning

To provide reproducible results when interpreting a build expression, the definitions in the root context must not change between interpretations of the same build expression. This is in opposition of also desiring a system where rules can be added, removed or updated. To obtain both of these properties rules are versioned. The version of a rule put into the root context is determined by value of the root context's $at_time variable.

When a new version of rule is created it is assigned a creation timestamp. This timestamp is the earliest point in time at which that version of the rule can be used in a build expression. When the interpreter builds the root context it adds the greatest version of each rule that was created before or at (<=) the $at_time variable.

For example, given a rule foo(), which two versions V1 and V2, where v1 was created at time T1 and V2 was created at time T2.

At time T0, foo() is not in the root context because its earliest, version V1, doesn't exist yet
At time T1, foo() V1 is added to the root context
At time T2, foo() V2 is added to the root context
At time T3, foo() V2 is added to the root context and will continue to be until a V3 version of foo() is created

Existing Operations (functions)

Operations and rules are similar. The difference is that rules are intended, at some point, to be definable by users while operations form the core of the build expr language and cannot be defined by users. Typically, rules are defined in terms of operations and other rules, while an operation cannot be defined in terms of a rule.

merge(left: BuildPlan, right: BuildPlan) -> BuildPlan
merge_set(set: frozenset[BuildPlan]) -> BuildPlan

Existing Rules (functions)

Selection

select_ingredient(src: BuildPlan[Source], namespace: string, name: string) -> BuildPlan[Source]
- creates a new build plan that contains only the selected source
- the selected source must be a terminal of the src build plan

Solving

solve(at_time: DateTime, requirements: Set[Requirement], platforms: Set[String], solver_version: int | None = None) -> BuildPlan[Source]
- resolves the dependencies of requirements for a given set of platforms.
- The solver_version argument is optional and can be used to select a specific version of the solver to use:
  - solver_version 2 (the default) selects the old and slow, but battle-tested solver.,
  - solver_version 3 results in a faster solve where the build and runtime closure are solved together, which is technically too constrictive.
  - solver_version 4 results in a fast and correct solve which only resolves the runtime closure of the requirements. Build closure are solved for in the state_tool_artifacts rule.

Rules to build artifacts

state_tool_artifacts(src: BuildPlan[Source]) -> BuildPlan[Star]
- builds State Tool artifacts from every source in the runtime closure of the src buildplan
- Variant: state_tool_artifacts(src: BuildPlan[Wheel] -> BuildPlan[Star])
  - builds State Tool artifacts from every python wheel reachable in the runtime closure of the src BuildPlan
- Note: if the input buildplan only contains runtime dependencies, the function recursively issues subsequent solves for build closures for every artifact. If both build- and runtime dependencies are present in the src, this function delegates the BuildPlan generation to the coupled_state_tool_artifacts rule.
coupled_state_tool_artifacts(src: BuildPlan[Source]) -> BuildPlan[Star]
- builds State Tool artifacts from every source in the combined runtime and build closure of the src buildplan
- the src BuildPlan must be created from a solve with solver_version==3.
community_artifacts(src: BuildPlan[Source]) -> BuildPlan[Wheel]
- turns all sources of python sdists into wheels by downloading them from PyPI
wheel_artifacts(src: BuildPlan[Source]) -> BuildPlan[Wheel]
- turns all sources of python sdists into wheels by building them into wheels with the wheel_builder
make_wheel(src: BuildPlan[Source]) -> BuildPlan[Wheel]
- builds a wheel for each platform terminal in the src build plan
- although the src build plan can have terminals for multiple platforms, each platform terminal must contain only the same single source

Examples: BuildScripts creating State Tool Artifacts from solves

The following examples show how solve and the state_tool_artifacts can be combined to resolve build closures.

Coupled build-/runtime closures

The (current) default behavior is to solve for a combined build-/runtime closure. All of the following BuildExpressions are equivalent:

sources = solve(
  at_time=at_time,
  requirements=Req(name="flask", namespace="language/python"),
  platforms=["7c998ec2-7491-4e75-be4d-8885800ef5f2"],
  solver_version=3,
)
runtime = state_tool_artifacts(
  src=sources
)
main = runtime

sources = solve(
  at_time=at_time,
  requirements=Req(name="flask", namespace="language/python"),
  platforms=["7c998ec2-7491-4e75-be4d-8885800ef5f2"],
)
runtime = state_tool_artifacts(
  src=sources
)
main = runtime

sources = solve(
  at_time=at_time,
  requirements=Req(name="flask", namespace="language/python"),
  platforms=["7c998ec2-7491-4e75-be4d-8885800ef5f2"],
  solver_version=3,
)
runtime = coupled_state_tool_artifacts(
  src=sources
)
main = runtime

Both these variants, issue a solve for a combined build-/runtime closure and then transform the resolved information into a BuildPlan. Note that the state_tool_artifacts rule actually delegates work to the coupled_state_tool_artifacts rule.

Separated build-/runtime closures

If you indeed want to solve with separate build-/runtime closures, try the following BuildScript:

sources = solve(
  at_time=at_time,
  requirements=Req(name="flask", namespace="language/python"),
  platforms=["7c998ec2-7491-4e75-be4d-8885800ef5f2"],
  solver_version=4,
)
runtime = state_tool_artifacts(
  src=sources
)
main = runtime

In this case, the solve only resolves the runtime closure. Runtime-only solves have a higher success rate, as they carry less conflict opportunities.

Here, the state_tool_artifacts rule needs to issue subsequent solves for every build closure of sources in the runtime closure. This process repeats recursively until runtime closures for every artifact needed in the build process are resolved.

Note, that this BuildScript is still in an experimental state, because the inventory data needs to be adapted to support all of these cases.

Likely, once we deem the behavior stable, it will become the default way to create new artifacts.

Rules for scanned images

These rules are used when automated scanning of a deployment is responsible for creating or updating a project.

scanned_image (
  registry: str,
  based_on: str,
  image_name: str,
  manifest_digest: str,
  os_arch: str,
  tags: tuple[str, ...],
  contents: frozenset[str],
  scan_uri: str,
  at_time: datetime | Var = Var("at_time),
) -> BuildPlan[MissingSource|Source]

Creates a build plan containing a single Source if the image can be found in the inventory data or a single MissingSource from the scanned data if it cannot.
contents is a set of PURLs found in the image by the scanner

replace_image(
  src: BuildPlan[MissingSource|Source],
  manifests: frozenset[str],
  namespace: str,
  name: str,
  version: str,
  at_time: datetime | Var = Var("at_time),
) -> BuildPlan[MissingSource|Source]

Replaces all images in src whose manifest is in manifests with the image specified by namespace, name and version from the inventory data.

Packager rules

Packager rules are rules that build a single artifact (a bundled package) of the terminals of a source BuildPlan. Current packagers are:

linux_installer(src: BuildPlan[Star], platform: String, name: String, at_time: DateTime | Var = Var("at_time"), memory: Int = 4000) -> BuildPlan[StateInstaller]
- bundles State Tool artifacts into a self-extractable executable that internally uses the State Tool to unpack and install the artifacts. The platform argument references the linux platform for which to package the artifacts.
windows_installer(src: BuildPlan[Star], platform: String, name: String, at_time: DateTime | Var = Var("at_time"), memory: Int = 4000) -> BuildPlan[WindowsStateInstaller]
- bundles State Tool artifacts into a self-extractable executable that internally uses the State Tool to unpack and install the artifacts. The platform argument references the windows platform for which to package the artifacts. The generated executable is authenticode signed.
docker(src: BuildPlan[Star], platform: String, name: string, base_image: String, at_time: DateTime | Var = Var("at_time"), memory: Int = 4000, env: Tuple[String] = ()) -> BuildPlan[ClouderaDockerContainer]
- bundles State Tool artifacts into a docker container that is highly specialized for use on the Cloudera Platform. The platform argument references the linux platform for which to package the artifacts.
relocate_and_zip(src: BuildPlan[Star], platform: String, name: String, at_time: DateTime | Var = Var("at_time"), memory: Int = 4000) -> BuildPlan[ZipFile]
- state installs the build plan's runtime closure into /usr and then zips the resulting directory structure into a single zip file.

Publisher rules

Publisher rules publish one or more existing artifacts to an artifact repository and produce a publish receipt as a result.

pypi_publisher(src: BuildPlan[Wheel], pypi_uri: String = "pypi.org", audience: String = "pypi", attempt: Int = 1) -> BuildPlan[PyPiPublishReceipt]
- publishes a terminal wheel artifact to the specified pypi_uri. If the attempt argument is incremented, a new publish actions will be scheduled, even if a previous publish action was scheduled for the src.

Security rules

Security rules provide security related actions such as credentials or authorization tokens to required by other rules.

oidc_claims() -> OIDCClaims
- returns project specific OIDC claims that can be inserted into a rule to create a build step that authenticates as a project-specific build of this artifact.

Signing rules

Signing rules cryptographically sign artifacts using different methods that can later be verified to know that an artifact was built by ActiveState.

```
authenticode_sign_stars(
  src: BuildPlan[Star],
  at_time: datetime | Var = Var("at_time),
) -> BuildPlan[Star[Authenticode Signed]]
```
- Authenticode signs all executables (EXEs) and dynamic link libraries (DLLs) in every artifact in the runtime closure of every Windows platform in the src BuildPlan.
- Authenticode signed artifacts can be identified by the MIME type parameter signed=authenticode.
  - For example, a state tool artifact (Star) has a MIME type of application/x.artifact, while an authenticode signed Star has a MIME type of application/x.artifact;signed=authenticode

Constructor operations

Constructor operations are functions that construct a new object and hence are in camel-case while regular functions are in snake-case.

BuildFlag(name: str, value: str | None = None) -> BuildFlag
Any() -> Any UnaryConstraint(value: str) -> UnaryConstraint for UnaryConstraint in (Eq, Ne, Gt, Gte, Lt, Lte) BinaryConstraint(left: Constraint, right: Constraint) -> BinaryConstraint for BinaryConstraint in (AndOp, OrOp)
Req(name: str, namespace: str, version: ast.Constraint = Any()) -> Requirement
ResourceRequirements(host_attributes: frozenset[tuple[str, str]] = frozenset(), memory: int | None = None, cpus: float | None = None) -> ResourceRequirements
Revision(name: str, revision_id: str) -> Requirement`

Deprecated rules to build artifacts

The following functions can be used to ask for artifacts, but they are deprecated and will eventually be disallowed for use in new commits.

camel(src: BuildPlan[Source]) -> BuildPlan[CamelStar]
- builds sources with the camel builder (CamelStar => CamelStateToolArtifacts)
pre_platform_installer(src: BuildPlan[Source]) -> BuildPlan[PrePlatformInstaller]
- builds the resolved pre-platform installer (not installable by the State Tool)
state_tool_artifacts_v1(src: BuildPlan[Source]) -> BuildPlan[Star]
- builds State Tool artifacts with artifact_ids compatible with all State Tools.

Current restrictions

Heuristics rewriting the BuildExpr

We apply the following heuristics that rewrite the BuildExpression. Users cannot overwrite this behavior.

The Build System camel/pre_platform_installer or state_tool_artifacts is selected based on the selected language core version.
(Soon to be released) If the project for which a new commit is requested, is in a free tier organization, the community_artifacts rule is going to be applied. This heuristic effectively disallows free tier users to build python artifacts from source.

Enforcement of build maker functions

The functions camel and state_tool_artifacts{_v1,} may work even if the the requirements allow only a build with the wrong build system. If the heuristic from above fails, users can add a requirement for language/alternative-built-language or language/camel-built-language to force the heuristic to select the correct build system - as a workaround.

Examples

Simple solve

{
  "let": {
    "sources": {
      "solve": {
        "at_time": "2023-09-01T16:41:06.922Z",
        "platforms": [
          "7c998ec2-7491-4e75-be4d-8885800ef5f2"
        ],
        "requirements": [
          {
            "name": "python",
            "namespace": "language",
            "version_requirements": [
              {
                "comparator": "gte",
                "version": "3.10"
              }
            ]
          }
        ]
      }
    },
    "runtime": {
      "state_tool_artifacts": {
        "src": "$sources",
      }
    },
    "in": "$runtime"
  }
}

Camel build

{
  "let": {
    "sources": {
      "solve": {
        "at_time": "2023-09-01T16:41:06.922Z",
        "platforms": [
          "7c998ec2-7491-4e75-be4d-8885800ef5f2"
        ],
        "requirements": [
          {
            "name": "python",
            "namespace": "language",
            "version_requirements": [
              {
                "comparator": "lt",
                "version": "3.8"
              }
            ]
          }
        ]
      }
    },
    "runtime": {
      "camel": {
        "src": "$sources",
      }
    },
    "in": "$runtime"
  }
}

Add installer

{
  "let": {
    "sources": {
      "solve": {
        "at_time": "2023-09-01T16:41:06.922Z",
        "platforms": [
          "7c998ec2-7491-4e75-be4d-8885800ef5f2"
        ],
        "requirements": [
          {
            "name": "python",
            "namespace": "language",
            "version_requirements": [
              {
                "comparator": "gte",
                "version": "3.10"
              }
            ]
          }
        ]
      },
    },
    "runtime": {
      "state_tool_artifacts": {
        "src": "$sources",
      }
    },
    "installer": {
     "windows_installer": {
       "src": "$runtime",
       "platform": "7c998ec2-7491-4e75-be4d-8885800ef5f2",
       "name": "my win 10 runtime"
     }
    },
    "in": "$installer"
  }
}

Add relocated zip installer

{
  "let": {
    "sources": {
      "solve": {
        "at_time": "2023-09-01T16:41:06.922Z",
        "platforms": [
          "7c998ec2-7491-4e75-be4d-8885800ef5f2"
        ],
        "requirements": [
          {
            "name": "python",
            "namespace": "language",
            "version_requirements": [
              {
                "comparator": "gte",
                "version": "3.10"
              }
            ]
          }
        ]
      },
    },
    "runtime": {
      "state_tool_artifacts": {
        "src": "$sources",
      }
    },
    "zip": {
     "relocate_and_zip": {
       "src": "$runtime",
       "platform": "7c998ec2-7491-4e75-be4d-8885800ef5f2",
       "name": "perl runtime"
     }
    },
    "in": "$zip"
  }
}

Publish wheel

{
                            "let": {
                              "sources": {
                                "solve": {
                                  "at_time": "2023-09-01T16:41:06.922Z",
                                  "platforms": [
                                    "7c998ec2-7491-4e75-be4d-8885800ef5f2"
                                  ],
                                  "requirements": [
                                    {
                                      "name": "my-python-module",
                                      "namespace": "language/python",
                                    }
                                  ]
                                },
                              },
                              "wheel": {
                               "wheel_artifacts": {
                                 "src": "$sources"
                               }
                              },
                              "publish": {
                                "pypi_publisher": {
                                  "src": "$wheel"
                                }
                              },
                              "in": "$publish"
                            }
                          }
                          
                          ### Publish wheel with make_wheel
                          
                          ```json
                          {
                            "let": {
                              "sources": {
                                "solve": {
                                  "at_time": "2023-09-01T16:41:06.922Z",
                                  "platforms": [
                                    "7c998ec2-7491-4e75-be4d-8885800ef5f2"
                                  ],
                                  "requirements": [
                                    {
                                      "name": "my-python-module",
                                      "namespace": "language/python",
                                    }
                                  ]
                                },
                              },
                              "runtime": {
                                "state_tool_artifacts": {
                                  "src": "$sources"
                                }
                              },
                              "wheel_source": {
                               "select_ingredient": {
                                 "src": "$source",
                                 "namespace": "language/python",
                                 "name": "my-python-module"
                               }
                              },
                              "wheels": {
                                "make_wheel": {
                                  "src": "$wheel_source"
                                }
                              },
                              "publish": {
                                "pypi_publisher": {
                                  "src": "$wheels"
                                }
                              },
                              "in": "$runtime"
                            }
                          }

Example

BuildExpr

Types

BuildExprError

Description

An error that can be correlated back to an element in the build expression.

Fields

Field Name	Description
`message` - `String!`	A message describing the error that occurred.
`buildExprPath` - `[String!]!`	The path in the build expression to the source of the error.

Possible Types

BuildExprError Types
`TargetNotFound`
`RemediableError`
`GenericBuildExprError`
`GenericSolveError`
`RemediableSolveError`

Example

{
  "message": "abc123",
  "buildExprPath": ["xyz789"]
}

Types

BuildExprOrCommitInput

Fields

Input Field	Description
`buildExpr` - `BuildExpr`	Specify a commit OR a `BuildExpr` from which to get a BuildPlan to compare. One of `commitId` or `buildExpr` must be provided. When providing a `buildExpr`, `atTime` may also be provided (`atTime` is ignored in combination with a `commitId`).
`atTime` - `DateTime`
`commitId` - `ID`

Example

{
  "buildExpr": BuildExpr,
  "atTime": "2007-12-03T10:15:30Z",
  "commitId": "4"
}

Types

BuildExprRemediation

Description

EXPERIMENTAL FEATURE: Remediable Error This type may be modified or removed from the schema without notice..

A remediation to update the build expression being used.

Fields

Field Name	Description
`description` - `String!`
`suggestedPriority` - `Int!`
`suggestedPatch` - `[Diff!]!`

Example

{
  "description": "abc123",
  "suggestedPriority": 123,
  "suggestedPatch": [Diff]
}

Types

BuildExprValue

Description

A value in a BuildExpr.

This value can be any valid single value in a BuildExpr such as an Int, String, Ap, Let or Var. The value is encoded as the JSON representation of that value as it would be in a BuildExpr.

Example

BuildExprValue

Types

BuildLogId

Types

Union Types
`CamelBuildId`
`AltBuildId`

Example

CamelBuildId

Types

BuildPartial

Description

The final state for a build plan's build that has finished execution and only parts of the plan were executed.

The executed build plan contained incomplete information, such as MissingSource nodes, that prevent the entire plan from being executed resulting in partial execution. The incomplete parts of the plan, such as artifacts that depend on a MissingSource, were not built and cannot be built.

Fields

Field Name	Description
`status` - `BuildPlanStatus!`
`buildLogIds` - `[BuildLogId!]!`
`components` - `[Component!]!`
`nodes` - `[Node!]!`
`steps` - `[Step!]!`
`terminals` - `[TaggedNodes!]!`
`resolvedRequirements` - `[ResolvedRequirement!]!`

Example

{
  "status": "PLANNING",
  "buildLogIds": [CamelBuildId],
  "components": [Component],
  "nodes": [Source],
  "steps": [Step],
  "terminals": [TaggedNodes],
  "resolvedRequirements": [ResolvedRequirement]
}

Types

BuildPlanStatus

Values

Enum Value	Description
`PLANNING`	The BuildPlan is being created/solved for.
`PLANNED`	The BuildPlan has been planned (created) but has not been submitted to be built.
`STARTED`	BuildPlan is in the process of being built.
`COMPLETED`	BuildPlan has been submitted and the build terminated. This does not indicate that the BuildPlan was built successfully only that a build has been attempted and completed.

Example

"PLANNING"

Types

BuildPlanned

Description

A build in the planned phase.

The build expression has finished being interpreted and a build plan has been created but not yet started.

Fields

Field Name	Description
`status` - `BuildPlanStatus!`
`components` - `[Component!]!`
`nodes` - `[Node!]!`
`steps` - `[Step!]!`
`terminals` - `[TaggedNodes!]!`
`resolvedRequirements` - `[ResolvedRequirement!]!`

Example

{
  "status": "PLANNING",
  "components": [Component],
  "nodes": [Source],
  "steps": [Step],
  "terminals": [TaggedNodes],
  "resolvedRequirements": [ResolvedRequirement]
}

Types

BuildPlanning

Description

A build in the planning phase.

The build expression is being interpreted and a build plan is being created.

Fields

Field Name	Description
`status` - `BuildPlanStatus!`
`components` - `[Component!]!`
`nodes` - `[Node!]!`
`steps` - `[Step!]!`
`terminals` - `[TaggedNodes!]!`
`resolvedRequirements` - `[ResolvedRequirement!]!`

Example

{
  "status": "PLANNING",
  "components": [Component],
  "nodes": [Source],
  "steps": [Step],
  "terminals": [TaggedNodes],
  "resolvedRequirements": [ResolvedRequirement]
}

Types

BuildRelationship

Description

A relationship to a build node.

Fields

Field Name	Description
`type` - `ComponentRelationshipType!`
`nodeId` - `ID!`

Example

{"type": "DIRECT", "nodeId": "4"}

Types

BuildResult

Types

Union Types
`BuildPlanning`
`BuildPlanned`
`BuildStarted`
`BuildPartial`
`BuildCompleted`
`PlanningError`

Example

BuildPlanning

Types

BuildStarted

Description

The build plan is being executed.

Fields

Field Name	Description
`status` - `BuildPlanStatus!`
`buildLogIds` - `[BuildLogId!]!`
`components` - `[Component!]!`
`nodes` - `[Node!]!`
`steps` - `[Step!]!`
`terminals` - `[TaggedNodes!]!`
`resolvedRequirements` - `[ResolvedRequirement!]!`
`startedAt` - `DateTime!`

Example

{
  "status": "PLANNING",
  "buildLogIds": [CamelBuildId],
  "components": [Component],
  "nodes": [Source],
  "steps": [Step],
  "terminals": [TaggedNodes],
  "resolvedRequirements": [ResolvedRequirement],
  "startedAt": "2007-12-03T10:15:30Z"
}

Types

CVEDiff

Fields

Field Name	Description
`cveID` - `String!`
`description` - `String!`
`severity` - `String!`
`status` - `CVEDiffStatus!`
`ingredientIdentifier` - `[IngredientIdentifier!]!`

Example

{
  "cveID": "abc123",
  "description": "xyz789",
  "severity": "xyz789",
  "status": "ADDED",
  "ingredientIdentifier": [IngredientIdentifier]
}

Types

CVEDiffStatus

Values

Enum Value	Description
`ADDED`
`REMOVED`
`UNCHANGED`

Example

"ADDED"

Types

CamelBuildId

Fields

Field Name	Description
`id` - `ID!`
`platformId` - `ID!`	The platform id associated to the build log.

Example

{
  "id": "4",
  "platformId": "4"
}

Types

CategorizedLicense

Description

Licenses exprs grouped by LicenseCategory

Fields

Field Name	Description
`category` - `LicenseCategory!`
`license` - `String!`

Example

{
  "category": "MAINTAINER_DECLARED",
  "license": "abc123"
}

Types

Commit

Description

commit information

NOTE: This is only inspired by what the mediator does.

I changed some of the field names to create some convention that we use throughout this schema: For example: the names in the mediator suddenly have snake case naming for the CommitType

Fields

Field Name	Description
`commitId` - `ID!`	The unique identifier for this commit.
`parentId` - `ID`	Commit id for the previous commit in the project. Will be null if this is the first commit of the project.
`description` - `String!`	Commit message submitted by the author.
`added` - `DateTime!`	Timestamp of when this commit was created.
`atTime` - `DateTime!`	The timestamp selects rule versions and sets the `$at_time` variable in the root context. See the BuildExpr documentation for more information about rule versioning and the root context.
`attestations` - `CommitAttestationsResult!`	The attestations
`expr` - `BuildExpr`	This is the build expression represented by this Commit. If it is null, a GraphQL error should be in the final response, explaining why this request failed.
`build` - `BuildResult!`	build returns the progress of the build or the build plan. The target parameter allows the execution target of the build expression to be specified. When the build expression is a Let, the in value is the execution target. By providing a target argument to build, a different target will be executed. The value of target must be a valid value in the Let's arguments or a PlanningError will be returned. For example, given this build expression: let: python = ... perl = ... in: $python Without specifying a target, "python" will be executed and its build returned. Setting target to "perl", will execute the perl definition in the Let instead, allowing one build expression to contain multiple builds.
Arguments `target` - `String`

Example

{
  "commitId": 4,
  "parentId": 4,
  "description": "xyz789",
  "added": "2007-12-03T10:15:30Z",
  "atTime": "2007-12-03T10:15:30Z",
  "attestations": CommitAttestations,
  "expr": BuildExpr,
  "build": BuildPlanning
}

Types

CommitAttestations

Fields

Field Name	Description
`spdx` - `URI!`
Arguments `version` - `String!`

Example

{"spdx": URI}

Types

CommitAttestationsResult

Types

Union Types
`CommitAttestations`
`FeatureNotEnabled`

Example

CommitAttestations

Types

CommitHasNoParent

Description

An error occurred when trying to revert a commit that has no parent commit.

Fields

Field Name	Description
`message` - `String!`
`commitId` - `ID!`
`targetCommitId` - `String!`

Example

{
  "message": "xyz789",
  "commitId": 4,
  "targetCommitId": "xyz789"
}

Types

CommitNotInTargetHistory

Description

An error occurred when trying to revert a commit that does not appear in the history of the target.

Fields

Field Name	Description
`message` - `String!`
`commitId` - `ID!`
`targetCommitId` - `String!`

Example

{
  "message": "xyz789",
  "commitId": "4",
  "targetCommitId": "xyz789"
}

Types

CommitResult

Types

Union Types
`Commit`
`NotFound`

Example

Commit

Types

Comparator

Values

Enum Value	Description
`EQ`
`GT`
`GTE`
`LT`
`LTE`
`NE`

Example

"EQ"

Types

Component

Description

A component that is part of this commit.

A component is a named and versioned item that can be accessed is some fashion via this commit's build plan. The source of the component may be downloadable or an artifact may provide access to running or executing the component. An image may provide access to a component by running the image.

Fields

Field Name	Description
`componentId` - `ID!`
`purl` - `PackageURL!`
`namespace` - `String!`
`name` - `String!`
`version` - `String!`
`relatesTo` - `[BuildRelationship!]!`	The build nodes that are related to this component.
`vulnerabilities` - `[Vulnerability!]!`	The component vulnerabilities

Example

{
  "componentId": "4",
  "purl": PackageURL,
  "namespace": "xyz789",
  "name": "abc123",
  "version": "xyz789",
  "relatesTo": [BuildRelationship],
  "vulnerabilities": [Vulnerability]
}

Types

ComponentDiff

Fields

Field Name	Description
`namespace` - `String!`
`name` - `String!`
`before` - `ComponentDiffState`
`after` - `ComponentDiffState`

Example

{
  "namespace": "abc123",
  "name": "abc123",
  "before": ComponentState,
  "after": ComponentState
}

Types

ComponentDiffState

Types

Union Types
`ComponentState`
`IngredientState`

Example

ComponentState

Types

ComponentRelationship

Description

A relationship to a Component.

Fields

Field Name	Description
`type` - `ComponentRelationshipType!`
`componentId` - `ID!`

Example

{"type": "DIRECT", "componentId": 4}

Types

ComponentRelationshipType

Values

Enum Value	Description
`DIRECT`	Component describes the build node.
`PROVIDED_BY_BUILD_NODE`	The build node is a container that provides this component.

Example

"DIRECT"

Types

ComponentState

Fields

Field Name	Description
`version` - `String!`

Example

{"version": "abc123"}

Types

CreateProjectInput

Fields

Input Field	Description
`organization` - `String!`
`project` - `String!`
`private` - `Boolean!`	If true, create a private project.
`expr` - `BuildExpr!`
`atTime` - `DateTime`	The atTime of the first commit in the created project. Selects rule versions and sets the `$at_time` variable in the root context. If null is passed, it will be treated as if the value "max_verified" had been passed. See the BuildExpr documentation for more information about rule versioning and the root context.
`description` - `String`

Example

{
  "organization": "abc123",
  "project": "abc123",
  "private": false,
  "expr": BuildExpr,
  "atTime": "2007-12-03T10:15:30Z",
  "description": "abc123"
}

Types

CreateProjectResult

Types

Union Types
`ProjectCreated`
`AlreadyExists`
`NotFound`
`ParseError`
`ValidationError`
`Forbidden`
`InvalidInput`

Example

ProjectCreated

Types

CreatedIngredientVersionRevision

Fields

Field Name	Description
`ingredientID` - `ID!`
`ingredientVersionID` - `ID!`
`ingredientVersionRevisionID` - `ID!`
`revision` - `Int!`
`createdAt` - `DateTime!`

Example

{
  "ingredientID": "4",
  "ingredientVersionID": "4",
  "ingredientVersionRevisionID": "4",
  "revision": 123,
  "createdAt": "2007-12-03T10:15:30Z"
}

Types

DateTime

Description

An ISO-8601 date and time in UTC with microsecond precision. Example: 2024-01-24T19:36:57.123456Z

It can also be set to "now" or "max_verified":

"now" selects the timestamp of the latest inserted ingredient revision in the catalog at that time.
"max_verified" selects the latest timestamp at which ActiveState verified the correct behavior of some commonly selected inventory data and rules.

Example

"2007-12-03T10:15:30Z"

Types

DependencyConditionInput

Fields

Input Field	Description
`name` - `String!`
`namespace` - `String!`
`versionRequirements` - `VersionRequirements`

Example

{
  "name": "abc123",
  "namespace": "abc123",
  "versionRequirements": VersionRequirements
}

Types

DependencyInput

Fields

Input Field	Description
`name` - `String!`
`namespace` - `String!`
`type` - `String`
`versionRequirements` - `VersionRequirements`
`conditions` - `[DependencyConditionInput!]`

Example

{
  "name": "xyz789",
  "namespace": "abc123",
  "type": "xyz789",
  "versionRequirements": VersionRequirements,
  "conditions": [DependencyConditionInput]
}

Types

Diff

Description

A build expression diff.

Fields

Field Name	Description
`buildExprPath` - `[String!]!`	The path to the AST node in the build expression to apply this diff to.
`action` - `DiffOperation!`	The diff action to take.
`value` - `BuildExprValue!`	The value to be deleted, inserted or replaced.
`replacingValue` - `BuildExprValue`	The new value to replace the existing value. This field is not null only when action is REPLACE. If action is DELETE or INSERT this field will be null.

Example

{
  "buildExprPath": ["xyz789"],
  "action": "DELETE",
  "value": BuildExprValue,
  "replacingValue": BuildExprValue
}

Types

DiffOperation

Values

Enum Value	Description
`DELETE`
`INSERT`
`REPLACE`

Example

"DELETE"

Types

Error

Description

Error is an interface for all user-actionable errors

Fields

Field Name	Description
`message` - `String!`

Possible Types

Error Types
`AlreadyExists`
`FeatureNotEnabled`
`NoChangeSinceLastCommit`
`NotFound`
`Forbidden`
`HeadOnBranchMoved`
`FastForwardError`
`NoCommonBaseFound`
`NoUpstreamBranch`
`CommitNotInTargetHistory`
`CommitHasNoParent`
`MultiPartUploadFileExpected`
`InvalidInput`
`InvalidIngredientVersion`
`InvalidNamespaceName`
`MergeConflict`
`RevertConflict`
`ImpactReportError`
`TargetNotFound`
`RemediableError`
`ParseError`
`ValidationError`
`PlanningError`
`GenericBuildExprError`
`GenericSolveError`
`RemediableSolveError`

Example

{"message": "xyz789"}

Types

ErrorWithSubErrors

Description

An error that contains one or more other errors.

Fields

Field Name	Description
`message` - `String!`
`subErrors` - `[BuildExprError!]!`

Possible Types

ErrorWithSubErrors Types
`ParseError`
`ValidationError`
`PlanningError`

Example

{
  "message": "abc123",
  "subErrors": [BuildExprError]
}

Types

EvaluateResult

Types

Union Types
`BuildPlanning`
`BuildPlanned`
`ParseError`
`ValidationError`
`PlanningError`

Example

BuildPlanning

Types

FastForwardError

Description

An error occurred when using the FastForward merge strategy, because the HEAD on target is not a commit on other.

Fields

Field Name	Description
`message` - `String!`
`targetVcsRef` - `ID!`
`otherVcsRef` - `ID!`

Example

{
  "message": "xyz789",
  "targetVcsRef": "4",
  "otherVcsRef": "4"
}

Types

FeatureNotEnabled

Fields

Field Name	Description
`message` - `String!`

Example

{"message": "xyz789"}

Types

FeaturesInput

Fields

Input Field	Description
`name` - `String!`
`namespace` - `String!`
`version` - `String!`

Example

{
  "name": "xyz789",
  "namespace": "abc123",
  "version": "xyz789"
}

Types

File

Fields

Field Name	Description
`url` - `URI!`
`checksum` - `String!`
`attestations` - `AttestationsResult!`

Possible Types

File Types
`Source`
`ArtifactSucceeded`

Example

{
  "url": URI,
  "checksum": "xyz789",
  "attestations": Attestations
}

Types

FileUpload

Example

FileUpload

Types

Float

Description

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

Example

987.65

Types

Forbidden

Description

An error occurred because an operation was forbidden.

Fields

Field Name	Description
`message` - `String!`
`operation` - `String!`
`resource` - `String!`

Example

{
  "message": "abc123",
  "operation": "xyz789",
  "resource": "xyz789"
}

Types

GenericBuildExprError

Description

An error that occurs at any stage of the BuildExpression evaluation phase.

Simplest implementation of BuildExprError

Fields

Field Name	Description
`message` - `String!`
`buildExprPath` - `[String!]!`

Example

{
  "message": "xyz789",
  "buildExprPath": ["xyz789"]
}

Types

GenericSolveError

Description

Minimal implementation of the SolveError interface

Fields

Field Name	Description
`message` - `String!`
`path` - `String!`	Replaced by buildExprPath which does not require parsing. Must exist until state tool v0.44.* is deprecated.
`buildExprPath` - `[String!]!`
`isTransient` - `Boolean!`
`validationErrors` - `[SolveErrorValidationError!]!`

Example

{
  "message": "abc123",
  "path": "xyz789",
  "buildExprPath": ["xyz789"],
  "isTransient": false,
  "validationErrors": [SolveErrorValidationError]
}

Types

HeadOnBranchMoved

Description

An error occurred during commit creation, because the parentCommit is not HEAD of branch anymore.

Fields

Field Name	Description
`message` - `String!`
`commitId` - `ID!`
`branchId` - `ID!`

Example

{
  "message": "abc123",
  "commitId": 4,
  "branchId": 4
}

Types

HostAttribute

Fields

Field Name	Description
`name` - `String!`
`value` - `String!`

Example

{
  "name": "abc123",
  "value": "xyz789"
}

Types

ID

Description

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.

Example

"4"

Types

ImpactReport

Fields

Field Name	Description
`buildBefore` - `BuildPlanned!`
`buildAfter` - `BuildPlanned!`
`components` - `[ComponentDiff!]!`
`ingredients` - `[IngredientDiff!]!`	Replaced by ImpactReport.components
`cves` - `[CVEDiff!]!`

Example

{
  "buildBefore": BuildPlanned,
  "buildAfter": BuildPlanned,
  "components": [ComponentDiff],
  "ingredients": [IngredientDiff],
  "cves": [CVEDiff]
}

Types

ImpactReportBuildResult

Types

Union Types
`BuildPlanned`
`BuildPlanning`
`ParseError`
`ValidationError`
`PlanningError`
`NotFound`
`InvalidInput`

Example

BuildPlanned

Types

ImpactReportError

Description

An error on requesting an impact report, containing success or error information about both inputs or their resultant build plans

Fields

Field Name	Description
`message` - `String!`
`buildBefore` - `ImpactReportBuildResult!`
`buildAfter` - `ImpactReportBuildResult!`

Example

{
  "message": "xyz789",
  "buildBefore": BuildPlanned,
  "buildAfter": BuildPlanned
}

Types

ImpactReportInput

Fields

Input Field	Description
`organization` - `String!`
`project` - `String!`
`buildExprOrCommit` - `BuildExprOrCommitInput!`

Example

{
  "organization": "abc123",
  "project": "xyz789",
  "buildExprOrCommit": BuildExprOrCommitInput
}

Types

ImpactReportResult

Types

Union Types
`ImpactReport`
`ImpactReportError`

Example

ImpactReport

Types

IngredientDiff

Fields

Field Name	Description
`namespace` - `String!`
`name` - `String!`
`before` - `IngredientState`
`after` - `IngredientState`

Example

{
  "namespace": "xyz789",
  "name": "xyz789",
  "before": IngredientState,
  "after": IngredientState
}

Types

IngredientIdentifier

Fields

Field Name	Description
`namespace` - `String!`
`name` - `String!`
`version` - `String!`

Example

{
  "namespace": "abc123",
  "name": "xyz789",
  "version": "xyz789"
}

Types

IngredientState

Fields

Field Name	Description
`version` - `String!`
`revision` - `Int!`
`ingredientID` - `ID!`
`ingredientVersionID` - `ID!`
`ingredientVersionRevisionID` - `ID!`
`isRequirement` - `Boolean!`	True if the ingredient is here to directly satisfy a requirement in the BuildExpr

Example

{
  "version": "abc123",
  "revision": 987,
  "ingredientID": 4,
  "ingredientVersionID": 4,
  "ingredientVersionRevisionID": "4",
  "isRequirement": true
}

Types

Int

Description

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

Example

Types

InvalidIngredientVersion

Description

An error indicating that the server rejected creating a requested ingredient version

Fields

Field Name	Description
`message` - `String!`
`validationErrors` - `[String!]!`

Example

{
  "message": "abc123",
  "validationErrors": ["xyz789"]
}

Types

InvalidInput

Description

An error indicating that the input given is invalid

Fields

Field Name	Description
`message` - `String!`

Example

{"message": "abc123"}

Types

InvalidNamespaceName

Description

An error indicating that the server rejected creating a namespace

Fields

Field Name	Description
`message` - `String!`
`validationErrors` - `[String!]!`

Example

{
  "message": "xyz789",
  "validationErrors": ["xyz789"]
}

Types

LicenseCategory

Description

Categories applied to license exprs based on how the license was declared or discovered.

Values

Enum Value	Description
`MAINTAINER_DECLARED`	A maintainer declared license
`SCANNED`	Discovered by an Open Source Software tool run against the packages source code after ingestion to find any additional licenses.
`ACTIVESTATE_FOUND`	A license found by ActiveState after ingestion in the package that was not declared by the maintainer.

Example

"MAINTAINER_DECLARED"

Types

MergeCommitInput

Fields

Input Field	Description
`organization` - `String!`	The organization for the project affected by the merge This field is required for access control
`project` - `String!`	The project affected by the merge This field is required for access control
`targetVcsRef` - `String!`	Branch name or commit id. If it is a branch name, the branch HEAD is forwarded to the new merged commit. If it is a commit id, the new merged commit is staged on top of the commit
`otherVcsRef` - `String!`	Branch name or commit id to be merged into the target
`strategy` - `MergeStrategy`	Merge strategy

Example

{
  "organization": "abc123",
  "project": "xyz789",
  "targetVcsRef": "xyz789",
  "otherVcsRef": "xyz789",
  "strategy": "Recursive"
}

Types

MergeCommitResult

Types

Union Types
`MergedCommit`
`MergeConflict`
`FastForwardError`
`NoCommonBaseFound`
`NotFound`
`ParseError`
`ValidationError`
`Forbidden`
`HeadOnBranchMoved`
`NoChangeSinceLastCommit`
`InvalidInput`

Example

MergedCommit

Types

MergeConflict

Description

An error for when merging commits creates conflicts

Fields

Field Name	Description
`message` - `String!`
`commonAncestorId` - `ID!`
`conflictPaths` - `[String!]!`

Example

{
  "message": "xyz789",
  "commonAncestorId": 4,
  "conflictPaths": ["xyz789"]
}

Types

MergeStrategy

Values

Enum Value	Description
`Recursive`	Applies a 3-way merge between two commits If changesets cannot be applied due to a conflict a MergeConflict error is returned
`RecursiveOverwriteOnConflict`	Applies the Recursive strategy. On conflicts it automatically prefers the changeset from the other branch.
`RecursiveKeepOnConflict`	Applies the Recursive strategy. On conflicts it automatically prefers the changeset from the target branch.
`FastForward`	Only applies the changesets from the other branch, if the target branch has not changed since creation of the other branch.

Example

"Recursive"

Types

MergeUpstreamBranchInput

Fields

Input Field	Description
`organization` - `String!`	The organization for the project affected by the merge This field is required for access control
`project` - `String!`	The project affected by the merge This field is required for access control
`targetBranch` - `String!`	The name of the branch to merge upstream changes into. The target branch's HEAD will be forwarded to the new merged commit.
`strategy` - `MergeStrategy`	Merge strategy. Default = `Recursive`

Example

{
  "organization": "xyz789",
  "project": "abc123",
  "targetBranch": "abc123",
  "strategy": "Recursive"
}

Types

MergeUpstreamBranchResult

Types

Union Types
`MergedCommit`
`MergeConflict`
`FastForwardError`
`NoUpstreamBranch`
`NotFound`
`ParseError`
`ValidationError`
`Forbidden`
`HeadOnBranchMoved`
`NoChangeSinceLastCommit`
`InvalidInput`

Example

MergedCommit

Types

MergedCommit

Description

The successful result of merging a commit.

Fields

Field Name	Description
`commit` - `Commit!`
`commonAncestorId` - `ID!`
`conflictPaths` - `[String!]!`

Example

{
  "commit": Commit,
  "commonAncestorId": "4",
  "conflictPaths": ["xyz789"]
}

Types

MissingSource

Description

A Source that may exist. It is not present in the platform's inventory.

Fields

Field Name	Description
`nodeId` - `ID!`
`namespace` - `String!`
`name` - `String!`
`version` - `String!`
`relatesTo` - `[ComponentRelationship!]!`	The components related to this MissingSource.

Example

{
  "nodeId": "4",
  "namespace": "xyz789",
  "name": "xyz789",
  "version": "abc123",
  "relatesTo": [ComponentRelationship]
}

Types

MultiPartUploadFileExpected

Description

An error indicating that a multipart upload request was expected

Fields

Field Name	Description
`message` - `String!`

Example

{"message": "xyz789"}

Types

NoChangeSinceLastCommit

Description

An error occurred while creating a commit, because the requested commit is identical to its parent

Fields

Field Name	Description
`message` - `String!`
`commitId` - `ID!`

Example

{
  "message": "xyz789",
  "commitId": "4"
}

Types

NoCommonBaseFound

Description

An error occurred when trying to merge commits that have no merge base.

Fields

Field Name	Description
`message` - `String!`
`targetVcsRef` - `ID!`
`otherVcsRef` - `ID!`

Example

{
  "message": "abc123",
  "targetVcsRef": 4,
  "otherVcsRef": "4"
}

Types

NoUpstreamBranch

Description

NoUpstreamBranch is an error that occurs when trying to merge changes from an upstream branch into a target branch but the target branch does not have an upstream branch.

Fields

Field Name	Description
`message` - `String!`
`targetBranch` - `String!`

Example

{
  "message": "xyz789",
  "targetBranch": "abc123"
}

Types

Node

Description

A Node in a BuildPlan.

A node represents something that exists before the build plan was created or something the build plan will produce when executed.

Types

Union Types
`Source`
`ArtifactSucceeded`
`ArtifactUnbuilt`
`ArtifactStarted`
`ArtifactTransientlyFailed`
`ArtifactPermanentlyFailed`
`MissingSource`

Example

Source

Types

NotFound

Description

An error indicating that a required resource resource of type type was not found

Fields

Field Name	Description
`message` - `String!`
`type` - `String!`
`resource` - `String!`
`mayNeedAuthentication` - `Boolean!`	a boolean flag indicating that the user may not be authorized to access the resource - if it actually exists

Example

{
  "message": "abc123",
  "type": "abc123",
  "resource": "abc123",
  "mayNeedAuthentication": false
}

Types

PackageURL

Description

A string in package URL (PURL) format as defined by the package url specification: https://github.com/package-url/purl-spec.

Example

PackageURL

Types

ParseError

Description

A wrapper for one or more errors that occur while parsing a build expression.

Fields

Field Name	Description
`message` - `String!`
`subErrors` - `[BuildExprError!]!`
`path` - `String!`	Replaced by the buildExprPath in subErrors. Must exist until state tool v0.44.* is deprecated.

Example

{
  "message": "abc123",
  "subErrors": [BuildExprError],
  "path": "abc123"
}

Types

Patch

Fields

Field Name	Description
`patchId` - `ID!`
`content` - `URI!`
`creationTimestamp` - `String!`
`description` - `String!`
`sequenceNumber` - `Int!`

Example

{
  "patchId": 4,
  "content": URI,
  "creationTimestamp": "xyz789",
  "description": "abc123",
  "sequenceNumber": 123
}

Types

PlanningError

Description

PlanningError refers to any error that occurs during the PLANNING phase.

If it occurs, no sensible BuildPlan will be generated.

Planning occurs after the build expression has been parsed and validated.

Fields

Field Name	Description
`message` - `String!`
`subErrors` - `[BuildExprError!]!`

Example

{
  "message": "xyz789",
  "subErrors": [BuildExprError]
}

Types

Project

Fields

Field Name	Description
`name` - `String!`	The project's short name.
`description` - `String!`	A description for the current project.
`evaluate` - `EvaluateResult!`	Evaluate a BuildExpr. IMPORTANT: The resulting BuildPlan might change after the graph is committed via `pushCommit`. This field is just a means to ensure that it can solve and to inspect the structure of the BuildPlan expected after a commit. A build will NOT be started. The atTime parameter selects rule versions and sets the `$at_time` variable in the root context. If null, the latest verified revision timestamp will be used. See the BuildExpr documentation for more information about rule versioning and the root context. The target parameter allows the execution target of the build expression to be specified. When the build expression is a Let, the in value is the execution target. By providing a target argument to build, a different target will be executed. The value of target must be a valid value in the Let's arguments or a PlanningError will be returned. For example, given this build expression: let: python = ... perl = ... in: $python Without specifying a target, "python" will be executed and its build returned. Setting target to "perl", will execute the perl definition in the Let instead, allowing one build expression to contain multiple builds.
Arguments `expr` - `BuildExpr!` `atTime` - `DateTime` `target` - `String`
`commit` - `CommitResult!`	commit has information about a specific commit for this project. If vcsRef is unset, the latest commit on the main branch can be returned. If vcsRef is set, it needs to be one of these commitId branch name tag name ...
Arguments `vcsRef` - `String`

Example

{
  "name": "xyz789",
  "description": "xyz789",
  "evaluate": BuildPlanning,
  "commit": Commit
}

Types

ProjectCreated

Fields

Field Name	Description
`project` - `Project!`
`branch` - `Branch!`
`commit` - `Commit!`

Example

{
  "project": Project,
  "branch": Branch,
  "commit": Commit
}

Types

ProjectResult

Types

Union Types
`Project`
`NotFound`

Example

Project

Types

PublishInput

Fields

Input Field	Description
`path` - `String!`
`version` - `String!`
`description` - `String!`
`file` - `FileUpload`
`file_checksum` - `String`
`features` - `[FeaturesInput!]`
`dependencies` - `[DependencyInput!]`
`authors` - `[AuthorInput!]`

Example

{
  "path": "abc123",
  "version": "abc123",
  "description": "xyz789",
  "file": FileUpload,
  "file_checksum": "abc123",
  "features": [FeaturesInput],
  "dependencies": [DependencyInput],
  "authors": [AuthorInput]
}

Types

PublishResult

Types

Union Types
`CreatedIngredientVersionRevision`
`Forbidden`
`MultiPartUploadFileExpected`
`InvalidNamespaceName`
`InvalidIngredientVersion`
`InvalidInput`

Example

CreatedIngredientVersionRevision

Types

PushCommitInput

Fields

Input Field	Description
`organization` - `String!`	The organization the created commit will belong to.
`project` - `String!`	The project the created commit will belong to.
`parentCommitId` - `ID!`	The id of the parent commit.
`expr` - `BuildExpr!`	The build expression being committed.
`atTime` - `DateTime`	The created commit's atTime. Selects rule versions and sets the `$at_time` variable in the root context. If null is passed, it will be treated as if the value "max_verified" had been passed. See the BuildExpr documentation for more information about rule versioning and the root context.
`branchRef` - `String`	The branch this commit will be part of. A branch reference can be either the name of a branch or its id. If not specified or null, the project's main branch will be used. The branch will be updated to point to the new commit.
`description` - `String`	A description of this commit - the commit message.

Example

{
  "organization": "abc123",
  "project": "xyz789",
  "parentCommitId": "4",
  "expr": BuildExpr,
  "atTime": "2007-12-03T10:15:30Z",
  "branchRef": "abc123",
  "description": "abc123"
}

Types

PushCommitResult

Types

Union Types
`Commit`
`NotFound`
`ParseError`
`ValidationError`
`Forbidden`
`HeadOnBranchMoved`
`NoChangeSinceLastCommit`
`InvalidInput`

Example

Commit

Types

RemediableError

Description

EXPERIMENTAL FEATURE: Remediable Error This type may be modified or removed from the schema without notice.

An error with possible remediations to correct it.

Fields

Field Name	Description
`buildExprPath` - `[String!]!`	The path in the build expression to the source of the error.
`message` - `String!`	A message describing the error that occurred.
`possibleRemediations` - `[Remediation!]!`	A set of possible remediations that can fix the error that occurred.

Example

{
  "buildExprPath": ["xyz789"],
  "message": "abc123",
  "possibleRemediations": [Remediation]
}

Types

RemediableSolveError

Fields

Field Name	Description
`message` - `String!`
`path` - `String!`	Replaced by buildExprPath which does not require parsing. Must exist until state tool v0.44.* is deprecated.
`buildExprPath` - `[String!]!`
`isTransient` - `Boolean!`
`errorType` - `SolveErrorType!`
`incompatibilities` - `[SolveErrorIncompatibility!]!`
`requirements` - `[Requirement!]!`
`suggestedRemediations` - `[SolveErrorRemediation!]!`
`validationErrors` - `[SolveErrorValidationError!]!`

Example

{
  "message": "xyz789",
  "path": "xyz789",
  "buildExprPath": ["xyz789"],
  "isTransient": false,
  "errorType": "REQUIREMENT_UNAVAILABLE_AT_TIMESTAMP",
  "incompatibilities": [SolveErrorIncompatibility],
  "requirements": [Requirement],
  "suggestedRemediations": [SolveErrorRemediation],
  "validationErrors": [SolveErrorValidationError]
}

Types

Remediation

Description

EXPERIMENTAL FEATURE: Remediable Error This type may be modified or removed from the schema without notice.

A remediation to an error.

Fields

Field Name Description

description - String! A description of this remediation.

suggestedPriority - Int!

An indication on how likely the user wants this remediation to be applied.

Assumes that client implement automatic application of remediations with a suggestedPriority > 1000. That give us flexibility to re-write build expressions without updating clients.

Possible Types

Remediation Types
`AtTimeRemediation`
`BuildExprRemediation`

Example

{
  "description": "abc123",
  "suggestedPriority": 987
}

Types

Requirement

Description

A Requirement represents a single solve requirement.

Fields

Field Name	Description
`name` - `String!`
`namespace` - `String!`
`versionRequirements` - `[VersionRequirement!]`

Example

{
  "name": "xyz789",
  "namespace": "xyz789",
  "versionRequirements": [VersionRequirement]
}

Types

ResolvedRequirement

Description

ResolvedRequirement relates information from a requirement in the BuildExpr to a Source node in the interpreted BuildPlan

This information does not affect the build. The mapping between requirements specified in BuildExpr and the resolved sources is only known after solving.

Fields

Field Name	Description
`path` - `String!`	path refers to the solve in the input BuildExpr path at which the referenced requirements are set. For example: .merge.left.solve Replaced by buildExprPath which does not require parsing. Must exist until state tool v0.44.* is deprecated.
`buildExprPath` - `[String!]!`	The path in the build expression where this requirement was requested.
`requirement` - `Requirement!`	requirement repeats the requirement from the solve function in a BuildExpr
`resolvedSource` - `ID!`	resolvedSource refers to the nodeId of the Source that was selected to resolve this requirement.

Example

{
  "path": "abc123",
  "buildExprPath": ["abc123"],
  "requirement": Requirement,
  "resolvedSource": 4
}

Types

ResourceRequirements

Fields

Field Name	Description
`cpus` - `Float`	The minimum number of CPU cores to dedicate to the execution of the build. Non-integer numbers indicate shared cores.
`memory` - `Int`	The minimum amount of memory in megabytes to make available to the build.
`hostAttributes` - `[HostAttribute!]!`	The required attributes of a build host.

Example

{
  "cpus": 987.65,
  "memory": 987,
  "hostAttributes": [HostAttribute]
}

Types

RevertCommitInput

Fields

Input Field	Description
`organization` - `String!`	The organization for the project affected by the merge This field is required for access control
`project` - `String!`	The project affected by the merge This field is required for access control
`commitId` - `String!`	Id of the commit that needs to be reverted.
`targetVcsRef` - `String`	Branch name or commit id. Default to main branch if not supplied. If commit id, stage the reverted commit on top of the commit.
`strategy` - `RevertStrategy`	Revert strategy

Example

{
  "organization": "xyz789",
  "project": "abc123",
  "commitId": "abc123",
  "targetVcsRef": "abc123",
  "strategy": "Force"
}

Types

RevertCommitResult

Types

Union Types
`RevertedCommit`
`RevertConflict`
`CommitNotInTargetHistory`
`CommitHasNoParent`
`NotFound`
`ParseError`
`ValidationError`
`Forbidden`
`HeadOnBranchMoved`
`NoChangeSinceLastCommit`
`InvalidInput`

Example

RevertedCommit

Types

RevertConflict

Description

An error for when reverting a commit creates conflicts

Fields

Field Name	Description
`message` - `String!`
`commitId` - `ID!`
`targetCommitId` - `String!`
`conflictPaths` - `[String!]!`

Example

{
  "message": "abc123",
  "commitId": 4,
  "targetCommitId": "xyz789",
  "conflictPaths": ["abc123"]
}

Types

RevertStrategy

Values

Enum Value	Description
`Force`	Forces a revert by applying the revert changes that are possible and ignoring the conflicts.
`Default`	If the revert changes cannot be applied due to conflicts, a RevertConflict error is returned.

Example

"Force"

Types

RevertedCommit

Description

The successful result of reverting a commit.

Fields

Field Name	Description
`commit` - `Commit!`
`targetCommitId` - `ID!`
`conflictPaths` - `[String!]!`

Example

{
  "commit": Commit,
  "targetCommitId": 4,
  "conflictPaths": ["xyz789"]
}

Types

SetVariableInput

Fields

Input Field	Description
`organization` - `String!`	The organization the created commit will belong to.
`project` - `String!`	The project the created commit will belong to.
`parentCommitId` - `ID!`	The id of the parent commit. A parent commit is required to provide the build expression to modify.
`variable` - `String!`	The name of the variable to set.
`expr` - `BuildExpr!`	The value to set variable to.
`atTime` - `DateTime`	The created commit's atTime. Selects rule versions and sets the `$at_time` variable in the root context. If null is passed, it will be treated as if the value "max_verified" had been passed. See the BuildExpr documentation for more information about rule versioning and the root context.
`branchRef` - `String`	The branch this commit will be part of. A branch reference can be either the name of a branch or its id. If not specified or null, the project's main branch will be used. The branch will be updated to point to the new commit.
`description` - `String`	A description of this commit - the commit message.

Example

{
  "organization": "xyz789",
  "project": "xyz789",
  "parentCommitId": "4",
  "variable": "abc123",
  "expr": BuildExpr,
  "atTime": "2007-12-03T10:15:30Z",
  "branchRef": "xyz789",
  "description": "xyz789"
}

Types

SetVariableResult

Types

Union Types
`Commit`
`NotFound`
`ParseError`
`ValidationError`
`Forbidden`
`HeadOnBranchMoved`
`NoChangeSinceLastCommit`
`InvalidInput`

Example

Commit

Types

SolveError

Description

An error returned by the solver during the planning phase.

While SolverErrors are a type of BuildExprError they will only be returned as part of a PlanningError and never as part of a ParseError or ValidationError.

Fields

Field Name	Description
`message` - `String!`
`path` - `String!`	Replaced by buildExprPath which does not require parsing. Must exist until state tool v0.44.* is deprecated.
`buildExprPath` - `[String!]!`
`isTransient` - `Boolean!`
`validationErrors` - `[SolveErrorValidationError!]!`

Possible Types

SolveError Types
`GenericSolveError`
`RemediableSolveError`

Example

{
  "message": "xyz789",
  "path": "abc123",
  "buildExprPath": ["abc123"],
  "isTransient": true,
  "validationErrors": [SolveErrorValidationError]
}

Types

SolveErrorIncompatibility

Fields

Field Name	Description
`type` - `SolveErrorIncompatibilityType!`

Possible Types

SolveErrorIncompatibility Types
`SolveErrorPackageIncompatibility`
`SolveErrorPlatformIncompatibility`

Example

{"type": "DEPENDENCY"}

Types

SolveErrorIncompatibilityType

Values

Enum Value	Description
`DEPENDENCY`
`PLATFORM`
`REQUIREMENT`

Example

"DEPENDENCY"

Types

SolveErrorPackageIncompatibility

Fields

Field Name	Description
`type` - `SolveErrorIncompatibilityType!`
`feature` - `String!`
`namespace` - `String!`

Example

{
  "type": "DEPENDENCY",
  "feature": "xyz789",
  "namespace": "abc123"
}

Types

SolveErrorPlatformIncompatibility

Fields

Field Name	Description
`type` - `SolveErrorIncompatibilityType!`
`platformId` - `ID!`
`platformKernel` - `String!`

Example

{
  "type": "DEPENDENCY",
  "platformId": "4",
  "platformKernel": "abc123"
}

Types

SolveErrorRemediation

Description

SolveErrorRemediation describes a possible command to resolve a solver error

Fields

Field Name	Description
`remediationType` - `SolveErrorRemediationType!`
`command` - `String!`	command is a human-readable description of what the user can do eg., "Remove package pywin32"
`parameters` - `Any`

Example

{
  "remediationType": "ADVANCE_TIMESTAMP",
  "command": "xyz789",
  "parameters": Any
}

Types

SolveErrorRemediationType

Values

Enum Value	Description
`ADVANCE_TIMESTAMP`	The user should bump the timestamp to get a new solve with the same requirements. This may fix various dependency issues by making new ingredients, versions, and revisions visible to the solver.
`REMOVE_REQUIREMENT`	The user should remove the requirement from the project entirely.
`REQUEST_PACKAGE_IMPORT`	The user should request that ActiveState import a new package and/or version.
`CHANGE_REQUIREMENT_NAME`	The user should change the name of a feature in a requirement. This should only be used to indicate that the requested feature is not provided by any known package.
`CHANGE_REQUIREMENT_VERSION`	The user should change the requested version of the package, either by unpinning or by allowing a broader range of versions.
`REMOVE_PLATFORM`	The user should remove one or more platforms from the solveRequest.

Example

"ADVANCE_TIMESTAMP"

Types

SolveErrorType

Values

Enum Value	Description
`REQUIREMENT_UNAVAILABLE_AT_TIMESTAMP`
`REQUIREMENT_UNAVAILABLE`
`REQUIREMENT_VERSION_UNAVAILABLE_AT_TIMESTAMP`
`REQUIREMENT_VERSION_UNAVAILABLE`
`TRANSITIVE_DEPENDENCY_UNAVAILABLE_AT_TIMESTAMP`
`TRANSITIVE_DEPENDENCY_UNAVAILABLE`
`REQUIREMENT_CONFLICTS_WITH_TRANSITIVE_DEPENDENCY`
`REQUIREMENTS_CONFLICT_ON_TRANSITIVE_DEPENDENCY`
`REQUIREMENT_CONFLICTS_WITH_PLATFORM`
`TRANSITIVITY_DEPENDENCY_CONFLICTS_WITH_PLATFORM`
`NO_BUILD_IMAGE_FOR_PLATFORM`

Example

"REQUIREMENT_UNAVAILABLE_AT_TIMESTAMP"

Types

SolveErrorValidationError

Fields

Field Name	Description
`jsonPath` - `String`
`error` - `String!`

Example

{
  "jsonPath": "xyz789",
  "error": "xyz789"
}

Types

Source

Description

Source to be built.

Fields

Field Name	Description
`nodeId` - `ID!`	A unique ID for this source.
`url` - `URI!`	The URL of the source code.
`mimeType` - `String!`	The MIME type of this source.
`checksum` - `String!`	The source code's checksum.
`namespace` - `String!`
`name` - `String!`
`version` - `String!`
`revision` - `Int!`
`ingredientVersionRevisionID` - `ID!`
`ingredientID` - `ID!`
`ingredientVersionID` - `ID!`
`isIndemnified` - `Boolean!`	Indicates whether the Source is marked as indemnified
`patches` - `[Patch!]!`	The patches to be applied to this source before it is built.
`attestations` - `AttestationsResult!`
`licenses` - `[String!]!`	The license exprs which apply to this source. Replaced by categorizedLicenses.
`categorizedLicenses` - `[CategorizedLicense!]!`	The license exprs which apply to this source, grouped by LicenseCategory
`relatesTo` - `[ComponentRelationship!]!`	The components related to this Source.

Example

{
  "nodeId": 4,
  "url": URI,
  "mimeType": "xyz789",
  "checksum": "xyz789",
  "namespace": "abc123",
  "name": "abc123",
  "version": "abc123",
  "revision": 123,
  "ingredientVersionRevisionID": "4",
  "ingredientID": "4",
  "ingredientVersionID": "4",
  "isIndemnified": false,
  "patches": [Patch],
  "attestations": Attestations,
  "licenses": ["abc123"],
  "categorizedLicenses": [CategorizedLicense],
  "relatesTo": [ComponentRelationship]
}

Types

StageCommitInput

Fields

Input Field	Description
`organization` - `String!`
`project` - `String!`
`parentCommitId` - `ID`
`description` - `String`
`expr` - `BuildExpr!`
`atTime` - `DateTime`	The created commit's atTime. Selects rule versions and sets the `$at_time` variable in the root context. If null is passed, it will be treated as if the value "max_verified" had been passed. See the BuildExpr documentation for more information about rule versioning and the root context.

Example

{
  "organization": "abc123",
  "project": "abc123",
  "parentCommitId": 4,
  "description": "xyz789",
  "expr": BuildExpr,
  "atTime": "2007-12-03T10:15:30Z"
}

Types

StageCommitResult

Types

Union Types
`Commit`
`NotFound`
`ParseError`
`ValidationError`
`Forbidden`
`HeadOnBranchMoved`
`NoChangeSinceLastCommit`
`InvalidInput`

Example

Commit

Types

Step

Description

A Step in the build process. A Step is the execution of a builder.

Fields

Field Name	Description
`stepId` - `ID!`	UUID for this step.
`name` - `String!`	the name of this step.
`image` - `ID!`	The image to execute this step on.
`command` - `String!`	The command to run and the options to pass it. The command will execute the builder: build for *nix/macOS and build.bat for windows.
`commandLineArgs` - `[String!]!`	The arguments to be passed to the builder on the command, derived from ingredient options.
`resourceRequirements` - `ResourceRequirements`	The minimum resources needed for this build, if specified in ingredient options.
`inputs` - `[TaggedNodes!]!`	The Step's inputs to be downloaded and unpacked. Inputs are Sources and/or Artifacts.
`outputs` - `[ID!]!`	The Step's outputs to be uploaded when the Step completes. Outputs are Artifacts.

Example

{
  "stepId": 4,
  "name": "xyz789",
  "image": "4",
  "command": "xyz789",
  "commandLineArgs": ["abc123"],
  "resourceRequirements": ResourceRequirements,
  "inputs": [TaggedNodes],
  "outputs": [4]
}

Types

String

Description

The String scalar 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.

Example

"abc123"

Types

TaggedNodes

Fields

Field Name	Description
`tag` - `String!`	An identifier "tagged" to the set of node ids.
`nodeIds` - `[ID!]!`

Example

{
  "tag": "abc123",
  "nodeIds": ["4"]
}

Types

TargetNotFound

Description

An error that occurs when the user requests a target that does not exist in the build expression.

Fields

Field Name	Description
`message` - `String!`
`buildExprPath` - `[String!]!`
`requestedTarget` - `String!`
`possibleTargets` - `[String!]!`

Example

{
  "message": "abc123",
  "buildExprPath": ["xyz789"],
  "requestedTarget": "abc123",
  "possibleTargets": ["xyz789"]
}

Types

URI

Example

URI

Types

ValidationError

Description

A wrapper for one or more errors that occur while validating a parsed build expression.

Fields

Field Name	Description
`message` - `String!`
`subErrors` - `[BuildExprError!]!`

Example

{
  "message": "xyz789",
  "subErrors": [BuildExprError]
}

Types

VersionRequirement

Description

A VersionRequirement represents a single version requirement (a comparator and a version) in a Requirement.

Fields

Field Name	Description
`comparator` - `Comparator!`
`version` - `String!`

Example

{"comparator": "EQ", "version": "abc123"}

Types

VersionRequirements

Description

The requirements (or constraints) on a version, such as a dependency version.

VersionRequirements specify one or more requirements that constrain a version. Each requirement specifies a half range and will be joined logically with other half ranges without having to specify how ranges are joined. The ordering of ranges is not significant with respect to the constraints they enforce on a version.

Examples:

= 1.0
- version must be greater than or equal to 1.0
= 1.0, < 2.0
- version must be greater than or equal to 1.0 and less than 2.0 or sometimes written as 1.*
= 1.0, < 2.0, >= 5.0, < 5.5
- version must be greater than or equal to 1.0 and less than 2.0
- OR version must be greater than or equal to 5.0 and less than 5.5

A VersionRequirements value is formatted as: versionRequirement : requirement (', ' requirement)* requirement : op ' ' version op : '==' | '<' | '<=' | '>' | '>=' version : STRING

Example

VersionRequirements

Types

Vulnerability

Fields

Field Name	Description
`id` - `ID!`
`vulnAliasIDs` - `[ID!]!`
`publishedDate` - `String`
`withdrawnDate` - `String`
`summary` - `String!`
`details` - `String!`
`severityType` - `String!`
`severityScore` - `Float!`

Example

{
  "id": "4",
  "vulnAliasIDs": [4],
  "publishedDate": "xyz789",
  "withdrawnDate": "abc123",
  "summary": "abc123",
  "details": "abc123",
  "severityType": "abc123",
  "severityScore": 987.65
}

Documentation by Anvil SpectaQL