Skip to main content

Role Mapping

Role Mapping lets you automatically assign workspace and repository permissions to users by connecting RepoFlow to your organization’s own API.
With role mapping, you can centralize permission management outside of RepoFlow, great for large teams or integrating with your existing internal systems.

How Role Mapping Works​

  1. When a user logs in or signs up, RepoFlow (if enabled) queries your configured Role Mapping API. The API URL must include a :user-email placeholder that will be replaced with the user's email address at runtime. (Example: http://localhost:9085/roles/alice@example.com)
  2. The API returns a JSON object listing the workspaces and repositories the user should have access to, along with their permission levels.
  3. RepoFlow updates the user's roles accordingly.

To set this up, see the Role Mapping Environment Variables section for details on configuring your API URL, secrets, and enabling this feature.

Example JSON Structure​

Here’s what a typical Role Mapping API response looks like for a user:

{
  "workspaces": [
    {
      "name": "teamOneWorkspace",
      "workspacePermission": "admin"
    },
    {
      "name": "teamTwoWorkspace",
      "workspacePermission": "none",
      "repositories": [
        { "name": "repoOne", "permission": "canDeploy" },
        { "name": "repoTwo", "permission": "canRead" },
        { "name": "repoThree", "permission": "canDeleteOverride" }
      ]
    }
  ]
}
  • workspacePermission must be one of: admin, canDeleteOverride, canDeploy, canRead, none
  • permission (per repository) must be one of: canDeploy, canRead, canDeleteOverride

Try It: Role Mapping JSON Validator​

Use the interactive editor below to validate your Role Mapping JSON before using it with RepoFlow.
You can copy and paste your JSON and see if it matches the expected format.

Loading editor…

Example Project​

Check out the open source Mock Roles API Example for a plug and play Docker container you can use as a starting point or to test your RepoFlow Role Mapping integration.