# Automation and CI

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

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](/docs/access/grants#grant-access-to-a-server).

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:

```yaml
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](https://github.com/nokku-sh/nokku/tree/main/cli#ci-and-headless-machines) 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](https://github.com/nokku-sh/nokku/blob/main/core/SECURITY.md#what-to-know-about-the-design) 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.

```bash
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`.

> **Warning: 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](/api). Every procedure is a `POST` with a JSON body. Send the key as a bearer token:

```bash
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.
