# CI/CD Pipelines

A pipeline reaching devices through ShellHub is an SSH client like any other. What makes it worth its own page is the credential question — get that wrong and the pipeline either breaks unpredictably or is over-privileged.

## Set it up correctly, once

**1. Give the pipeline its own key.** Not a person’s. Create an API key named for the pipeline, `ci-deploy`, then open its **SSH access** on the **Team** page and add an SSH key for it.

Two things this buys you: the session list attributes deploys to `ci-deploy` rather than to whoever set it up, and the pipeline does not break the week that person leaves. See [SSH Access](https://docs.shellhub.io/api/ssh-access).

**2. Add the key ahead of time.** A key that is not yet an identity parks the login waiting for a browser approval. In a pipeline that is a hang, then a timeout, on a job nobody is watching.

**3. Write a policy for it.** An `all-members` allow does **not** cover an automation, which is not a member:

| Name                 | Effect | Subject             | Devices          | Logins   |
| -------------------- | ------ | ------------------- | ---------------- | -------- |
| Deploy to production | allow  | API key `ci-deploy` | tag `production` | `deploy` |

Grant the unix login it actually needs. If the deploy runs as `deploy`, do not grant `root`.

**4. Put the private key in the pipeline’s secret store.** Nowhere else.

## Using it

GitHub Actions:

```yaml
- name: Deploy
  env:
    SSH_KEY: ${{ secrets.SHELLHUB_DEPLOY_KEY }}
  run: |
    install -m 600 /dev/stdin ~/.ssh/id_ed25519 <<< "$SSH_KEY"
    ssh -o StrictHostKeyChecking=accept-new \
      deploy@mycompany.gateway-01@cloud.shellhub.io \
      'systemctl restart myservice'
```

GitLab CI:

```yaml
deploy:
  script:
    - install -m 600 /dev/stdin ~/.ssh/id_ed25519 <<< "$SHELLHUB_DEPLOY_KEY"
    - ssh -o StrictHostKeyChecking=accept-new
        deploy@mycompany.gateway-01@cloud.shellhub.io
        'systemctl restart myservice'
```

`StrictHostKeyChecking=accept-new` accepts the ShellHub server’s host key on first use. Pinning it properly is better if your runner has persistent state — and be aware that regenerating the server’s SSH host key changes it.

## Deploying to a fleet

Do not enumerate devices in the pipeline. Query them by tag and iterate, so a device added next month is included without an edit:

```bash
$ curl -s -H "X-API-Key: $SHELLHUB_API_KEY" \
    "https://cloud.shellhub.io/api/devices" | \
  jq -r '.[] | select(.tags[]?.name == "production") | .name' | \
  while read -r device; do
    ssh "deploy@mycompany.$device@cloud.shellhub.io" 'systemctl restart myservice'
  done
```

That needs both credentials, and they are different things: an [API key](https://docs.shellhub.io/api#creating-a-key) to list devices over HTTP, and the SSH key that key owns to connect. Neither substitutes for the other, though both belong to the same principal.

For anything beyond a loop, use [Ansible](https://docs.shellhub.io/api/ansible).

## Short-lived credentials

For a genuinely one-shot job — a provisioning run, a migration — an automation’s key can be **single use**: spent after one connection. Combined with an expiry, that is the tightest credential available.

## What to watch for

**A device the policy misses** fails as unreachable, which looks like a network problem. Check the policy before the network.

**Ephemeral runners** each connect fresh, so the key must already be an identity — a runner cannot complete a browser approval.

**Sessions are attributed and recorded** like any other. If recording is on, pipeline sessions are recorded too.

## Where to go next

- [SSH Access](https://docs.shellhub.io/api/ssh-access) — The principal a pipeline should hold.
- [Ansible](https://docs.shellhub.io/api/ansible) — Beyond a shell loop.
- [Provisioning Keys](https://docs.shellhub.io/manage/devices/provisioning-keys) — Enrolling what the pipeline creates.
