Skip to main content

Roles & Permissions

Roles determine what team members (or integrations) can do inside a project. Pair them with organisation access levels and groups to build a thorough access model.

Permission groups​

Permissions are organised by functional area (Projects, Test Cases, Test Suites, Test Runs, Defects, Requirements, Integrations, etc.). Each permission group typically supports the actions:

  • read
  • create
  • update
  • delete

Some groups expose additional actions (e.g., execute, manage_reviews). View the full list under Configuration → Roles; TestFish automatically surfaces new groups when features ship.

Role types​

  • System roles – Created by TestFish for core use cases (Owner, Admin, Tester, Viewer, API Integration, Webhook Integration, Jira App). These cannot be deleted but can be cloned.
  • Custom roles – Build roles tailored to your workflow (e.g., “Contractor – Execute only” or “Automation – Read repository”).
  • API token roles – When you generate API tokens, TestFish can create dedicated roles with the minimum required scope.

Applying roles​

  • Users – Assign a role per project when inviting a user or editing membership.
  • Groups – Apply roles to groups; user-level assignments override group roles for fine-grained control.
  • Public projects – Require a default role so everyone in the organisation inherits appropriate permissions.

Best practices​

  • Start from a system role and adjust rather than building from scratch.
  • Keep roles focused; it is better to create multiple targeted roles than one role with every permission.
  • Review roles quarterly—especially if you add new permission groups (e.g., integrations, automated runs).
  • Use audit logs to confirm which role made a change when troubleshooting.