> ## 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.

# What Aspect needs from you

> The integrations and credentials Aspect needs to stand up an Aspect Enterprise deployment in its cloud: the VCS app, the CI provider credential, identity provider choice, and DNS.

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

This page is for teams getting an Aspect Enterprise deployment hosted by Aspect. Standing it up needs the following from you; Aspect does everything else.

Runners clone your repository with the credentials your CI provider issues, as your existing runners do. The checkout sits on the runner's disk in your deployment and goes when the runner is recycled.

## 1. A version control integration

Status checks, PR comments and inline lint findings reach your VCS through the Aspect Workflows GitHub App or GitLab App, installed on your organization. It's the same app and install flow the [Aspect CLI](/docs/cli/authentication) uses, so if you've already installed it for CLI features, this step is done.

<CardGroup cols={2}>
  <Card title="GitHub App" icon="github" href="/docs/cli/authentication-github">
    Install the Aspect Workflows GitHub App on your organization and link it to your Aspect account.
  </Card>

  <Card title="GitLab App" icon="gitlab" href="/docs/cli/authentication-gitlab">
    Link the Aspect Workflows GitLab App to your Aspect account.
  </Card>
</CardGroup>

Someone with admin rights on the VCS organization installs the app. Linking it needs the **Account Owner**, **Account Admin**, or the matching **GitHub Integration Admin** / **GitLab Integration Admin** role in the [Aspect settings](https://app.aspect.build/settings/org/users).

## 2. A CI provider credential, if you use Workflows CI runners

Workflows registers its managed CI runners with your CI provider and polls it for queue depth to drive scaling. That needs one credential, which differs by provider.

If you bring your own CI runners, on any CI system, and use only the remote cache, remote execution and Build Results UI, skip this step.

| Provider           | What Aspect needs                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Used for                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **GitHub Actions** | The App ID and private key (PEM) of a second GitHub App you create for runner registration, separate from the Aspect Workflows GitHub App. It needs **Actions: Read-only** (repository) and **Self-hosted runners: Read and write** (organization); see <GatedLink access={gatedAccess(user, "workflows-subscriber")} href="/docs/aspect-workflows/enterprise/self-hosted/runner-registration/github-actions#step-1-create-the-github-app" group="workflows-subscriber">creating it</GatedLink> | Registering runners as self-hosted runners; querying queued jobs for scaling |
| **Buildkite**      | An agent token, plus an API access token with `Read Agents` and `Write Agents` scopes                                                                                                                                                                                                                                                                                                                                                                                                           | Agents joining their cluster queue; counting queued and running jobs         |
| **GitLab**         | A GitLab personal access token with the `api` scope, one per runner group; see <GatedLink access={gatedAccess(user, "workflows-subscriber")} href="/docs/aspect-workflows/enterprise/self-hosted/runner-registration/gitlab#step-2-create-credentials" group="workflows-subscriber">creating it</GatedLink>                                                                                                                                                                                     | Registering runners and maintaining their metadata; reading job queue depth  |
| **CircleCI**       | A self-hosted runner resource-class token and an API access token                                                                                                                                                                                                                                                                                                                                                                                                                               | Runner registration at boot; queue polling for scaling                       |

Send these through the secure channel your Aspect contact provides, not over email or a shared document. They're stored in the deployment's secret manager and readable only by the services that need them.

<Note>
  These credentials scope to runner registration and queue introspection. They don't give
  Aspect write access to your repositories; posting status checks and PR comments goes
  through the VCS app in step 1, which has its own, separately granted permissions.
</Note>

## 3. An identity provider decision

Choose how developers authenticate to the Build Results UI and to the external cache and execution endpoints:

* **Aspect sign-in (standard).** Aspect operates the identity provider. It can connect to your identity provider for SSO, and people still sign in to Aspect accounts. Users are invited through the [Aspect settings](https://app.aspect.build/settings/org/users). Without SSO there's nothing to configure on your side. Either way, Aspect API tokens are available for CI and headless use.
* **Your own identity provider**, an optional customization that replaces Aspect sign-in. The deployment authenticates against your directory directly, with no Aspect accounts. You supply the issuer URL, client ID and client secret, and register Aspect's redirect URIs at your IdP.

With Aspect sign-in, SCIM provisioning can sync users from your directory. With your own identity provider you don't need it: you manage users and groups there directly.

Replacing Aspect sign-in changes how non-interactive clients authenticate: there's no Aspect API token, and you supply your own credential helper for CI. Read [If the deployment uses your own identity provider](/docs/aspect-workflows/enterprise/connect/ci-setup#if-the-deployment-uses-your-own-identity-provider) before deciding.

## 4. A DNS decision

Standard deployments serve their endpoints on Aspect's domain, and Aspect issues and renews the certificates. Nothing is needed from you.

If you'd rather the endpoints sat on your own domain, you delegate a subdomain to Aspect, for example `aspect.example.com`, and Aspect issues and renews certificates inside it. That's a one-time DNS change.

## What you get back

When the deployment is up, Aspect gives you:

* **The deployment host**, for example `remote.<your-deployment>.aspect.build`. This is the one string developers need: [`aspect auth configure`](/docs/aspect-workflows/enterprise/connect/local-setup) discovers the cache, build event and remote execution endpoints from it.
* **The Build Results UI URL**, on the same domain as the host, under `app.`.
* **The runner group names** your CI jobs target. See [Targeting runner groups from CI](/docs/aspect-workflows/enterprise/ci-runners/runner-groups).
* **The remote execution platform properties** your Bazel exec platforms must advertise. See [Targeting remote execution worker pools](/docs/aspect-workflows/platform/guides/remote-execution-worker-pools).

From there, see [local setup](/docs/aspect-workflows/enterprise/connect/local-setup) and [CI setup](/docs/aspect-workflows/enterprise/connect/ci-setup).