> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/getting-started/self-serve-onboarding.md).

# Self-Serve Workspace Onboarding

Connect a non-production application, code repository, and team tools in the ContextQA self-serve onboarding flow, then verify the generated workspace.

## Quick answer

ContextQA self-serve onboarding collects a reachable non-production application URL, a dedicated test account when authentication is required, testing context, and optional code, delivery-tool, and AI-agent connections. Check the endpoint, choose a Slack notification channel when Slack is connected, and use **Review setup** before entering the workspace. Analysis can continue in the background while ContextQA prepares the dashboard.

## What this page covers

{% hint style="info" %}
**Who is this for?** Workspace owners evaluating ContextQA or setting up a new self-serve workspace for a QA, engineering, or product team.
{% endhint %}

{% hint style="warning" %}
Use a reachable **non-production** environment and a dedicated test account with the minimum permissions required for the selected workflow. Do not enter production customer credentials, payment data, or other sensitive records.
{% endhint %}

## What you need before setup

| Item                 | Requirement                                                                            |
| -------------------- | -------------------------------------------------------------------------------------- |
| Application endpoint | A staging, QA, demo, or other non-production URL that ContextQA can reach              |
| Test account         | Required email address or username, plus a password, when the application needs login  |
| Workflow context     | The problem you want to solve, your role, and your current testing maturity            |
| Code connection      | Optional GitHub or GitLab access to an eligible repository                             |
| Team tools           | Optional Jira, Linear, and Slack connections                                           |
| AI client            | Optional ChatGPT, Claude, Claude Code, Cursor, Codex, or another compatible MCP client |
| Teammates            | Optional email addresses for people who should join the workspace                      |

## Onboarding flow

```mermaid
flowchart LR
    A[Application URL and test account] --> B[Check connection]
    B --> C[Goals, role, and maturity]
    C --> D{Connect code?}
    D -- GitHub or GitLab --> E[Select and validate repository]
    D -- Skip --> F[Connect team tools]
    E --> F
    F --> G[Choose Slack channel when connected]
    G --> H[Analysis and initial coverage drafts]
    H --> I{Connect an AI agent?}
    I -- Configure MCP --> J[Copy client configuration<br/>and optionally add the agent skill]
    I -- Skip --> K[Invite teammates]
    J --> K
    K --> L[Review setup]
    L --> M[Open workspace dashboard]
```

The diagram is a retrieval-friendly summary of the current flow. The exact integrations shown can vary by workspace and rollout.

## 1. Tell ContextQA what you are building

On **Tell us what you're building**, enter the application name or description and a URL for your team's environment.

If the application requires authentication:

1. Enable the login option.
2. Enter the dedicated test-account email address or username and its password. Both fields are required.
3. Verify that the account can reach the intended starting page without production-only data.
4. Review the endpoint and credentials before continuing.

Use a dedicated test account and non-production environment that do not present interactive CAPTCHA or multi-factor prompts during the automated crawl. Do not disable those protections on a production account or customer-facing environment.

Starting the crawl is a one-way transition in the onboarding flow. If the connection succeeds, you cannot return to this first step. If the connection fails, update the endpoint or test credentials and retry when the recovery controls appear.

{% hint style="info" %}
Localhost targets are not available in the current self-serve flow. Use a reachable non-production endpoint or ask your ContextQA administrator about an approved private-connectivity option.
{% endhint %}

## 2. Add testing context

Use **What brought you here?** to identify:

* the quality or delivery problem you want to solve;
* your role; and
* the team's current automation maturity.

Choose the closest available answers. This context helps ContextQA shape the initial workspace without replacing human review of generated tests or coverage suggestions.

## 3. Connect your code

Under **Connect your code**, choose GitHub or GitLab, authorize the approved organization, and select the repository and default branch. In the integration details, an administrator can enable or disable an eligible repository for analysis without disconnecting the entire provider.

ContextQA validates repository compatibility before completing this step. If validation fails, confirm that you selected the intended repository and that the authorized account can read it.

The onboarding screen explains what happens next:

1. ContextQA uses the application and repository context to propose initial tests.
2. Suggested coverage remains a draft until it is reviewed.
3. PR Impact can check eligible new pull requests after setup.

{% hint style="warning" %}
The code connection used by this flow is read-only. Generated coverage and PR Impact recommendations still require review; connecting a repository does not authorize ContextQA to merge code or silently change test cases.
{% endhint %}

You can skip the code connection and add it later if your evaluation begins with application discovery or manually authored tests.

## 4. Connect team tools

The tool-connection step can offer Jira, Linear, and Slack. Connect only the systems needed for the evaluation and use an account approved by the relevant system owner.

| Connection | Typical purpose                                                           |
| ---------- | ------------------------------------------------------------------------- |
| Jira       | Bring requirements or work items into a reviewed test-generation workflow |
| Linear     | Connect issue context for supported requirement and defect workflows      |
| Slack      | Send approved workspace or execution notifications to a selected channel  |

Some rows or follow-on capabilities are shown only when their prerequisite integration is connected. Availability can also depend on the workspace rollout.

After Slack connects, select a **Default channel**. Search by channel name and save the destination that should receive this workspace's findings and activity. ContextQA can join a public channel when you save it. For a private channel, invite the ContextQA Slack app first, then check access and save again. If the picker asks for new permissions, choose **Reconnect Slack** and complete the authorization flow.

## 5. Let analysis run

After the application and optional repository are connected, ContextQA can analyze the available context and prepare the initial workspace. The activity view shows progress while discovery runs, and the flow can continue in the background.

Do not treat a generated test or coverage value as approved simply because analysis completed. Open the resulting draft, verify its preconditions and assertions, and execute it against the intended environment.

## 6. Connect an AI agent (optional)

The **Bring ContextQA into your AI agent** step can provide client-specific setup for supported MCP clients. Choose the client, copy the configuration, and finish the ContextQA sign-in from that client. You can also download the ContextQA agent skill or copy its companion prompt. The skill file does not contain ContextQA credentials; OAuth and the signed-in user's permissions still control which workspace and actions are available.

This step is optional. Skip it when an administrator must review the connection first, then return to **Settings → MCP** after onboarding. Begin with a read-only request so you can confirm the selected organization and available tools before authorizing changes or executions.

See [Install and set up the ContextQA MCP server](/mcp-server/installation-and-setup.md) for client-specific instructions.

## 7. Invite teammates and enter the workspace

Add one or more teammate email addresses as chips, or skip invitations and add users later. When setup is ready, open **Review setup** to check the workspace, product context, code, integrations, team, and trial selections in one place. Incomplete optional items remain visible on the dashboard under **Finish setting up**. Select **Go to dashboard** when the summary matches the intended workspace. If an optional payment action is presented, you can complete it separately from the workspace-entry action.

## Verify the setup

After opening the dashboard, confirm that:

* the correct workspace and application are selected;
* any connected repository and integrations show the expected account or organization;
* initial tests or coverage suggestions are drafts until reviewed;
* recent activity reflects the completed setup; and
* invited users receive only the role and access intended for them; and
* an AI client, when connected, is signed into the intended ContextQA account and passes a read-only verification.

{% hint style="warning" %}
Before authorizing GitHub, GitLab, Jira, Linear, or Slack, review the provider's permission screen and your organization's approved data-handling requirements. Do not infer a retention or deletion policy from the onboarding screen; use the applicable agreement and your administrator's controls for that decision.
{% endhint %}

## Common questions

<details>

<summary>Can I skip GitHub, GitLab, Jira, Linear, or Slack?</summary>

Yes. The code and team-tool connections are optional in the self-serve flow. You can begin with the application endpoint and add approved integrations later.

</details>

<details>

<summary>Why can I not return to the application step?</summary>

Once a successful connection starts the crawl, the flow prevents returning to the first step so that the active analysis is not silently detached from its source. A failed connection can expose controls to update the endpoint or credentials and retry.

</details>

<details>

<summary>Does connecting a repository let ContextQA write to it?</summary>

The self-serve code connection is described as read-only. ContextQA uses the selected repository as context for initial coverage and eligible PR Impact analysis; normal repository controls continue to govern code changes.

</details>

<details>

<summary>What should I do if analysis is still running?</summary>

Leave the analysis running and continue when the flow says the workspace is ready. After entering the dashboard, use recent activity and the generated drafts to confirm that processing completed before making a coverage decision.

</details>

## Related documentation

* [Quick Start](/getting-started/quickstart.md)
* [Requirements Management](/web-testing/requirements-management.md)
* [PR Impact Analysis](/ai-features/pr-impact-analysis.md)
* [Integrations Overview](/integrations/integrations.md)
* [Team Management](/administration/team-management.md)

{% hint style="info" %}
**Want help configuring the first workspace safely?** [**Book a Demo →**](https://contextqa.com/book-a-demo/?utm_source=learning.contextqa.com\&utm_medium=referral\&utm_campaign=docs_demand_gen\&utm_content=self_serve_onboarding) — Use your non-production application and evaluation goals in a guided setup.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://learning.contextqa.com/getting-started/self-serve-onboarding.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.