GitHub Actions Upsert a Repository Secret

arazzo: 1.0.1
info:
  title: GitHub Actions Upsert a Repository Secret
  summary: Fetch the repository public key, create or update an encrypted secret, then confirm it exists.
  description: >-
    The required handshake for writing an Actions secret. The workflow first
    retrieves the repository public key (needed to identify which key encrypted
    the value), creates or updates the secret with the caller-supplied encrypted
    value and key id, then reads the secret metadata back to confirm the write.
    Every step spells out its request inline so the flow can be read and
    executed without opening the underlying OpenAPI description.
  version: 1.0.0
  x-realizes-capability-ids:
  - BC-4210.60
  x-capability-derivation:
    method: 'deterministic join: sourceDescriptions -> per-tag OpenAPI -> tag/capability edge. No classification at this step.'
    min_confidence: 0.7
    sources:
    - capability_id: BC-4210.60
      capability_name: Configuration & Secrets Management
      spec: github-actions-secrets-api-openapi.yml
      confidence: 0.85
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: secretsApi
  url: ../openapi/github-actions-secrets-api-openapi.yml
  type: openapi
workflows:
- workflowId: upsert-repo-secret
  summary: Create or update an encrypted repository secret and confirm it.
  description: >-
    Gets the repository public key, writes the encrypted secret value with that
    key id, and reads the secret metadata back to verify the upsert.
  inputs:
    type: object
    required:
    - accessToken
    - owner
    - repo
    - secretName
    - encryptedValue
    - keyId
    properties:
      accessToken:
        type: string
        description: GitHub bearer token with Actions secrets write access.
      owner:
        type: string
        description: The account owner of the repository.
      repo:
        type: string
        description: The name of the repository without the .git extension.
      secretName:
        type: string
        description: The name of the secret to create or update.
      encryptedValue:
        type: string
        description: The secret value encrypted with LibSodium using the repo public key.
      keyId:
        type: string
        description: The id of the public key used to encrypt the value.
  steps:
  - stepId: getPublicKey
    description: >-
      Retrieve the repository public key. The returned key_id must match the
      key id used to encrypt the secret value.
    operationId: getRepoPublicKey
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: owner
      in: path
      value: $inputs.owner
    - name: repo
      in: path
      value: $inputs.repo
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      keyId: $response.body#/key_id
      publicKey: $response.body#/key
  - stepId: writeSecret
    description: >-
      Create or update the secret with the supplied encrypted value. The API
      returns 201 when the secret is newly created and 204 when it is updated.
    operationId: createOrUpdateRepoSecret
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: owner
      in: path
      value: $inputs.owner
    - name: repo
      in: path
      value: $inputs.repo
    - name: secret_name
      in: path
      value: $inputs.secretName
    requestBody:
      contentType: application/json
      payload:
        encrypted_value: $inputs.encryptedValue
        key_id: $inputs.keyId
    successCriteria:
    - condition: $statusCode == 201 || $statusCode == 204
  - stepId: confirmSecret
    description: >-
      Read the secret metadata back to confirm the upsert succeeded and capture
      its updated timestamp.
    operationId: getRepoSecret
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: owner
      in: path
      value: $inputs.owner
    - name: repo
      in: path
      value: $inputs.repo
    - name: secret_name
      in: path
      value: $inputs.secretName
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      name: $response.body#/name
      updatedAt: $response.body#/updated_at
  outputs:
    secretName: $steps.confirmSecret.outputs.name
    updatedAt: $steps.confirmSecret.outputs.updatedAt