Actions

ship.actions uses the same operations as the dashboard and REST API. All user operations require the selected organization and job permissions. Workflow access also checks the originating user's repository, runner and storage access. Configuring a runner requires administration access to its server.

See Openship Actions for supported syntax, destination requirements, fork restrictions and compatibility limits.

Configure and dispatch

Select runner IDs from actions.runners(). Saving an existing repository file does not execute it; dispatch resolves a commit and saves an immutable snapshot.

const workflow = await ship.actions.create({
  controller: "openship",
  name: "CI",
  owner: "your-organization",
  repo: "your-app",
  ref: "main",
  path: ".openship/workflows/ci.yml",
  runnerIds: ["runner_123"],
});

const run = await ship.actions.dispatch(workflow.id, {
  idempotencyKey: crypto.randomUUID(),
});

Reuse the original idempotency key after a timeout or lost response. A new key requests a new run. rerun(runId, { idempotencyKey }) uses the saved revision, definition and configuration as a new attempt.

create and update accept the same complete workflow configuration. Optional source contains inline YAML; otherwise Openship reads the repository file. variables are plain environment values. secrets adds or replaces only the provided encrypted entries; removeSecrets explicitly removes named entries. storageDestinationId selects an authorized backup destination for artifacts and cache. Reads return secret names, never their values.

Optional accessPolicy configures audience (owner, selected or collaborators), users (1–30 GitHub usernames for selected-user access), approval (required or automatic) and forks (deny or review). New workflows default to the owner, required approval and denied forks. The server resolves GitHub identities and never accepts account IDs supplied by the caller. Fork review requires a disposable Cloud runner and always needs approval.

Run details exposes admission, runnerIds and canApprove. When admission is approval_required, review the commit, attempt, requester and destinations, then send { key: run.admission.key } to approve. A changed review returns a conflict; refresh the run before approving again. Approval requires job:admin and administration of the current destinations. canApprove is a presentation hint; the mutation checks permissions again. The legacy no-body approval remains only for independent fork runs without a saved access policy.

importWorkflows({ workflows }) accepts up to 50 complete configurations from one repository and branch. It validates all new files, then saves workflows and project links in one transaction. Repeating the import reuses each file's existing record, preserves its settings and adds new authorized project links. Use update to change an already imported workflow. Importing does not commit repository changes or start runs.

For a standalone workflow, omit owner and repo and provide source. It can run manually, on a schedule, from an authenticated webhook, or through a Job without GitHub credentials. actions/checkout needs an explicit with.repository in this mode.

Optional projectIds associates a workflow with projects the caller can edit. actions.projectPolicy(projectId) reads linked workflows and pending deployment requests; actions.updateProjectPolicy(projectId, input) selects manual, push, or required-check deployment. Required workflows must cover every push to the project's branch without path filters. Linking workflows alone does not enable automatic deployment.

dispatch accepts either declared manual inputs or an eventType and optional clientPayload for repository_dispatch. Both use normal API authentication and the caller's selected organization. See the webhook example.

GitHub-controlled workflows

Use controller: "github", source: null and a committed .github/workflows/*.yml file. Configure accessPolicy to control which matching jobs may execute on its destinations. The old repositoryRunnerConsent field is accepted for compatibility but grants no permission. GitHub manages secrets, variables, artifacts and Checks; omit Openship secrets, variables and storage settings in this mode.

preview, repositorySource and updateRepositorySource infer the controller from the file path: .github/workflows/ uses GitHub, while .openship/workflows/ and standalone YAML use the independent controller. API callers may also provide an explicit controller.

GitHub mode dispatches workflow_dispatch through GitHub and mirrors the exact returned run ID and attempt. It delegates reruns and cancellation to GitHub. Reuse request keys: an uncertain GitHub POST is never automatically replayed. An accepted command whose run is not visible yet will appear through reconciliation. Send repository_dispatch and other GitHub events to GitHub's own API.

Run and job views include externalUrl. GitHub live logs open at that URL; jobEvents provides the completed log preview with the same cursor contract. settledAt also waits for Openship's runner cleanup. Native GitHub Check IDs and conclusions are preserved without creating duplicate Checks.

Observe and cancel

const current = await ship.actions.getRun("run_123");
for (const job of current.jobs) {
  const output = await ship.actions.jobEvents(job.id, { after: 0 });
  console.log(output.events);
  // Save output.next and use it as after when polling or reconnecting.
}
await ship.actions.cancel(current.id);

Cancellation is a durable request. Job cleanedAt confirms destination cleanup; run settledAt confirms all jobs and GitHub Checks have settled. A disconnected controller resumes inspection of the original worker rather than replaying it.

Artifact download links expire after 60 seconds. The runtime protocol endpoints below authenticate scoped job capabilities and recheck their saved authority. They do not accept a user session as an upload grant. /twirp is also exposed at the API origin because the official cache client resolves that absolute path. Preserve both paths when configuring an external reverse proxy.

Operations

Workflows

Runners

Runs

Output

Project integration

Job runtime protocols