HermetiqDocsOpen dashboard
Getting started

Get your first build into Hermetiq

Connect Bazel build data to Hermetiq Cloud or your own deployment, secure credentials, and verify ingestion. Continue to executor provisioning for Managed Builds.

Choose Cloud or customer-managed before copying configuration

This guide connects Bazel build data to Hermetiq. To run actions on Hermetiq’s infrastructure, follow the Managed Builds setup path as well.

Prerequisites

Before connecting a build, you need:

  • A Bazel workspace you can run locally or in CI.
  • Access to a Hermetiq project in the correct deployment.
  • Permission to commit a credential helper and Bazel configuration to the workspace, and to add secrets to CI if you build there.
  • For Hermetiq Cloud on a workstation: python3, plus the macOS Keychain or pass on Linux to hold your credentials.

Choose your deployment path

Self-service onboarding in Hermetiq Cloud

Create or join a project in the hosted dashboard, then follow its Quickstart: download the project’s credential helper, issue your own credentials, and copy the Bazel configuration.

Customer-managed onboarding through your administrator

Sign in to your organization’s Hermetiq URL, select an existing project, and obtain the project credential helper from your platform administrator.

Hermetiq Cloud

SOC 2 Type II — powered by VantaSOC 2 Type II · Trust Center

  1. Create or open your hosted account, then create or select the project that should receive the build.
  2. Open Quickstart for that project and download the credential helper and the build metadata script. Save them as tools/hermetiq-credential-helper and tools/set-build-metadata.sh at the workspace root, next to MODULE.bazel or WORKSPACE, make them executable, and commit them. The helper holds no secrets, so every clone and git worktree gets it.
  3. Under Store your credentials, click Issue credentials. Hermetiq shows your client secret once and doesn’t keep it.
  4. Run tools/hermetiq-credential-helper store once per machine. When it asks, click Copy credentials and paste the whole line it copies, {"client_id": "...", "client_secret": "..."}. It saves them in the macOS Keychain, or in pass on Linux.
  5. Copy the generated .bazelrc block. Quickstart supplies the project ID, BEP and results endpoints, the credential-helper lines, build metadata, profile flags, and the optional remote cache.
  6. Optionally, use Quickstart’s Try remote execution step to add flags for Hermetiq’s shared trial workers, which run Ubuntu 22.04 and have limited idle capacity.
Terminal · from the workspace root
chmod +x tools/hermetiq-credential-helper tools/set-build-metadata.sh
git add tools/hermetiq-credential-helper tools/set-build-metadata.sh
tools/hermetiq-credential-helper store

Customer-managed

Installing Hermetiq in your own cluster first? Follow the on-prem installation guide, then return here to connect a build.

  1. Open the dashboard URL supplied by your organization and select the project assigned by your Hermetiq administrator.
  2. Obtain the credential helper through your organization’s approved channel. Customer-managed Quickstart does not create a new hosted credential for you.
  3. Copy the project-specific Quickstart configuration from that deployment. If a value is unavailable, ask the administrator to confirm the BEP, results, cache, and authentication endpoints.

See Deployments for the supported topology and Administration for project and credential ownership.

Credential security and rotation

In Hermetiq Cloud, the credential helper holds only the project ID and Hermetiq’s token endpoint. Each person and each CI system uses their own M2M client ID and secret, which the helper reads, in order, from the HERMETIQ_M2M_CLIENT_ID and HERMETIQ_M2M_CLIENT_SECRET environment variables, the macOS Keychain item hermetiq/<project-id>, or the pass entry of the same name.

  • Commit the helper, but never commit, print or share your credentials, the client ID and secret.
  • Hermetiq shows the secret once. If you lose it, issue new credentials in Quickstart, which revokes the old ones.
  • A customer-managed helper supplied by your administrator may still contain a secret or mTLS material. Keep that one out of git, add its path to .gitignore, and restrict its file permissions.
  • If a secret is exposed, issue new credentials, or have a project admin reset the member’s M2M OAuth client or mTLS certificate in Users, then update every machine and CI secret that used it.

Run your first build

If you kept the default isolated configuration, activate it with --config=hermetiq:

Terminal
bazel build //... --config=hermetiq

If you chose global build entries instead, run your normal Bazel command. CI can use the same configuration once it has its own credentials.

In Hermetiq Cloud, an MCP-connected agent can also do the repository setup through the MCP setup workflow. You still issue and store your own credentials.

Verify the data

  1. Open Build History in the same Cloud or customer-managed dashboard you configured.
  2. Confirm the invocation appears under the expected project.
  3. Open the build to inspect targets, actions, logs, cache, profile, or remote-execution data available for that invocation.

A recorded invocation confirms ingestion. It does not establish that actions ran remotely. For Managed Builds, continue with executor provisioning and configuration, then verify a remotely executed action.

Last reviewedNovember 6, 2026