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

# Clone your workspace with Git

> Clone your QA Wolf flow repository, edit files locally, and push changes to your workspace.

Clone your workspace's flow repository to edit flows, helpers, and [custom skills](https://docs.qawolf.com/custom-skills.md) with your own tools.
Your QA Wolf workspace access controls cloning and pushing.

> [!TIP]
>
> Install Git before you start. Your workspace must have Git access.
> If **Settings > Git** is missing, contact QA Wolf support.

## Authenticate

Choose one authentication method before cloning.

**QA Wolf CLI**

**1. Install the CLI**

[Install the QA Wolf CLI](https://docs.qawolf.com/local-execution/authenticate.md#install-the-cli) with npm or a standalone binary.

The Git credential helper requires a persistent installation.
Running login through `npx` does not configure it.

**2. Sign in**

Run the login command:

```bash theme={null}
qawolf auth login
```

Git uses your CLI sign-in for clone, fetch, and push.

**User API key**

Create a user API key under **Settings > API keys**.
If API keys are unavailable, use the CLI authentication method.

When Git asks for a username, enter `qawolf`.
When Git asks for a password, paste your user API key.
Git requires a non-empty username to send the key.

Organization API keys and legacy workspace API keys cannot authenticate Git requests.
Keep the key out of clone URLs and committed files.

## Clone the repository

**1. Copy the clone command**

Open **Settings > Git** in your workspace.
Under **Clone**, select **Copy clone command**.

**2. Run the command**

Paste the copied command into your terminal.
It uses your workspace's slug:

```bash theme={null}
git clone https://app.qawolf.com/api/git/<workspace-slug>.git
```

Use the copied host if your workspace uses a different QA Wolf deployment.

**3. Open the clone**

Enter the directory that Git created:

```bash theme={null}
cd <workspace-slug>
```

The repository's `origin` points to QA Wolf.
Later fetches and pushes use the same authentication method.
Git access uses HTTPS. QA Wolf does not support SSH, Git LFS, or submodule authentication.

## Edit and push files

> [!WARNING]
>
> A push to an environment branch changes the flows that its scheduled runs use.
> Confirm the target branch before pushing.

**1. Choose the target branch**

Use the branch that your QA Wolf environment or investigation uses:

```bash theme={null}
git fetch origin
git switch <branch-name>
```

Replace `<branch-name>` with the existing branch's name.
Cloning alone does not select your investigation's branch.

**2. Edit the files**

Make your changes in your editor.
For reusable investigation guidance, [add a skill file](https://docs.qawolf.com/custom-skills.md#add-a-skill-through-git).

**3. Review the changes**

Inspect the target branch and changed files:

```bash theme={null}
git status
git diff
```

**4. Commit and push**

Stage only the files you intend to publish:

```bash theme={null}
git add <file-path>
git commit -m "docs(skills): add investigation guidance"
git push
```

QA Wolf imports pushed changes into your workspace.
Changes can appear after Git reports a successful push.
Git pushes support branches. QA Wolf rejects tags and other non-branch writes.

### Associate a new branch with an environment

A branch created through Git has no environment until you associate it.
This makes it available under that environment on the **Flows** page.

**1. Find the branch**

Open **Settings > Git** and find your pushed branch under **Branches**.

**2. Choose the environment**

Select **Associate…** for the branch, then choose its environment.

**3. Confirm the association**

Select **Associate** in the dialog.

> [!WARNING]
>
> You cannot change a branch's environment association later.
> Check the selected environment before confirming.

## Troubleshoot Git access

| Symptom | Action |
| - | - |
| **Git** is missing from Settings | Contact QA Wolf support to confirm that Git access is enabled. |
| Authentication fails | Run `qawolf auth login` again, or use a valid user API key. |
| A user API key fails | Confirm that the key belongs to the workspace's organization and that your user still has access. |
| Git asks for the key on every command | Configure a Git credential helper, or use CLI sign-in. |
| The repository returns `404` | Copy the command from Settings again and confirm your workspace access. |
| A pushed branch is missing from Flows | Associate it with an environment under **Settings > Git > Branches**. |
| A push fails or its connection closes | Fetch and inspect the remote branch before repeating the push. |

Each workspace member can push to every branch, subject to the repository's existing GitHub rules.
Revoke a user API key under **Settings > API keys** to stop its access.
Run `qawolf auth logout` to remove CLI sign-in and its Git credential helper.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.