> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Running an Aspect Enterprise trial

> Run your existing pipeline on an Aspect Enterprise deployment alongside your current CI, without blocking anyone: take a baseline, dark-launch, then fix what the new environment exposes.

export const gatedAccess = (user, group) => {
  const loggedIn = !!(user && user.loggedIn);
  const groups = user && user.tenantMetadata && user.tenantMetadata.docsGroups || [];
  if (loggedIn && (!group || groups.indexOf(group) >= 0)) {
    return "entitled";
  }
  return loggedIn ? "signed-in" : "anonymous";
};

export const GatedLink = ({access, href, group, children}) => {
  const note = group ? "Aspect Enterprise customers" : "free Aspect account";
  const muted = {
    fontSize: "0.85em",
    opacity: 0.7,
    whiteSpace: "nowrap"
  };
  if (access === "entitled") {
    return <a href={href}>{children}</a>;
  }
  if (access !== "signed-in") {
    return <span>
        <a href={"/login?redirect=" + encodeURIComponent(href)}>{children}</a>
        <span style={muted}> (sign in: {note})</span>
      </span>;
  }
  return <span>
      {children}
      <span style={muted}> ({note})</span>
    </span>;
};

A 30-day trial of [Aspect Enterprise](/docs/aspect-workflows/enterprise/overview) runs your existing pipeline on a deployment next to your current CI, on the same commits, without blocking anyone. Your `bazel build` and `bazel test` steps run unchanged. When it's green, you [measure the result](/docs/aspect-workflows/enterprise/evaluation/measuring) against the baseline you took first.

[Talk to us](/contact) to agree the trial's terms and success criteria.

## Who does what

|                                                 | [Hosted by Aspect](/docs/aspect-workflows/enterprise/hosted/overview)        | [Self-hosted](/docs/aspect-workflows/enterprise/self-hosted)                                                                                                                                                          |
| ----------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Stands the deployment up**                    | Aspect                                                                       | You, [in your AWS account or GCP project](/docs/aspect-workflows/enterprise/self-hosted)                                                                                                                              |
| **Registers the runners with your CI provider** | Aspect                                                                       | You; see <GatedLink access={gatedAccess(user, "workflows-subscriber")} href="/docs/aspect-workflows/enterprise/self-hosted/runner-registration/overview" group="workflows-subscriber">runner registration</GatedLink> |
| **What you provide**                            | [What Aspect needs from you](/docs/aspect-workflows/enterprise/hosted/setup) | The deployment, and its runner registration                                                                                                                                                                           |

The deployment has to be ready for CI traffic, with its runners registered, before you dark-launch in step 2.

## 1. Take a baseline

Before changing anything, record how your current CI performs. [Measuring results](/docs/aspect-workflows/enterprise/evaluation/measuring#what-to-measure) lists what to capture. A week of ordinary traffic is enough.

## 2. Dark-launch a copy of your pipeline

Add a job that runs your existing build and test steps on a Workflows runner group, next to your current jobs. It targets the group with your CI provider's own selector, adds the setup step, and is marked so a failure can't block a merge:

<Tabs>
  <Tab title="GitHub Actions">
    ```yaml theme={null}
    permissions:
      contents: read
      id-token: write    # artifact uploads and the PR summary comment

    jobs:
      test-on-aspect:
        runs-on: [self-hosted, aspect-workflows, aspect-default]
        continue-on-error: true
        steps:
          - uses: actions/checkout@v6
          - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
          - run: bazel test //...
    ```

    Don't add the job to your branch protection's required checks.
  </Tab>

  <Tab title="Buildkite">
    ```yaml theme={null}
    steps:
      - label: "test on Aspect"
        agents:
          queue: aspect-default
        plugins:
          - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
        command: bazel test //...
        soft_fail: true
    ```
  </Tab>

  <Tab title="GitLab CI">
    ```yaml theme={null}
    include:
      - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

    test-on-aspect:
      extends: .setup-aspect
      tags: [aspect-workflows, aspect-default]
      allow_failure: true
      script:
        - bazel test //...
    ```
  </Tab>

  <Tab title="CircleCI">
    ```yaml theme={null}
    version: 2.1

    orbs:
      setup-aspect: aspect-build/setup-aspect@2026.38.2

    jobs:
      test-on-aspect:
        machine: true
        resource_class: YOUR-ORG/aspect-default
        working_directory: /mnt/ephemeral/workdir
        steps:
          - checkout
          - setup-aspect/setup
          - run: bazel test //...
    ```

    CircleCI has no per-job allow-failure. Run the job in its own workflow and leave it out of your required status checks.
  </Tab>
</Tabs>

Run it on `main`, on pull requests, or both. Pull requests give you the numbers developers actually feel; `main` gives you a steady stream of comparable builds.

The runner group name and each provider's selector are covered in [runner groups](/docs/aspect-workflows/enterprise/ci-runners/runner-groups).

## 3. Exclude tests that only work on your current CI

Some tests depend on something only your current CI can reach: a database, an internal service, a license server. Tag them:

```python title="BUILD.bazel" theme={null}
some_test(
    name = "only_works_on_legacy",
    tags = ["requires-legacy-ci"],
)
```

Exclude the tag in a `poc` config group, so only the dark-launched job sees it and your current CI and every developer's build are unchanged:

```bash title=".bazelrc" theme={null}
test:poc --test_tag_filters=-requires-legacy-ci
```

Add `--config=poc` to the dark-launched job's `bazel` calls, such as `bazel test //... --config=poc`.

Keep the list short and write it down. Each of these is either a network path to open or a test to fix before you switch over.

## 4. Turn on the `poc` group from `config.axl`

If the dark-launched job runs Aspect CLI tasks, such as `aspect test`, turn the `poc` group on in `config.axl` instead of adding `--config=poc` to each call. The check limits it to Workflows runners, so the same tasks on your current CI and on developer machines are unchanged:

```python title=".aspect/config.axl" theme={null}
load("@aspect//traits.axl", "BazelTrait")

def config(ctx: ConfigContext):
    if bool(ctx.std.env.var("ASPECT_WORKFLOWS_RUNNER")):
        ctx.traits[BazelTrait].extra_flags.extend(["--config=poc"])
```

`config.axl` applies to `aspect` tasks only. A plain `bazel` call still takes `--config=poc` on its command line. Remove the group once every tagged test is fixed or can reach what it needs.

## 5. Add what a non-hermetic build needs on the machine

If the build depends on something installed on the machine rather than fetched by Bazel, such as a system library a C++ target links against, the runners need it too:

* **Hosted by Aspect:** tell Aspect what's missing; see [requesting changes](/docs/aspect-workflows/enterprise/hosted/requesting-changes).
* **Self-hosted:** build a runner image with it; see <GatedLink access={gatedAccess(user, "workflows-subscriber")} href="/docs/aspect-workflows/enterprise/self-hosted/infrastructure/machine-images" group="workflows-subscriber">custom machine images</GatedLink>.

## Next

When the dark-launched job is green on ordinary traffic, [measure the result](/docs/aspect-workflows/enterprise/evaluation/measuring).