Skip to main content

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 the service account lives in.
  2. Create the service account and its access token.
  3. Store the token and the organization as secrets.
  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, 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. 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 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:

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:

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:

SecretValue
REMOTIVE_CLOUD_AUTH_TOKENThe access token printed in step 2.
REMOTIVE_CLOUD_ORGANIZATIONThe 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.

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:

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; --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:

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:

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

Reference​

Environment variableUsed for
REMOTIVE_CLOUD_AUTH_TOKENThe access token the CLI signs in with, instead of a login.
REMOTIVE_CLOUD_ORGANIZATIONThe organization, for commands and checks that need one, such as the subscription check.
REMOTIVE_CLOUD_PROJECTThe project, for commands that take --project.

More on managing service accounts, tokens, and projects: