### Setup Backend Environment and Database

Source: https://github.com/chaoss/grimoirelab-sortinghat/blob/main/README.md

Commands to install Python dependencies using Poetry, activate the virtual environment, and initialize the Django database.

```bash
poetry install
poetry shell
sortinghat-admin --config sortinghat.config.settings setup
```

--------------------------------

### Install System Dependencies for Database

Source: https://github.com/chaoss/grimoirelab-sortinghat/blob/main/README.md

Commands to install necessary MySQL or MariaDB client development libraries on Debian-based systems.

```bash
apt install libmysqlclient-dev
apt install libmariadbclient-dev-compat
```

--------------------------------

### Run Backend and Frontend Services

Source: https://github.com/chaoss/grimoirelab-sortinghat/blob/main/README.md

Commands to start the Django development server and the frontend build process with watch mode.

```bash
./manage.py runserver --settings=sortinghat.config.settings
yarn watch --api_url=http://localhost:8000/api/ --publicpath="/static/" --mode development
```

--------------------------------

### Initialize and Configure SortingHat Server

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Instructions for setting up the SortingHat server, including setting essential environment variables and running the initial setup or upgrade commands. Supports both interactive and non-interactive modes.

```bash
# Set required environment variables
export SORTINGHAT_SECRET_KEY="your-secret-key"
export SORTINGHAT_DB_HOST="localhost"
export SORTINGHAT_DB_PORT="3306"
export SORTINGHAT_DB_USER="sortinghat"
export SORTINGHAT_DB_PASSWORD="password"
export SORTINGHAT_DB_DATABASE="sortinghat_db"

# Run initial setup (creates database, applies migrations, creates superuser)
sortinghat-admin --config sortinghat.config.settings setup

# Non-interactive setup with environment variables
export SORTINGHAT_SUPERUSER_USERNAME="admin"
export SORTINGHAT_SUPERUSER_PASSWORD="admin123"
sortinghat-admin --config sortinghat.config.settings setup --no-interactive

# Upgrade existing installation
sortinghat-admin --config sortinghat.config.settings upgrade
```

--------------------------------

### Deploy SortingHat with Docker Compose

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Configures the SortingHat server, worker, database, and cache services using Docker Compose. Includes environment variable setup and service orchestration.

```yaml
version: '3.8'
services:
  sortinghat:
    build:
      context: .
      dockerfile: docker/server.dockerfile
    environment:
      - SORTINGHAT_SECRET_KEY=your-secret-key
      - SORTINGHAT_DB_HOST=mysql
      - SORTINGHAT_DB_PORT=3306
      - SORTINGHAT_DB_USER=sortinghat
      - SORTINGHAT_DB_PASSWORD=password
      - SORTINGHAT_DB_DATABASE=sortinghat_db
      - SORTINGHAT_REDIS_URL=redis://redis:6379/0
    ports:
      - "9314:9314"
    depends_on:
      - mysql
      - redis
  worker:
    build:
      context: .
      dockerfile: docker/worker.dockerfile
    environment:
      - SORTINGHAT_SECRET_KEY=your-secret-key
      - SORTINGHAT_DB_HOST=mysql
      - SORTINGHAT_DB_PORT=3306
      - SORTINGHAT_DB_USER=sortinghat
      - SORTINGHAT_DB_PASSWORD=password
      - SORTINGHAT_DB_DATABASE=sortinghat_db
      - SORTINGHAT_REDIS_URL=redis://redis:6379/0
    depends_on:
      - mysql
      - redis
  mysql:
    image: mysql:8.1
    environment:
      - MYSQL_ROOT_PASSWORD=root
      - MYSQL_DATABASE=sortinghat_db
      - MYSQL_USER=sortinghat
      - MYSQL_PASSWORD=password
    volumes:
      - mysql_data:/var/lib/mysql
  redis:
    image: redis:7
volumes:
  mysql_data:
```

```bash
docker-compose up -d
docker-compose exec sortinghat sortinghat-admin --config sortinghat.config.settings setup --no-interactive
```

--------------------------------

### Run SortingHat Server and Worker Processes

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Commands to start the SortingHat server in development or production modes, and to run background worker processes for handling jobs. Includes options for multi-tenancy worker management.

```bash
# Run server in development mode
sortinghatd --config sortinghat.config.settings --dev

# Run server in production mode (WSGI)
sortinghatd --config sortinghat.config.settings

# Run background worker for jobs
sortinghatw --config sortinghat.config.settings

# Run worker for specific tenants (multi-tenancy)
sortinghatw --config sortinghat.config.settings tenant_A tenant_B
```

--------------------------------

### Run SortingHat Server Docker Container

Source: https://github.com/chaoss/grimoirelab-sortinghat/blob/main/docker/README.md

Starts a SortingHat server container in developer mode with MySQL and Redis dependencies. It configures the service to run on localhost:8000 with specified credentials and network settings. Environment variables can be modified for custom configurations.

```bash
docker network create sh

docker run --rm --net sh --name mysqldb -e 'MYSQL_ALLOW_EMPTY_PASSWORD=yes' mysql:8.0.22

docker run --rm --net sh --name redisdb redis:latest redis-server --appendonly yes

docker run --rm --net sh -p 8000:8000 --name sortinghat \
    -e 'SORTINGHAT_SECRET_KEY=secret' \
    -e 'SORTINGHAT_DB_HOST=mysqldb' \
    -e 'SORTINGHAT_REDIS_HOST=redisdb' \
    -e 'SORTINGHAT_SUPERUSER_USERNAME=admin' \
    -e 'SORTINGHAT_SUPERUSER_PASSWORD=admin' \
    -e 'SORTINGHAT_HTTP_DEV=0.0.0.0:8000' \
    -e 'SORTINGHAT_UWSGI_WORKERS=1' \
    -e 'SORTINGHAT_UWSGI_THREADS=4' \
    grimoirelab/sortinghat --dev
```

--------------------------------

### Run SortingHat Worker Docker Container

Source: https://github.com/chaoss/grimoirelab-sortinghat/blob/main/docker/README.md

Starts a SortingHat worker container to execute jobs. It connects to the same MySQL and Redis instances as the server, using environment variables for configuration. This command assumes the necessary network and database containers are already running.

```bash
docker run --rm --net sh --name sortinghat-worker-1 \
    -e 'SORTINGHAT_SECRET_KEY=secret' \
    -e 'SORTINGHAT_DB_HOST=mysqldb' \
    -e 'SORTINGHAT_REDIS_HOST=redisdb' \
    grimoirelab/sortinghat-worker
```

--------------------------------

### GraphQL API Individual Query - Search and Retrieve

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Provides examples for querying individuals from the Sorting Hat registry. Supports filtering by various attributes like name, email, source, organization, and bot status, along with pagination and sorting.

```graphql
query {
  individuals(
    page: 1
    pageSize: 50
    filters: {
      term: "john"
      isBot: false
      isEnrolled: true
      enrollment: "Example Corp"
      source: "git"
    }
    orderBy: "lastModified"
  ) {
    entities {
      mk
      isLocked
      profile {
        name
        email
        gender
        isBot
        country {
          code
          name
        }
      }
      identities {
        uuid
        source
        name
        email
        username
      }
      enrollments {
        group {
          name
        }
        start
        end
      }
    }
    pageInfo {
      page
      pageSize
      numPages
      hasNext
      hasPrev
      totalResults
    }
  }
}

query {
  individuals(filters: { uuid: "a9b403e150dd4af8953a52a4bb841051e4b705d9" }) {
    entities {
      mk
      profile {
        name
      }
      identities {
        uuid
        source
      }
    }
  }
}
```

--------------------------------

### Update Enrollment Dates

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Mutation to update the enrollment start and end dates for an individual.

```APIDOC
## Update Enrollment Dates

### Description
Updates the enrollment dates for a given individual.

### Method
MUTATION

### Endpoint
N/A (GraphQL)

### Parameters
#### Arguments
- **uuid** (String!) - The unique identifier of the individual.
- **group** (String) - The group the enrollment belongs to.
- **fromDate** (String!) - The original start date of the enrollment.
- **toDate** (String!) - The original end date of the enrollment.
- **newFromDate** (String!) - The new start date for the enrollment.
- **newToDate** (String!) - The new end date for the enrollment.

### Request Example
```graphql
mutation {
  updateEnrollment(
    uuid: "a9b403e150dd4af8953a52a4bb841051e4b705d9"
    group: "Example Corp"
    fromDate: "2020-01-01T00:00:00+00:00"
    toDate: "2023-12-31T23:59:59+00:00"
    newFromDate: "2019-06-01T00:00:00+00:00"
    newToDate: "2024-06-30T23:59:59+00:00"
  ) {
    uuid
    individual {
      enrollments {
        start
        end
      }
    }
  }
}
```

### Response
#### Success Response (200)
Returns the updated enrollment details.
- **uuid** (String) - The UUID of the individual.
- **individual** (Individual) - The individual object with updated enrollments.
  - **enrollments** (Enrollment) - List of enrollments.
    - **start** (String) - The start date of the enrollment.
    - **end** (String) - The end date of the enrollment.

#### Response Example
```json
{
  "data": {
    "updateEnrollment": {
      "uuid": "a9b403e150dd4af8953a52a4bb841051e4b705d9",
      "individual": {
        "enrollments": [
          {
            "start": "2019-06-01T00:00:00+00:00",
            "end": "2024-06-30T23:59:59+00:00"
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### Manage Users and Permissions via CLI

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

CLI commands for creating and managing user accounts, assigning administrative privileges, and setting user permissions or tenant assignments. Supports interactive and non-interactive user creation.

```bash
# Create regular user
sortinghat-admin --config sortinghat.config.settings create-user --username jsmith

# Create admin user
sortinghat-admin --config sortinghat.config.settings create-user --username admin --is-admin

# Non-interactive user creation
export SORTINGHAT_USER_USERNAME="newuser"
export SORTINGHAT_USER_PASSWORD="password123"
sortinghat-admin --config sortinghat.config.settings create-user --no-interactive

# Assign user to permission group
sortinghat-admin --config sortinghat.config.settings set-user-permissions jsmith admin

# Assign user to tenant (multi-tenancy mode)
sortinghat-admin --config sortinghat.config.settings set-user-tenant jsmith "X-SortingHat-Tenant" tenant_db
```

--------------------------------

### Configure SortingHat CLI

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Set up connection endpoints, authentication credentials, and manage configuration files for the CLI client.

```bash
sortinghat config set endpoint http://localhost:8000/api/
sortinghat config set user admin
sortinghat config set password secret
sortinghat config show
sortinghat -c /path/to/config.ini add --source git --email jsmith@example.com
```

--------------------------------

### Run SortingHat Frontend Tests

Source: https://github.com/chaoss/grimoirelab-sortinghat/blob/main/README.md

Initiates the frontend unit tests for SortingHat. This command is executed from the 'ui' directory and utilizes yarn for package management and test execution.

```bash
$ cd ui/
$ yarn test:unit
```

--------------------------------

### CLI - Configuration

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Configure the CLI client connection settings, including API endpoint and authentication credentials.

```APIDOC
## CLI - Configuration

### Description
Configure the CLI client connection settings, such as the API endpoint and authentication credentials. You can also specify a custom configuration file.

### Commands

- **sortinghat config set endpoint [URL]**
  Sets the API endpoint URL.
  Example: `sortinghat config set endpoint http://localhost:8000/api/`

- **sortinghat config set user [USERNAME]**
  Sets the authentication username.
  Example: `sortinghat config set user admin`

- **sortinghat config set password [PASSWORD]**
  Sets the authentication password.
  Example: `sortinghat config set password secret`

- **sortinghat config show**
  Displays the current configuration settings.

- **sortinghat -c [CONFIG_FILE] [COMMAND]**
  Uses a custom configuration file for the specified command.
  Example: `sortinghat -c /path/to/config.ini add --source git --email jsmith@example.com`
```

--------------------------------

### Manage Identities via CLI

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Add, remove, or display individual identity records within the registry.

```bash
sortinghat add --source git --email jsmith@example.com --name "John Smith" --username jsmith
sortinghat add --source github --email john@company.com --uuid a9b403e150dd4af8953a52a4bb841051e4b705d9
sortinghat rm a9b403e150dd4af8953a52a4bb841051e4b705d9
sortinghat show a9b403e150dd4af8953a52a4bb841051e4b705d9
```

--------------------------------

### Run SortingHat Backend Tests

Source: https://github.com/chaoss/grimoirelab-sortinghat/blob/main/README.md

Executes the backend unit tests for SortingHat. It shows two different settings configurations for testing, one for general testing and another specifically for tenant-related configurations.

```bash
(.venv)$ ./manage.py test --settings=config.settings.config_testing
(.venv)$ ./manage.py test --settings=config.settings.config_testing_tenant
```

--------------------------------

### Build SortingHat Docker Images

Source: https://github.com/chaoss/grimoirelab-sortinghat/blob/main/docker/README.md

Commands to build the SortingHat server and worker Docker images. This process first requires building the SortingHat Python package using 'poetry build' and potentially building the UI assets with 'yarn'. The Docker images are then built using specific Dockerfiles.

```bash
yarn --cwd ui build
poetry build

docker build -f docker/server.dockerfile -t grimoirelab/sortinghat .

docker build -f docker/worker.dockerfile -t grimoirelab/sortinghat-worker .
```

--------------------------------

### Manage Enrollments and Merges via CLI

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Perform complex registry operations such as enrolling individuals in organizations, merging multiple identities, or splitting individuals.

```bash
sortinghat enroll a9b403e150dd4af8953a52a4bb841051e4b705d9 "Example Corp"
sortinghat merge a9b403e150dd4af8953a52a4bb841051e4b705d9 b4c123f260ee5bg9064b63b5cc952162f5c816ea c5d234g371ff6ch0175c74c6dd063273g6d927fb
sortinghat split b4c123f260ee5bg9064b63b5cc952162f5c816ea
```

--------------------------------

### Manage Organizations and Domains via CLI

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Commands to add, remove, and manage organizations and their associated domains using the SortingHat CLI. This includes adding new organizations, associating domains, and removing both.

```bash
sortinghat orgs add "Example Corp"
sortinghat orgs add "Example Corp" example.com --top-domain
sortinghat orgs rm "Example Corp" example.com
sortinghat orgs rm "Example Corp"
```

--------------------------------

### Manage Organizations and Teams via Python API

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Demonstrates programmatic management of organizations, including adding domains, aliases, teams, and merging or deleting organizational records. It utilizes the SortingHatContext for tenant-aware operations.

```python
from sortinghat.core.api import (
    add_organization, add_domain, add_team, add_alias,
    delete_organization, merge_organizations
)
from sortinghat.core.context import SortingHatContext

ctx = SortingHatContext(user=request.user, tenant='default')

org = add_organization(ctx, name='Example Corp')
domain = add_domain(ctx, organization='Example Corp', domain_name='example.com', is_top_domain=True)
alias = add_alias(ctx, organization='Example Corp', name='Example Corporation')
team = add_team(ctx, team_name='Engineering', organization='Example Corp')
subteam = add_team(ctx, team_name='Backend', organization='Example Corp', parent_name='Engineering')
merged_org = merge_organizations(ctx, from_org='Old Company Name', to_org='Example Corp')
deleted_org = delete_organization(ctx, name='Obsolete Org')
```

--------------------------------

### Assign User to Tenant

Source: https://github.com/chaoss/grimoirelab-sortinghat/blob/main/README.md

Command-line interface command to assign a specific user to a tenant. This is a crucial step for managing user access and data segregation in a multi-tenant environment.

```bash
sortinghat-admin set-user-tenant username header tenant
```

--------------------------------

### Configure SortingHat Multi-tenancy

Source: https://github.com/chaoss/grimoirelab-sortinghat/blob/main/README.md

Enables multi-tenancy by setting the MULTI_TENANT flag to True and defining tenants in a JSON configuration file. This allows for isolated data instances within a single service. The tenant configuration specifies the tenant name and whether a dedicated queue should be used for its jobs.

```json
{
  "tenants": [
    {"name": "tenant A", "dedicated_queue": true},
    {"name": "tenant B", "dedicated_queue": false}
  ]
}
```

--------------------------------

### Clone Sorting Hat Repository

Source: https://github.com/chaoss/grimoirelab-sortinghat/blob/main/README.md

Commands to clone the Sorting Hat repository from GitHub and navigate into the project directory.

```bash
git clone https://github.com/chaoss/grimoirelab-sortinghat
cd grimoirelab-sortinghat
```

--------------------------------

### Add Identity using Python API

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Demonstrates how to use the SortingHat Python API to add new identities. This includes creating identities from scratch or associating them with existing individuals, and managing the context for API calls.

```python
from sortinghat.core.api import add_identity
from sortinghat.core.context import SortingHatContext

# Create context with authenticated user
ctx = SortingHatContext(user=request.user, tenant='default')

# Add new identity (creates individual automatically)
identity = add_identity(
    ctx,
    source='git',
    name='John Smith',
    email='jsmith@example.com',
    username='jsmith'
)
print(f"Created identity: {identity.uuid}")
print(f"Individual: {identity.individual.mk}")

# Add identity to existing individual
identity = add_identity(
    ctx,
    source='github',
    email='john@company.com',
    uuid='a9b403e150dd4af8953a52a4bb841051e4b705d9'
)
```

--------------------------------

### CLI - Enrollments

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Manage organization enrollments for individuals, including enrolling, updating dates, and withdrawing.

```APIDOC
## CLI - Enrollments

### Description
Manage organization enrollments for individuals. This includes enrolling an individual into an organization, specifying date ranges for enrollment, forcing updates, and withdrawing an individual from an organization.

### Commands

- **sortinghat enroll [INDIVIDUAL_UUID] [ORGANIZATION_NAME]**
  Enrolls an individual into an organization.
  Example: `sortinghat enroll a9b403e150dd4af8953a52a4bb841051e4b705d9 "Example Corp"`

- **sortinghat enroll [INDIVIDUAL_UUID] [ORGANIZATION_NAME] --from-date [DATE] --to-date [DATE]**
  Enrolls an individual with a specified start and end date.
  Example: `sortinghat enroll a9b403e150dd4af8953a52a4bb841051e4b705d9 "Example Corp" --from-date "2020-01-01" --to-date "2023-12-31"`

- **sortinghat enroll [INDIVIDUAL_UUID] [ORGANIZATION_NAME] --from-date [DATE] --force**
  Enrolls an individual, forcing an overwrite of default dates if they exist.
  Example: `sortinghat enroll a9b403e150dd4af8953a52a4bb841051e4b705d9 "Example Corp" --from-date "2020-01-01" --force`

- **sortinghat withdraw [INDIVIDUAL_UUID] [ORGANIZATION_NAME] --from-date [DATE] --to-date [DATE]**
  Withdraws an individual from an organization within a specified date range.
  Example: `sortinghat withdraw a9b403e150dd4af8953a52a4bb841051e4b705d9 "Example Corp" --from-date "2022-01-01" --to-date "2022-12-31"`
```

--------------------------------

### Python API - Merge and Enroll

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Manage individual merging and organization enrollment programmatically.

```APIDOC
## Python API - Merge and Enroll

### Description
Merge multiple individual records into a single identity and manage enrollment periods for organizations.

### Methods
- `merge(ctx, from_uuids, to_uuid)`: Merges individuals.
- `enroll(ctx, uuid, group, from_date, to_date)`: Enrolls an individual in a group.
- `withdraw(ctx, uuid, group, from_date, to_date)`: Withdraws an individual from a group.
```

--------------------------------

### Manage Identities via GraphQL

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Import identities from external backends and list available importers using GraphQL mutations and queries.

```graphql
mutation { importIdentities(backend: "gitdm" url: "https://example.com/mailmap" params: "{}") { jobId } }

query { identitiesImportersTypes { name args } }
```

--------------------------------

### CLI - Organization Management

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Manage organizations and their associated domains using the sortinghat CLI tool.

```APIDOC
## CLI Organization Management

### Description
Commands to add or remove organizations and their associated domains.

### Usage
- `sortinghat orgs add "Org Name"` - Add a new organization.
- `sortinghat orgs add "Org Name" domain.com --top-domain` - Add a domain to an organization.
- `sortinghat orgs rm "Org Name" domain.com` - Remove a domain from an organization.
- `sortinghat orgs rm "Org Name"` - Remove an organization and all its domains.
```

--------------------------------

### List and Search Countries via CLI

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

CLI commands to list all available country codes and search for specific countries using a term. This functionality is useful for data validation or filtering.

```bash
# List all countries
sortinghat countries

# Search for country
sortinghat countries --term "united"
```

--------------------------------

### Manage Recommendations

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Generates and manages recommendations for identity matching, organization affiliations, and gender detection. Includes queries for pending items and mutations to apply or dismiss them.

```graphql
mutation {
  recommendMatches(criteria: ["email", "name"], sourceUuids: ["a9b403e150dd4af8953a52a4bb841051e4b705d9"], exclude: true, strict: true) { jobId }
}

mutation {
  recommendAffiliations(uuids: ["a9b403e150dd4af8953a52a4bb841051e4b705d9"]) { jobId }
}

mutation {
  recommendGender(uuids: ["a9b403e150dd4af8953a52a4bb841051e4b705d9"], exclude: true) { jobId }
}

query {
  recommendedMerge(page: 1, pageSize: 20) { entities { id individual1 { mk profile { name } } individual2 { mk profile { name } } applied } }
}

mutation {
  manageMergeRecommendation(recommendationId: 42, apply: true) { applied }
}
```

--------------------------------

### Manage Teams via GraphQL

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Handles the creation of hierarchical team structures within organizations. Supports adding subteams and querying team data.

```graphql
mutation { addTeam(teamName: "Engineering", organization: "Example Corp") { team { name parentOrg { name } } } }
mutation { addTeam(teamName: "Backend", organization: "Example Corp", parentName: "Engineering") { team { name parentOrg { name } } } }
query { teams(filters: { organization: "Example Corp", term: "engineering" }) { entities { name subteams { name } parentOrg { name } } } }
mutation { deleteTeam(teamName: "Engineering", organization: "Example Corp") { team { name } } }
```

--------------------------------

### Manage Enrollments via GraphQL

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Enrolls individuals into organizations or teams for specific timeframes. Overlapping enrollments are automatically merged by the system.

```graphql
mutation { enroll(uuid: "a9b403e150dd4af8953a52a4bb841051e4b705d9", group: "Example Corp", fromDate: "2020-01-01T00:00:00+00:00", toDate: "2023-12-31T23:59:59+00:00") { uuid individual { enrollments { group { name } start end } } } }
mutation { enroll(uuid: "a9b403e150dd4af8953a52a4bb841051e4b705d9", group: "Engineering", parentOrg: "Example Corp", fromDate: "2021-06-01T00:00:00+00:00") { uuid individual { enrollments { group { name } start end } } } }
mutation { withdraw(uuid: "a9b403e150dd4af8953a52a4bb841051e4b705d9", group: "Example Corp", fromDate: "2022-01-01T00:00:00+00:00", toDate: "2022-12-31T23:59:59+00:00") { uuid individual { enrollments { group { name } start end } } } }
```

--------------------------------

### CLI - Organizations

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Manage organizations and their associated domains from the command line.

```APIDOC
## CLI - Organizations

### Description
Manage organizations and their associated domains within the registry. This command allows you to list all registered organizations.

### Command

- **sortinghat orgs show**
  Lists all organizations currently registered in the system.
  Example: `sortinghat orgs show`
```

--------------------------------

### Migrate SortingHat Database Schema

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

CLI commands for migrating the database schema from older SortingHat versions (e.g., 0.7.x) to newer versions. Supports both interactive and non-interactive migration processes.

```bash
# Migrate old database schema
sortinghat-admin --config sortinghat.config.settings migrate-old-database

# Non-interactive migration
export SORTINGHAT_SUPERUSER_USERNAME="admin"
export SORTINGHAT_SUPERUSER_PASSWORD="admin123"
sortinghat-admin --config sortinghat.config.settings migrate-old-database --no-interactive
```

--------------------------------

### CLI - Show Individuals

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Display information about individuals in the registry, with options to search and filter.

```APIDOC
## CLI - Show Individuals

### Description
Display information about individuals stored in the registry. You can view details for a specific individual, search for individuals by a term, or filter them by their data source.

### Commands

- **sortinghat show [INDIVIDUAL_UUID]**
  Displays detailed information for a specific individual identified by their UUID.
  Example: `sortinghat show a9b403e150dd4af8953a52a4bb841051e4b705d9`

- **sortinghat show --term [SEARCH_TERM]**
  Searches for individuals containing the specified term in their information.
  Example: `sortinghat show --term "john"`

- **sortinghat show --source [SOURCE_NAME]**
  Filters and displays individuals based on their data source.
  Example: `sortinghat show --source git`
```

--------------------------------

### Manage Organizations via GraphQL

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Provides operations for creating, querying, merging, and deleting organizations. Includes support for managing associated domains and aliases.

```graphql
mutation { addOrganization(name: "Example Corp") { organization { name } } }
mutation { addDomain(organization: "Example Corp", domain: "example.com", isTopDomain: true) { domain { domain isTopDomain } } }
mutation { addAlias(organization: "Example Corp", alias: "Example Corporation") { alias { alias } } }
query { organizations(page: 1, pageSize: 20, filters: { term: "example" }, orderBy: "name") { entities { name domains { domain isTopDomain } aliases { alias } totalEnrollments } pageInfo { totalResults } } }
mutation { mergeOrganizations(fromOrg: "Old Company Name", toOrg: "Example Corp") { organization { name domains { domain } } } }
mutation { deleteOrganization(name: "Old Company Name") { organization { name } } }
```

--------------------------------

### GraphQL API - Identity Import

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Import identities into the system from a specified backend and URL. This mutation initiates an import job.

```APIDOC
## GraphQL API - Identity Import

### Description
Import identities into the system from a specified backend and URL. This mutation initiates an import job.

### Method
POST

### Endpoint
/graphql

### Parameters
#### Request Body
- **query** (string) - Required - The GraphQL mutation query.

### Request Example
```json
{
  "query": "mutation { importIdentities(backend: \"gitdm\", url: \"https://example.com/mailmap\", params: \"{\\"}\") { jobId } }"
}
```

### Response
#### Success Response (200)
- **data** (object) - The result of the mutation.
  - **importIdentities** (object)
    - **jobId** (string) - The ID of the initiated import job.

#### Response Example
```json
{
  "data": {
    "importIdentities": {
      "jobId": "12345abcde"
    }
  }
}
```
```

--------------------------------

### CLI - Add Identity

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Add identities to the registry from the command line. This can create a new individual or add an identity to an existing one.

```APIDOC
## CLI - Add Identity

### Description
Add identities to the registry from the command line. This command can be used to create a new individual with associated identities or to add an identity to an existing individual identified by their UUID.

### Commands

- **sortinghat add --source [SOURCE] --email [EMAIL] --name [NAME] --username [USERNAME]**
  Adds a new identity and creates a new individual.
  Example: `sortinghat add --source git --email jsmith@example.com --name "John Smith" --username jsmith`

- **sortinghat add --source [SOURCE] --email [EMAIL] --uuid [UUID]**
  Adds an identity to an existing individual identified by their UUID.
  Example: `sortinghat add --source github --email john@company.com --uuid a9b403e150dd4af8953a52a4bb841051e4b705d9`
```

--------------------------------

### POST /graphql (Query Individuals)

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Search and retrieve individuals using filters, pagination, and sorting.

```APIDOC
## POST /graphql (Query Individuals)

### Description
Retrieves a list of individuals based on search criteria such as name, email, or organization enrollment.

### Method
POST

### Endpoint
/graphql

### Request Body
- **page** (int) - Optional - Page number
- **pageSize** (int) - Optional - Results per page
- **filters** (object) - Optional - Filtering criteria

### Request Example
query { individuals(page: 1, pageSize: 10) { entities { mk } } }

### Response
#### Success Response (200)
- **entities** (array) - List of individual objects
- **pageInfo** (object) - Pagination details

#### Response Example
{ "data": { "individuals": { "entities": [...] } } }
```

--------------------------------

### CLI - Split Individual

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Separate an identity from its individual, creating a new individual for that identity.

```APIDOC
## CLI - Split Individual

### Description
Split an identity from its current individual. This action creates a new individual for the specified identity, effectively separating it from its original owner.

### Command

- **sortinghat split [IDENTITY_UUID]**
  Splits the specified identity into a new individual.
  Example: `sortinghat split b4c123f260ee5bg9064b63b5cc952162f5c816ea`
```

--------------------------------

### Python API - Identity Management

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Programmatically add identities and link them to individuals using the SortingHat Python API.

```APIDOC
## Python API - Add Identity

### Description
Use the `add_identity` function to create or link identities within a specific context.

### Parameters
- **ctx** (SortingHatContext) - Required - The authenticated user context.
- **source** (string) - Required - The identity source (e.g., 'git', 'github').
- **name** (string) - Optional - Name of the individual.
- **email** (string) - Required - Email address.
- **username** (string) - Optional - Username.

### Example
```python
from sortinghat.core.api import add_identity
identity = add_identity(ctx, source='git', name='John Smith', email='jsmith@example.com', username='jsmith')
```
```

--------------------------------

### Manage Background Jobs

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Executes automated background jobs for affiliation, unification, and genderization. Provides queries to check job status and list all active or completed jobs.

```graphql
mutation {
  affiliate(uuids: ["a9b403e150dd4af8953a52a4bb841051e4b705d9"]) { jobId }
}

mutation {
  unify(criteria: ["email", "name", "username"], sourceUuids: ["a9b403e150dd4af8953a52a4bb841051e4b705d9"], exclude: true, strict: true, matchSource: false) { jobId }
}

query {
  job(jobId: "abc123-def456-ghi789") {
    jobId
    status
    result { ... on UnifyResultType { merged } }
  }
}
```

--------------------------------

### Define Changelog Entry in YAML

Source: https://github.com/chaoss/grimoirelab-sortinghat/blob/main/CONTRIBUTING.md

This snippet demonstrates the required YAML structure for a changelog entry. It includes mandatory fields like title and category, and optional fields for attribution and issue tracking.

```yaml
title: 'Fix bug casting spells on magicians'
category: fixed
author: John Smith <jsmith@example.com>
issue: 666
notes: >
    The bug was making impossible to cast a spell on
    a magician.
```

--------------------------------

### POST /graphql (Add Identity)

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Allows adding new identities to the registry, either creating a new individual or linking to an existing one via UUID.

```APIDOC
## POST /graphql (Add Identity)

### Description
Adds a new identity to the system. If a UUID is provided, it links the identity to an existing individual; otherwise, it creates a new one.

### Method
POST

### Endpoint
/graphql

### Request Body
- **source** (string) - Required - Data source origin
- **name** (string) - Optional - Identity name
- **email** (string) - Required - Identity email
- **username** (string) - Required - Identity username
- **uuid** (string) - Optional - Existing individual UUID

### Request Example
mutation { addIdentity(source: "git", name: "John", email: "j@ex.com", username: "j") { uuid } }

### Response
#### Success Response (200)
- **uuid** (string) - The individual's unique identifier

#### Response Example
{ "data": { "addIdentity": { "uuid": "a9b4..." } } }
```

--------------------------------

### GraphQL API Authentication - JWT Token Management

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Demonstrates how to obtain, verify, and refresh JSON Web Tokens (JWT) for authenticating with the Sorting Hat GraphQL API. Requires username and password for initial token acquisition.

```graphql
mutation {
  tokenAuth(username: "admin", password: "secret") {
    token
    payload
    refreshExpiresIn
  }
}

mutation {
  verifyToken(token: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...") {
    payload
  }
}

mutation {
  refreshToken(token: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...") {
    token
    payload
    refreshExpiresIn
  }
}
```

--------------------------------

### CLI - Update Profile

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Update an individual's profile information, such as name, email, country, or bot status.

```APIDOC
## CLI - Update Profile

### Description
Update an individual's profile information. You can modify various fields including name, email, country, and mark an individual as a bot.

### Command

- **sortinghat profile [INDIVIDUAL_UUID] [OPTIONS]**
  Updates the profile of the specified individual.
  Options:
  - `--name [NAME]`
  - `--email [EMAIL]`
  - `--country [COUNTRY_CODE]`
  - `--bot` (flag to mark as bot)

  Example: `sortinghat profile a9b403e150dd4af8953a52a4bb841051e4b705d9 --name "John Smith" --email jsmith@example.com --country US --bot`
```

--------------------------------

### Enrollments

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Manage individual enrollments in organizations or teams over specific time periods.

```APIDOC
## MUTATION enroll

### Description
Enroll an individual into an organization or team. Overlapping enrollments are automatically merged.

### Method
POST (GraphQL Mutation)

### Parameters
#### Request Body
- **uuid** (String) - Required - Individual UUID.
- **group** (String) - Required - Organization or Team name.
- **fromDate** (String) - Required - Start date (ISO format).
- **toDate** (String) - Optional - End date (ISO format).

### Request Example
mutation { enroll(uuid: "uuid", group: "Org", fromDate: "2020-01-01T00:00:00+00:00") { uuid } }
```

--------------------------------

### POST /graphql (Authentication)

Source: https://context7.com/chaoss/grimoirelab-sortinghat/llms.txt

Endpoints for managing JWT authentication tokens to access the Sorting Hat API.

```APIDOC
## POST /graphql (Authentication)

### Description
Provides mutations to obtain, verify, and refresh JWT tokens for API access.

### Method
POST

### Endpoint
/graphql

### Request Body
- **mutation** (string) - Required - GraphQL mutation (tokenAuth, verifyToken, or refreshToken)

### Request Example
mutation { tokenAuth(username: "admin", password: "secret") { token } }

### Response
#### Success Response (200)
- **token** (string) - The JWT access token
- **payload** (object) - Token metadata

#### Response Example
{ "data": { "tokenAuth": { "token": "eyJ..." } } }
```