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

# Add credentials, roles & permissions

> Configure authentication profiles for different user roles in your tests using environment variables and secure credential management.

Adding credentials, roles, and permissions in Bugster is simple and explicit.
Define multiple credential profiles in config.yaml, keep secrets in environment variables, reference a profile per test with credential\_id, and—if you use the GitHub App—mirror the same variables in your project settings for CI runs.

Bugster doesn’t grant permissions itself; your application enforces them. Bugster simply logs in with the chosen profile so each test runs under the correct role

<Card title="Prerequisites">
  * Bugster CLI installed and authenticated.
  * Access to your app's user accounts with different permission levels.
  * For CI/CD: Bugster GitHub App installed or access to CI secret management.
</Card>

## 1. Add credentials in config.yaml

Create one entry per login profile (each maps to an app role). Use env vars—don't hard-code secrets.

```yaml theme={null}
# bugster/config.yaml
project_name: nextjs-app-demo
project_id: nextjs-app-demo-1755891784
base_url: "http://localhost:3001"

credentials:
  - id: user
    username: ${BUGSTER_USERNAME}
    password: ${BUGSTER_PASSWORD}

  - id: superadmin
    username: ${BUGSTER_USERNAME_SUPERADMIN}
    password: ${BUGSTER_PASSWORD_SUPERADMIN}
```

`id` is the handle you'll reference from tests (e.g., `superadmin`).

## 2. Provide secrets locally (.bugster/.env)

Add the variables to your local Bugster env file.

```bash theme={null}
# .bugster/.env
BUGSTER_USERNAME=user@bugster.dev
BUGSTER_PASSWORD=Password

BUGSTER_USERNAME_SUPERADMIN=superadmin@bugster.dev
BUGSTER_PASSWORD_SUPERADMIN=PasswordSuperadmin
```

## 3. Use a credential in a test

Point the test to the desired profile via `credential_id`.

```yaml theme={null}
name: Home page navigation - Hello component
page: /
page_path: app/page.tsx
credential_id: superadmin
task: Navigate from home page to dashboard
steps:
  - Visit the home page
  - Verify that the Hello component is rendered on the screen
  - Verify that no dashboard navigation links or buttons are present on the page
expected_result: User should see the Hello component rendered instead of dashboard navigation
```

The value must match a `credentials[].id` in `config.yaml`.

## 4. If you use the Bugster GitHub App (CI/CD)

For cloud runs to authenticate, mirror these env vars in your project's settings or your CI secrets.

<Steps>
  <Step title="Open project settings">
    Open your project in `app.bugster.dev` → Settings.
  </Step>

  <Step title="Add environment variables">
    Add the same keys/values you used locally (e.g., `BUGSTER_USERNAME_SUPERADMIN`, `BUGSTER_PASSWORD_SUPERADMIN`).
  </Step>

  <Step title="Save and test">
    Save and re-run your job/PR.
  </Step>
</Steps>

## 5. Quick validation

Run a test that specifies `credential_id` and watch the login succeed:

```bash theme={null}
bugster run .bugster/tests/path/to/test.yaml
```

If a variable is missing/empty, fix it in `.bugster/.env` or CI secrets and re-run.

## 6. Best practices

<Check>
  **Security & Organization:**

  * **One profile per app role.** Name ids by role (`user`, `manager`, `superadmin`) for clarity.
  * **Never commit secrets.** Keep them in env files or CI secret stores, not in Git.
  * **Keep least privilege.** Tests that don't need admin rights should use `user`, not `superadmin`.
  * **Document intent.** Add a short comment near each credential entry describing what the role can do.
</Check>

### Example with role documentation

```yaml theme={null}
credentials:
  # Standard user - can view own data, basic operations
  - id: user
    username: ${BUGSTER_USERNAME}
    password: ${BUGSTER_PASSWORD}

  # Manager - can view team data, approve requests
  - id: manager
    username: ${BUGSTER_USERNAME_MANAGER}
    password: ${BUGSTER_PASSWORD_MANAGER}

  # Super admin - full system access, user management
  - id: superadmin
    username: ${BUGSTER_USERNAME_SUPERADMIN}
    password: ${BUGSTER_PASSWORD_SUPERADMIN}
```