> ## Documentation Index > Fetch the complete documentation index at: https://docs.firedrill.run/llms.txt > Use this file to discover all available pages before exploring further. # Exchange a GitHub Actions OIDC token for an exact-revision CI credential ## OpenAPI ````yaml /api-reference/openapi.json post /v1/auth/github-actions/exchange openapi: 3.1.0 info: title: Firedrill Control API version: 1.0.0 description: >- The control plane for drills, drill runs, and the worlds they run in. Errors always carry the canonical envelope; unsafe operations require an Idempotency-Key; long work returns an operation resource. servers: - url: https://api.firedrill.run security: - controlCredential: [] tags: - name: authentication description: Sessions, CLI exchange, credentials, and verification keys. x-group: Authentication - name: organizations description: Organization members, billing, usage, retention, audit, and exports. x-group: Organizations - name: projects description: Project lifecycle, access, grants, and repository bindings. x-group: Projects - name: builds description: Immutable builds, uploads, source drafts, and world definitions. x-group: Builds and source - name: tools description: Project Tool discovery, approval, source, and revocation. x-group: Tool library - name: worlds description: >- Managed environments, world sessions, state, time, reset, faults, forks, and snapshots. x-group: Environments and sessions - name: runs description: >- Hosted runs, comparisons, attachments, reports, evidence bundles, sharing, and exports. x-group: Runs and evidence - name: browser description: Managed browser tests, runs, messages, streams, frames, and artifacts. x-group: Browser testing - name: callbacks description: Callback receiver approval, revocation, and signing material. x-group: Callbacks - name: github-ci description: >- GitHub installations, repository automation, CI suites, cases, evidence, and checks. x-group: GitHub and CI - name: authoring description: Authoring sessions, proposals, turns, and scenario proposals. x-group: Cloud authoring paths: /v1/auth/github-actions/exchange: post: tags: - authentication summary: Exchange a GitHub Actions OIDC token for an exact-revision CI credential operationId: auth.githubActionsExchange requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GitHubActionsExchangeRequest' responses: '200': description: CI credential and immutable workflow invocation content: application/json: schema: $ref: '#/components/schemas/GitHubActionsExchangeResponse' default: description: Canonical error envelope content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: [] components: schemas: GitHubActionsExchangeRequest: type: object properties: oidcToken: type: string minLength: 100 maxLength: 16384 projectId: type: string pattern: ^prj_[0-9a-z]{12,32}$ environmentId: type: string pattern: ^env_[0-9a-z]{12,32}$ repositoryBindingId: type: string pattern: ^repo_[0-9a-z]{12,32}$ suiteKey: default: default type: string minLength: 1 maxLength: 96 pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$ required: - oidcToken - projectId - environmentId - repositoryBindingId - suiteKey additionalProperties: false GitHubActionsExchangeResponse: type: object properties: schemaVersion: type: number enum: - 1 credential: type: string pattern: ^fd_ci_[A-Za-z0-9_-]{32,}$ credentialExpiresAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 actions: type: array items: anyOf: - type: string enum: - ci.execute minItems: 1 maxItems: 1 invocation: type: object properties: schemaVersion: type: number enum: - 1 ciInvocationId: type: string pattern: ^ci_[0-9a-z]{12,32}$ organizationId: type: string pattern: ^org_[0-9a-z]{12,32}$ projectId: type: string pattern: ^prj_[0-9a-z]{12,32}$ environmentId: type: string pattern: ^env_[0-9a-z]{12,32}$ repositoryBindingId: type: string pattern: ^repo_[0-9a-z]{12,32}$ credentialId: type: string pattern: ^cred_[0-9a-z]{12,32}$ provider: type: string enum: - github_actions suiteKey: type: string minLength: 1 maxLength: 96 pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$ state: type: string enum: - active - completed - cancelled - expired installationId: type: string pattern: ^[1-9][0-9]{0,19}$ repositoryId: type: string pattern: ^[1-9][0-9]{0,19}$ repository: type: string minLength: 3 maxLength: 201 pattern: ^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$ repositoryOwnerId: type: string pattern: ^[1-9][0-9]{0,19}$ repositoryVisibility: type: string enum: - public - private - internal eventName: type: string minLength: 1 maxLength: 100 source: oneOf: - type: object properties: kind: type: string enum: - workflow candidateRevision: type: string pattern: ^[0-9a-f]{40}$ ref: type: string minLength: 1 maxLength: 1024 required: - kind - candidateRevision - ref additionalProperties: false - type: object properties: kind: type: string enum: - push candidateRevision: type: string pattern: ^[0-9a-f]{40}$ ref: type: string minLength: 1 maxLength: 1024 required: - kind - candidateRevision - ref additionalProperties: false - type: object properties: kind: type: string enum: - pull_request pullRequestNumber: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 baseRevision: type: string pattern: ^[0-9a-f]{40}$ candidateRevision: type: string pattern: ^[0-9a-f]{40}$ baseRef: type: string minLength: 1 maxLength: 255 headRef: type: string minLength: 1 maxLength: 255 required: - kind - pullRequestNumber - baseRevision - candidateRevision - baseRef - headRef additionalProperties: false githubActor: type: string minLength: 1 maxLength: 255 githubActorId: type: string pattern: ^[1-9][0-9]{0,19}$ workflowRunId: type: string pattern: ^[1-9][0-9]{0,19}$ workflowRunNumber: type: string pattern: ^[1-9][0-9]{0,19}$ workflowRunAttempt: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 workflowName: type: string minLength: 1 maxLength: 255 workflowRef: type: string minLength: 1 maxLength: 2048 workflowSha: type: string pattern: ^[0-9a-f]{40}$ jobWorkflowRef: type: string minLength: 1 maxLength: 2048 jobWorkflowSha: type: string pattern: ^[0-9a-f]{40}$ githubEnvironment: type: string minLength: 1 maxLength: 255 checkRunId: type: string pattern: ^[1-9][0-9]{0,19}$ commentId: type: string pattern: ^[1-9][0-9]{0,19}$ credentialExpiresAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 createdAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 updatedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 finishedAtMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - schemaVersion - ciInvocationId - organizationId - projectId - environmentId - repositoryBindingId - credentialId - provider - suiteKey - state - installationId - repositoryId - repository - repositoryOwnerId - repositoryVisibility - eventName - source - githubActor - githubActorId - workflowRunId - workflowRunNumber - workflowRunAttempt - workflowName - workflowRef - workflowSha - credentialExpiresAtMs - createdAtMs - updatedAtMs additionalProperties: false required: - schemaVersion - credential - credentialExpiresAtMs - actions - invocation additionalProperties: false ErrorEnvelope: type: object properties: code: type: string pattern: ^(control|world)\.[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$ message: type: string minLength: 1 correlationId: type: string minLength: 1 retryable: type: boolean retryAfterMs: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 operationId: type: string source: type: string enum: - platform - simulated_provider issues: type: array items: type: object properties: path: type: string code: type: string message: type: string required: - path - code - message additionalProperties: false details: type: object propertyNames: type: string additionalProperties: {} evidence: type: object properties: sessionId: type: string runId: type: string journalSeq: type: integer minimum: 0 maximum: 9007199254740991 buildHash: type: string additionalProperties: false required: - code - message - correlationId - retryable - source additionalProperties: true securitySchemes: controlCredential: type: http scheme: bearer description: Opaque control credential ````