Skip to content
Nokku LogoNokku
GuidesLearn the concepts

Use service accounts to let CI jobs and scripts reach your servers or call the API.

Last updated on

CI jobs and scripts can’t open a browser to sign in. They use a service account instead: an identity for a machine, with access granted like a person’s.

Create a service account

  1. In the web app, create a service account under Service accounts. You need the editor role.
  2. Grant it the Linux accounts it needs, exactly like a person. See Grant access.

For logging in to servers, the default member role is enough. Give it viewer or editor only if a job needs to read or change things in the workspace.

How the account signs in depends on where it runs:

  • A CI job signs in with the token its platform already gives it. Nothing secret is stored. Use this whenever you can.
  • Ansible and scripts that run somewhere without such a token use a service account key.

In CI, with no stored secret

GitHub Actions, GitLab and many other CI systems give every job a signed token that says which repository, branch and environment it runs for. Nokku can trust that token directly.

  1. Open the service account and add a rule under CI jobs. A rule names the platform and exactly which jobs may sign in, like one repository and its production environment.
  2. In the job, sign in with nk login --ci <service account>.

On GitHub Actions the job needs the id-token: write permission:

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    permissions:
      contents: read
      id-token: write
    env:
      NK_API_URL: https://nokku.example.com
    steps:
      - run: curl -fsSL https://get.nokku.sh/nk | sh
      - run: nk login --ci deploy
      - run: ssh deploy@my-server ./release.sh

GitLab and other platforms work the same way. The nk README shows the GitLab setup.

  • The session is short, never outlives the job’s token, and is bound to a key nk holds on the runner. A session token in a log is worth nothing alone.
  • A job token works once. When the session runs out, nk fails and says to run nk login --ci again. It never waits on a browser.
  • Make the rule as narrow as you can. An environment only limits a job if that environment is protected on the platform. core/SECURITY.md explains what a rule must name and why.

Ansible and scripts, with a key

  1. Open the service account, go to Tokens and create one. Pick when it expires, every key has an end date.
  2. Copy it. It starts with nk_sa_ and is shown only once.
  3. Pass it in the NK_TOKEN environment variable. nk never writes it to disk.
export NK_API_URL=https://nokku.example.com
export NK_TOKEN=nk_sa_...
nk login
ssh deploy@my-server "systemctl restart my-app"

nk gets a certificate for each server right before ssh needs it. A service account’s certificate is kept short and never outlives its key. nk renews it on its own, so keep NK_TOKEN set wherever the job runs ssh.

Treat the key like a password

Unlike a person’s session or a CI sign-in, a service account key is not tied to one machine. Anyone who has it can use it. Keep it in a secret store, never in a repository or in logs. CI should not hold one, use a CI rule instead.

A service account can hold several keys, each with its own label and expiry. Give every job or environment its own, so you can replace or revoke one without breaking the others.

Replace a key

Replace a key before it expires, or when it may have leaked:

  1. Create a new key under Tokens and copy it.
  2. Put it where the old one was and let a job run with it.
  3. Revoke the old key.

Both keys work until you revoke the old one, so nothing fails in between. The service account keeps its grants and its role.

Limit what it can do

Under Login limits, a service account can carry a forced command and a source list. Both go on every certificate it gets, and the server enforces them:

  • A forced command runs instead of whatever the login asks for. It also turns off port and agent forwarding. The command that was asked for is passed along as SSH_ORIGINAL_COMMAND, so wrappers like git-shell work.
  • A source list names the addresses the account may log in from.

Only a person can change these. The workspace’s own source list for people does not apply to service accounts.

Call the API

A service account key also works for the API. Every procedure is a POST with a JSON body. Send the key as a bearer token:

curl -X POST https://<your-nokku>/nokku.v1.TargetService/ListTargets \
  -H "Authorization: Bearer $NK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

The call needs the role the API reference names, so a script that reads the workspace needs a viewer account or higher.

Remove access

Delete the service account, or remove its grants. It can’t get new certificates after that, and servers with nokkud stop accepting its existing ones right away. Removing a CI rule stops new sign-ins from those jobs. Revoking a key stops its calls and new certificates, but a certificate it already holds keeps working until it runs out, which is soon. To end its access at once, remove its grants or delete the account.