Skip to main content

CI

Using RemotiveTopology in a CI environment​

When running RemotiveTopology in a CI (Continuous Integration) environment, avoid using personal tokens. Instead, use a service account to ensure secure and maintainable access.

Read more on RemotiveCloud Service accounts.

Use service accounts​

To create a service account, you must be an administrator of the relevant cloud project. If you created a personal account to evaluate RemotiveCloud or RemotiveTopology, you are automatically the administrator of that personal project.

You can create a service account in the RemotiveCloud console or by using RemotiveCLI. In order to run RemotiveTopology, grant the RemotiveTopology Executor role to the service account.

Concept​

In RemotiveCloud, projects are the top-level boundary—typically a team or a product. Inside a project you create service accounts to authenticate non-human callers (CI jobs, schedulers, deployments).

  • One project per team, make sure to invite at least some core members
  • One service account per service. A "service" here means a single CI pipeline, deploy job, or automated workflow—not the whole organization.

Why one service account per service​

  • Least privilege—each account only gets the permissions its workflow actually needs.
  • Clear audit trail—actions in logs map directly to the service that performed them.
  • Independent rotation—rotate or revoke one account without breaking unrelated pipelines.
  • Blast radius—a leaked credential only compromises one workflow.

Avoid sharing a single "ci-bot" account across every pipeline. The convenience cost is small; the security cost when something goes wrong is large.

Setup​

  1. Create the project that owns the resources the CI job accesses. This project should be for your team or product. Invite members (or at least one more member) so you aren't alone to manage this.
  2. Create a service account inside that project, named after the service that uses it—e.g. ci-gh-engine-tests, ci-gh-pr-checks, etc. Make sure to include RemotiveTopology Executor role.
  3. Generate a token for the service account and store it in your CI provider's secret store (GitHub Actions secrets, GitLab CI variables, etc.). Never commit it.
  4. Expose it as REMOTIVE_CLOUD_AUTH_TOKEN in the job's environment. The CLI picks the token up from this variable automatically—no login step needed.

In your CI config​

Just set the environment variable; the CLI uses it directly:

# GitHub Actions example
jobs:
  deploy:
    env:
      REMOTIVE_CLOUD_AUTH_TOKEN: ${{ secrets.REMOTIVE_CLOUD_AUTH_TOKEN }}
      REMOTIVE_CLOUD_ORGANIZATION: my-org
    steps:
      - run: remotive cloud auth whoami

You can also pin the organization with REMOTIVE_CLOUD_ORGANIZATION so commands don't depend on a configured active account.

Operational guidance​

  • Rotate regularly. Set a rotation cadence and rotate immediately if a token may have been exposed.
  • Scope to one project. A service account belongs to one project; resist creating cross-project accounts.
  • Name for traceability. The name should make it obvious which pipeline owns it.
  • Clean up. When a pipeline is retired, delete its service account.
  • Don't reuse for local development. Developers should use their personal accounts; service account tokens are for automation only.

To create the service account in the CLI​

# Automatically picked up as project
export REMOTIVE_CLOUD_PROJECT=my-project
export SA_NAME=gh-action-runner

remotive cloud service-accounts create $SA_NAME --role org/topologyRunner

# Create the access token for the service account
remotive cloud service-accounts tokens create --service-account $SA_NAME

# This will show all your accounts, including service-accounts. Select the number of your service account.
remotive cloud auth activate
    ┏━━━┳━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
    ┃ # ┃ Active ┃ Type ┃ Token ID         ┃ Account                                        ┃ Created    ┃ Expires    ┃
    ┡━━━╇━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
    │ 1 │        │ sa   │ 63F172EF3082FD47 │ my-docs-test-sa@sa.my-project.remotivecloud.com│ 2026-05-06 │ 2027-05-06 │
    │ 2 │ ✅     │ user │ 2C63465D9688B0AF │ dev@remotivelabs.com                           │ 2026-04-10 │ 2027-04-10 │
    └───┴────────┴──────┴──────────────────┴────────────────────────────────────────────────┴────────────┴────────────┘
    👉 To get the access token for your activated account, use remotive cloud auth print-access-token


# Now, the access token that will be used in REMOTIVE_CLOUD_AUTH_TOKEN
remotive cloud auth print-access-token
    sax.x/xxxx-xxxxxx-xxxxx-xxxxx

With this information, the following environment variables can be used to handle access to RemotiveCloud and validation of the RemotiveTopology subscription:

  • REMOTIVE_CLOUD_AUTH_TOKEN—Provides an authentication token.
  • REMOTIVE_CLOUD_ORGANIZATION—Provides your RemotiveCloud organization.

RemotiveCLI provides more commands to handle service accounts and tokens. More information can be found in the Service Accounts section in the RemotiveCLI documentation.