NKS SSH Certificate Action

Request a short-lived SSH certificate from Neural Key Service (NKS) inside a GitHub Actions workflow.

This action generates an ephemeral Ed25519 key pair on the runner, sends only the raw public key to NKS, writes the signed OpenSSH certificate to disk, and exposes file paths for later SSH/SCP/rsync steps.

Usage

name: Deploy

on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - id: nks
        uses: IlluminatiLTD-AI/nks-ssh-cert@v1
        with:
          api-key: ${{ secrets.NKS_API_KEY }}
          host: droplet
          principal: root
          ttl-minutes: 15

      - name: Deploy over SSH
        run: |
          ssh \
            -i "${{ steps.nks.outputs.private-key-path }}" \
            -o CertificateFile="${{ steps.nks.outputs.certificate-path }}" \
            -o StrictHostKeyChecking=no \
            root@167.71.43.219 \
            "cd /opt/projects/openclawBRO && git status --short"

Inputs

Input	Required	Default	Description
api-key	yes		NKS API key. Store it in secrets.NKS_API_KEY.
api-url	no	https://crm.illuminati.co.il	NKS API base URL.
host	yes		NKS host identifier.
principal	yes		SSH principal/user to authenticate as on the target host.
ttl-minutes	no	15	Certificate lifetime in minutes. NKS currently accepts 1 to 60.
services	no		Comma-separated service labels reserved for forward-compatible workflow metadata. Current NKS SSH certs are scoped by host and principal.
key-path	no	$RUNNER_TEMP/nks-ssh-cert/id_ed25519	Path for the generated Ed25519 private key.
certificate-path	no	<key-path>-cert.pub	Path for the signed OpenSSH certificate.
comment	no	nks-github-actions	SSH key comment.

Outputs

Output	Description
certificate	Signed OpenSSH certificate content. Masked in logs.
certificate-path	Path to the signed OpenSSH certificate file.
private-key	Path to the generated private key. The private key content is not exposed.
private-key-path	Path to the generated private key.
public-key	Generated OpenSSH public key content.
public-key-path	Path to the generated OpenSSH public key file.
serial	NKS certificate serial number.
expires-at	ISO timestamp when the certificate expires.
principal	SSH principal confirmed by NKS.
host	NKS host confirmed by NKS.

Security Model

• The action is public/open source so teams can inspect exactly what runs in CI.
• Payment and authorization are enforced by the NKS API key, not by the action code.
• The NKS API key must be stored as a GitHub Actions secret.
• The generated private key stays on the GitHub Actions runner and is never sent to NKS.
• NKS receives only the raw Ed25519 public key and returns a short-lived OpenSSH certificate.
• Use scoped NKS keys and access windows for CI-specific deployments.
• The certificate expires quickly, so leaked runner artifacts are not long-lived credentials.

Requirements

• A Linux or macOS runner with ssh-keygen and node available.
• An NKS tenant/API key with SSH certificate issuance enabled.
• A target host configured to trust your NKS tenant CA through TrustedUserCAKeys.

Billing

This GitHub Action is free to install. NKS usage is controlled and billed by your NKS account/API key. Copying this repository does not grant access to the NKS service or signing CA.