---
title: "RemotiveTopology in CI"
description: "Run RemotiveTopology in CI pipelines with a RemotiveCloud service account instead of personal tokens, and create one in the console or with RemotiveCLI."
source: https://developer.remotivelabs.com/docs/remotive-topology/usage/ci
last_updated: 2026-11-20
---

# RemotiveTopology in CI

## RemotiveTopology in CI

A CI job that runs RemotiveTopology needs access to RemotiveCloud: starting a topology checks that your organization has a RemotiveTopology subscription. The job shouldn't do that with a person's login. It uses a **service account**, an account made for automation, with an **access token** stored as a secret in your CI provider.

This page takes you from nothing to a job that runs `remotive topology` commands:

1. [Choose the project](#step-1-choose-the-project) the service account lives in.
2. [Create the service account and its access token](#step-2-create-the-service-account-and-its-access-token).
3. [Store the token and the organization as secrets](#step-3-store-the-secrets-in-your-ci-provider).
4. [Use them in the job](#step-4-use-them-in-the-job).

This page is about the access. How a topology is built, started with a test container, and torn down is in [Running a topology](https://developer.remotivelabs.com/docs/remotive-topology/usage/run.md), and the job in step 4 uses those commands.

## How access works

Four things fit together, from the outside in:

- An **organization** is your company in [RemotiveCloud](https://cloud.remotivelabs.com). It holds the members and the RemotiveTopology subscription. In the CLI it's the `REMOTIVE_CLOUD_ORGANIZATION` environment variable or `--organization`.
- A **project** is a team or a department within the organization. It holds the members and service accounts that work in it, and it's the unit of access. In the CLI it's `REMOTIVE_CLOUD_PROJECT` or `--project`, by the project's ID.
- A **service account** belongs to exactly one project and acts with the roles you give it. To run topologies it needs the **RemotiveTopology Executor** role, which the CLI calls `org/topologyRunner`.
- An **access token** is the secret a service account signs in with. It reaches the project the account belongs to and nothing else, which is what makes it safe to hand to a CI job. The CLI reads it from `REMOTIVE_CLOUD_AUTH_TOKEN`, with no login step.

Creating a service account needs the `project/admin` role in its project. If you created a personal account to evaluate RemotiveCloud or RemotiveTopology, you administer that personal project.

## Good practice

- **One project per team or department.** Its service accounts stay together, and a token reaches only that project.
- **One service account per pipeline.** A "service" is a single CI pipeline, deploy job or automated workflow, not the whole organization. Each account gets only the permissions its pipeline needs, actions in logs map to the pipeline that performed them, you can rotate or revoke one without breaking the others, and a leaked token compromises one pipeline. A shared `ci-bot` account is a small convenience and a large cost when something goes wrong.
- **Name for traceability.** The name should make it obvious which pipeline owns the account, such as `ci-gh-pr-checks` or `ci-gh-engine-tests`.
- **Keep service accounts for automation.** Developers use their personal accounts.

## What you need

For the steps on this page:

- [RemotiveCLI](https://developer.remotivelabs.com/docs/remotive-cli/installation.md) 0.44.0 or later installed on your machine, and signed in as yourself with `remotive auth login`. Version 0.44.0 moved sign-in and service accounts from `remotive cloud` to `remotive auth`; older versions have the same commands under `remotive cloud`. The service account is created with your login; only the CI job uses the token.
- The `project/admin` role in the project the CI job uses. Creating a service account or an access token in a project needs it.

## Step 1: choose the project

Use your team's or department's project. Invite at least one more member so you aren't alone to administer it.

### If you aren't its administrator

Ask its administrator for the `project/admin` role. The guided flow in step 2 helps you find out: when it finds no project you administer, it lists the projects you are in with your roles, so you know whom to ask.

## Step 2: create the service account and its access token

Name the service account after the pipeline that uses it and give it only the roles that pipeline needs. For topologies that's `org/topologyRunner`.

Let the CLI guide you:

```sh
remotive auth service-accounts create --it
```

It asks for the organization and the project, then the name and roles of the new service account, and creates the account and an access token. The token file is saved in the configuration directory of the CLI. This recording creates `github-sil` in a project of a demo organization, with the `org/topologyRunner` role:

[Terminal recording (asciicast): Creating a service account and its access token with remotive auth service-accounts create --it](https://developer.remotivelabs.com/casts/service_account_create.cast)

At the end it offers to print the token. Answer yes to copy it right away, or print it later with `remotive auth print-access-token`, as the last line of the recording shows. The token, starting with `sa`, is what goes into your CI provider in step 3. A service account has an email of its own, `<name>@sa.<project>.remotivecloud.com`, which is how you refer to it when printing the token later.

A few things the guided flow does for you:

- With `--project` given or `REMOTIVE_CLOUD_PROJECT` set, it skips the organization and project questions.
- When the project already has service accounts, it offers to create a new access token for one of them instead of a new account. That's how you rotate a token.
- Ctrl-C at any question stops it, and it tells you what was created by then.

## Step 3: store the secrets in your CI provider

Store two values in your CI provider's secret store, such as GitHub Actions secrets or GitLab CI variables:

| Secret                        | Value                                                                                   |
| ----------------------------- | --------------------------------------------------------------------------------------- |
| `REMOTIVE_CLOUD_AUTH_TOKEN`   | The access token printed in step 2.                                                     |
| `REMOTIVE_CLOUD_ORGANIZATION` | The ID of the organization with the RemotiveTopology subscription, from `remotive cloud organizations list`. |

Never commit the token or the token file. Keep it out of logs too: print it only to copy it.

> **Warning: Don't activate the token in your own CLI**
>
> `remotive auth activate` would make the service account your active account, so your own commands would run as the CI job, with its narrow access, and fail in ways that are hard to explain. Use your personal login on your machine and the token only in CI.

## Step 4: use them in the job

Expose the two secrets as environment variables and the CLI picks them up. This GitHub Actions job installs the CLI, checks who it runs as, builds the topology, runs it with a test container and cleans up:

```yaml
jobs:
  topology-tests:
    runs-on: ubuntu-latest
    env:
      REMOTIVE_CLOUD_AUTH_TOKEN: ${{ secrets.REMOTIVE_CLOUD_AUTH_TOKEN }}
      REMOTIVE_CLOUD_ORGANIZATION: ${{ secrets.REMOTIVE_CLOUD_ORGANIZATION }}
    steps:
      - uses: actions/checkout@v4
      - name: Install RemotiveCLI
        run: pipx install remotivelabs-cli
      - name: Check the service account
        run: remotive auth whoami
      - name: Build the topology
        run: remotive topology build -f mytopology.instance.yaml build
      - name: Run the tests
        run: docker compose -f build/mytopology/docker-compose.yml --profile tester up --abort-on-container-exit --exit-code-from tester
      - name: Clean up
        if: always()
        run: docker compose -f build/mytopology/docker-compose.yml --profile tester down
```

`remotive auth whoami` shows the service account's email when the token works, which makes a wrong secret fail early and clearly. The build is the step that needs the subscription, and so the token. The `tester` profile, the test container, and `--abort-on-container-exit` are explained in [Running a topology](https://developer.remotivelabs.com/docs/remotive-topology/usage/run.md); `--exit-code-from tester` makes the step's exit code the test container's, so a failed test fails the job. Other CI providers work the same way: set the two variables in the job's environment.

## Rotate and clean up

Rotate the token on a cadence, and right away if it may have been exposed. Run the guided flow again and pick the existing service account to get a new token, update the secret in your CI provider, then revoke the old token:

```sh
remotive auth service-accounts tokens list --service-account ci-gh-pr-checks --project my-project
remotive auth service-accounts tokens revoke 63F172EF3082FD47 --service-account ci-gh-pr-checks --project my-project
```

When a pipeline is retired, delete its service account, which revokes all its tokens:

```sh
remotive auth service-accounts delete ci-gh-pr-checks --project my-project
```

## Reference

| Environment variable          | Used for                                                                     |
| ----------------------------- | ---------------------------------------------------------------------------- |
| `REMOTIVE_CLOUD_AUTH_TOKEN`   | The access token the CLI signs in with, instead of a login.                  |
| `REMOTIVE_CLOUD_ORGANIZATION` | The organization, for commands and checks that need one, such as the subscription check. |
| `REMOTIVE_CLOUD_PROJECT`      | The project, for commands that take `--project`.                             |

More on managing service accounts, tokens, and projects:

- [Service accounts in RemotiveCloud](https://developer.remotivelabs.com/docs/cloud/Project/Projects.md#service-accounts), with the console's how-tos.
- [The `remotive auth service-accounts` commands](https://developer.remotivelabs.com/docs/remotive-cli/cli_man_pages.md#remotive-auth-service-accounts) in the CLI manual.
