# com.publicdomainrelay.temp.tangled.spindle.trigger

> Published by [johnandersen777.bsky.social](https://lexicon.garden/identity/did:plc:5svqtrhheairglgiiyvutzik)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:5svqtrhheairglgiiyvutzik/com.publicdomainrelay.temp.tangled.spindle.trigger)
- [Documentation](https://lexicon.garden/lexicon/did:plc:5svqtrhheairglgiiyvutzik/com.publicdomainrelay.temp.tangled.spindle.trigger/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:5svqtrhheairglgiiyvutzik/com.publicdomainrelay.temp.tangled.spindle.trigger/examples)

## Definitions

### `com.publicdomainrelay.temp.tangled.spindle.trigger`

**Type**: `procedure`

Manually trigger a pipeline run on a Tangled spindle. Intended to be called via PDS service proxying (the 'atproto-proxy' header, pointed at the spindle's did:web service entry), so the user's PDS mints and signs the inter-service auth token; the spindle verifies the token's issuer against their DID document and requires it to match the trigger's 'actor'. Mirrors the sh.tangled.pipeline fields a knot dispatches on a push/PR event.

#### Input

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ref` | `string` | Yes | Commit SHA to run at. The spindle fetches .github/workflows/*.yml at this exact commit, so it must be a real commit, not a branch name. |
| `knot` | `string` | Yes | Knot hostname that hosts the repo, e.g. knot1.tangled.sh. |
| `actor` | `string` (did) | Yes | DID of the actor the run is attributed to. Must equal the issuer of the service-auth token. |
| `inputs` | `unknown` | No | Optional workflow_dispatch-style inputs, as a map of string keys to string values. |
| `repoDid` | `string` (did) | Yes | DID of the repo (the owner DID used for sh.tangled.repo.blob lookups). |
| `repoName` | `string` | Yes | Human-readable repo name, e.g. myrepo. |
| `pipelineRkey` | `string` | Yes | Record key identifying this pipeline run; only needs to be unique per run. |

#### Output

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ref` | `string` | Yes |  |
| `knot` | `string` | Yes |  |
| `submitted` | `boolean` | Yes | True once the trigger was accepted and workflow submission started. |
| `workflows` | `array` | Yes | The workflow stems that were submitted, with their log/status stream URLs. |
| `pipelineRkey` | `string` | Yes |  |

#### Errors

- **InvalidRequest**: Malformed body or missing required fields.
- **Unauthorized**: Missing or invalid inter-service auth token.
- **Forbidden**: Token issuer does not match actor, or repo is not authorized for this spindle.

### `com.publicdomainrelay.temp.tangled.spindle.trigger#workflowResult`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `logsUrl` | `string` (uri) | No | URL to the log stream for this workflow run. |
| `workflow` | `string` | Yes | Workflow stem that was submitted. |
| `statusUrl` | `string` (uri) | No | URL to the status stream for this workflow run. |

## Raw Schema

```json
{
  "id": "com.publicdomainrelay.temp.tangled.spindle.trigger",
  "defs": {
    "main": {
      "type": "procedure",
      "input": {
        "schema": {
          "type": "object",
          "required": [
            "knot",
            "pipelineRkey",
            "actor",
            "repoDid",
            "repoName",
            "ref"
          ],
          "properties": {
            "ref": {
              "type": "string",
              "description": "Commit SHA to run at. The spindle fetches .github/workflows/*.yml at this exact commit, so it must be a real commit, not a branch name."
            },
            "knot": {
              "type": "string",
              "description": "Knot hostname that hosts the repo, e.g. knot1.tangled.sh."
            },
            "actor": {
              "type": "string",
              "format": "did",
              "description": "DID of the actor the run is attributed to. Must equal the issuer of the service-auth token."
            },
            "inputs": {
              "type": "unknown",
              "description": "Optional workflow_dispatch-style inputs, as a map of string keys to string values."
            },
            "repoDid": {
              "type": "string",
              "format": "did",
              "description": "DID of the repo (the owner DID used for sh.tangled.repo.blob lookups)."
            },
            "repoName": {
              "type": "string",
              "description": "Human-readable repo name, e.g. myrepo."
            },
            "pipelineRkey": {
              "type": "string",
              "description": "Record key identifying this pipeline run; only needs to be unique per run."
            }
          }
        },
        "encoding": "application/json"
      },
      "errors": [
        {
          "name": "InvalidRequest",
          "description": "Malformed body or missing required fields."
        },
        {
          "name": "Unauthorized",
          "description": "Missing or invalid inter-service auth token."
        },
        {
          "name": "Forbidden",
          "description": "Token issuer does not match actor, or repo is not authorized for this spindle."
        }
      ],
      "output": {
        "schema": {
          "type": "object",
          "required": [
            "submitted",
            "knot",
            "pipelineRkey",
            "ref",
            "workflows"
          ],
          "properties": {
            "ref": {
              "type": "string"
            },
            "knot": {
              "type": "string"
            },
            "submitted": {
              "type": "boolean",
              "description": "True once the trigger was accepted and workflow submission started."
            },
            "workflows": {
              "type": "array",
              "items": {
                "ref": "#workflowResult",
                "type": "ref"
              },
              "description": "The workflow stems that were submitted, with their log/status stream URLs."
            },
            "pipelineRkey": {
              "type": "string"
            }
          }
        },
        "encoding": "application/json"
      },
      "description": "Manually trigger a pipeline run on a Tangled spindle. Intended to be called via PDS service proxying (the 'atproto-proxy' header, pointed at the spindle's did:web service entry), so the user's PDS mints and signs the inter-service auth token; the spindle verifies the token's issuer against their DID document and requires it to match the trigger's 'actor'. Mirrors the sh.tangled.pipeline fields a knot dispatches on a push/PR event."
    },
    "workflowResult": {
      "type": "object",
      "required": [
        "workflow"
      ],
      "properties": {
        "logsUrl": {
          "type": "string",
          "format": "uri",
          "description": "URL to the log stream for this workflow run."
        },
        "workflow": {
          "type": "string",
          "description": "Workflow stem that was submitted."
        },
        "statusUrl": {
          "type": "string",
          "format": "uri",
          "description": "URL to the status stream for this workflow run."
        }
      }
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1
}
```