Run an automation with a key file

Run Nevia from a CI job with no person signing in. The job acts as a principal with its own key file. It creates a computer, runs a command on it and deletes the computer, even when a step fails.

Prerequisites

A workspace admin with the CLI installed and signed in, to issue the key.
A CI system that stores secrets. This guide uses GitHub Actions.
A pinned CLI version, the same on your laptop and in CI. This guide pins 0.1.6.

The principal has the editor role. It can create and delete computers and never gets admin. See Workspace permissions.

Issue the key

An admin runs this on a local machine:

nevia access add --private-key --description "ci"

The CLI saves the key file to ~/.config/nevia/keys/<key>.json, readable only by you. Nevia keeps no copy. Print the file and copy its full contents:

cat ~/.config/nevia/keys/<key>.json

Then delete the local copy. If you lose the key, issue a new one. For the other --out options and --role viewer, see Give a script or agent access.

Store the key file as a CI secret

Save the full JSON in your CI secret store. In GitHub, create a repository secret named NEVIA_KEY. Don't commit the file or put it in a variable.

Run the job

The job installs the CLI, writes the key file to a temporary path with chmod 600, and runs the steps. The delete step has if: always(), so a failed command still removes the computer.

name: nevia-automation

on:
  workflow_dispatch:

jobs:
  nevia:
    runs-on: ubuntu-latest
    steps:
      - name: Install nevia
        env:
          NEVIA_VERSION: "0.1.6"
        run: |
          curl -fsSL https://get.nevia.cloud | NEVIA_VERSION="$NEVIA_VERSION" NEVIA_INSTALL_DIR="$RUNNER_TEMP/bin" sh
          echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"

      - name: Write key file
        env:
          NEVIA_KEY: ${{ secrets.NEVIA_KEY }}
        run: |
          key_file="$RUNNER_TEMP/nevia-key.json"
          printf '%s' "$NEVIA_KEY" > "$key_file"
          chmod 600 "$key_file"
          echo "NEVIA_KEY_FILE=$key_file" >> "$GITHUB_ENV"

      - name: Check identity
        run: nevia whoami

      - name: Create computer
        id: create
        run: nevia new ci-${{ github.run_id }} --wait

      - name: Run command
        run: nevia exec ci-${{ github.run_id }} -- sh -c 'echo ok'

      - name: Delete computer
        if: ${{ always() && steps.create.outcome != 'skipped' }}
        run: nevia rm ci-${{ github.run_id }} --yes --wait

On another CI system, keep the same steps: a pinned install, the secret written to a chmod 600 file, NEVIA_KEY_FILE set, and the delete in an always-run step.

Verify

nevia whoami shows (private key) and the one workspace. If it shows your login, NEVIA_KEY_FILE didn't reach the step.

The CLI doesn't check for updates in CI, so the pinned version stays put.

Rotate the key

Keys expire 90 days after creation by default. Rotate before that date or the job can't sign in.

An admin runs:

nevia access keys rotate <principal>

keys rotate revokes the old key in the same step, so update the NEVIA_KEY secret before the next run or the job fails. Pass --expires-in for a shorter lifetime. nevia access ls shows each principal's key state. To cut off access with no replacement, run nevia access keys rm <principal>.

Give a script or agent access: add, use, rotate and bring your own key.
nevia auth use-key-file: remember a key file path in a project.
Workspace permissions: what the editor role can do.