Configuration

Configuration is stored in smm_config.json inside the folder referenced by SMM_STORE_DATA_AT.

Required environment variable

export SMM_STORE_DATA_AT=/absolute/path/to/data-folder

Configuration format

SMM uses a multi-project configuration format. Wrap your project configurations in a projects array:

{
  "projects": [
    {
      "git_provider": "github",
      "github_token": "your_github_token",
      "github_repository": "your-org/frontend-app",
      "git_repository_location": "/absolute/path/to/frontend-app",
      "deployment_frequency_targets": [
        { "pipeline": ".github/workflows/ci.yml", "job": "deploy" }
      ],
      "main_branch": "main",
      "timezone": "Europe/Madrid",
      "dashboard_start_date": "2025-01-01",
      "dashboard_end_date": "2025-12-31",
      "dashboard_color": "#1976d2",
      "log_level": "INFO"
    },
    {
      "git_provider": "github",
      "github_token": "your_github_token",
      "github_repository": "your-org/backend-api",
      "git_repository_location": "/absolute/path/to/backend-api",
      "main_branch": "main",
      "jira_url": "https://your-domain.atlassian.net",
      "jira_email": "your-email@example.com",
      "jira_token": "your_jira_token",
      "jira_project": "API"
    }
  ]
}

Selecting a project

When you have multiple projects, select which one to use with the CLI global option:

smm --project your-org/frontend-app prs fetch

If smm_config.json has more than one project and --project is not provided, SMM uses the first project in the projects array. Project-specific environment variables are then resolved with that first project's github_repository prefix.

In the dashboard, configured projects appear in the project drawer. Selecting a project stores the repository name in the smm_active_project browser cookie and reloads the current page without stale filter query parameters.

Project-specific environment variables

Project configuration can be provided through project-specific environment variables instead of smm_config.json. Uppercase the github_repository value, replace non-alphanumeric characters with underscores, and append the setting environment variable name:

export YOUR_ORG_FRONTEND_APP_GITHUB_TOKEN=ghp_frontend
export YOUR_ORG_FRONTEND_APP_JIRA_TOKEN=jira_token
export YOUR_ORG_FRONTEND_APP_SMM_TIMEZONE=Europe/Madrid

For example, github_repository value your-org/frontend-app maps GITHUB_TOKEN to YOUR_ORG_FRONTEND_APP_GITHUB_TOKEN, JIRA_TOKEN to YOUR_ORG_FRONTEND_APP_JIRA_TOKEN, and so on.

Supported project-specific environment variable suffixes are:

• GIT_PROVIDER
• GITHUB_TOKEN
• GITLAB_TOKEN
• GIT_REPOSITORY_PATH
• LOGGING_LEVEL
• JIRA_URL
• JIRA_EMAIL
• JIRA_TOKEN
• JIRA_PROJECT
• SONAR_URL
• SONAR_TOKEN
• SONAR_PROJECT
• STORE_LOGS
• SMM_TIMEZONE
• SMM_STORAGE_TYPE

The only global environment variable used by configuration loading is SMM_STORE_DATA_AT. Generic variables such as GITHUB_TOKEN, JIRA_TOKEN, SONAR_TOKEN, SMM_TIMEZONE, or GIT_REPOSITORY_PATH are not used.

Project-specific GITHUB_TOKEN takes precedence over project github_token and root github_token. Other project-specific environment variables are used only when the selected project does not set the corresponding smm_config.json key, except LOGGING_LEVEL, which overrides log_level.

Dashboard configuration

These keys affect dashboard behavior:

• dashboard_start_date and dashboard_end_date: default dashboard date range when no URL filters are provided.
• dashboard_color: theme color value exposed by the configuration API.
• deployment_frequency_targets: pipeline/job pairs used by the Insights deployment frequency chart.
• timezone: configured project timezone for CLI and provider fetch behavior.

Dashboard filtering uses the browser timezone and sends it as the timezone query parameter. This keeps dashboard date-time filtering aligned with the user viewing the dashboard. See Dashboard for shared dashboard behavior.

Timezone configuration

Set timezone in each project to an IANA timezone identifier such as Europe/Madrid, America/New_York, or UTC. This value is used by CLI commands when they interpret date-only filters and group time-based metrics.

{
  "projects": [
    {
      "github_repository": "your-org/frontend-app",
      "timezone": "Europe/Madrid"
    }
  ]
}

If timezone is omitted from the selected project, CLI commands use the project-specific SMM_TIMEZONE environment variable. If neither is set, SMM uses UTC.

export YOUR_ORG_FRONTEND_APP_SMM_TIMEZONE=Europe/Madrid
smm --project your-org/frontend-app prs summary --start-date 2026-01-01 --end-date 2026-01-31

For client dashboards and REST API calls, send the browser or viewer timezone as the timezone query parameter. The dashboard does this automatically from the browser's Intl.DateTimeFormat().resolvedOptions().timeZone value. REST API clients should pass the same kind of IANA identifier:

/pull-requests/summary?start_date=2026-01-01&end_date=2026-01-31&timezone=Europe%2FMadrid

Date-only filters such as 2026-01-01 are expanded to the beginning or end of that day in the selected timezone. Offset-aware date-time values such as 2026-01-01T09:00:00+01:00 are treated as exact instants.

Key reference

Key	Description	Required
git_provider	Git provider (for example github)	Yes
github_token	GitHub personal access token	Yes for GitHub PR/pipeline
gitlab_token	GitLab personal access token	Yes for GitLab MR/pipeline
github_repository	Repository in owner/repo format (also used as project identifier)	Yes
git_repository_location	Local clone path for git/code metrics	Yes for source-code metrics
deployment_frequency_targets	Deployment frequency workflow/job targets as { "pipeline": "...", "job": "..." } objects	No
main_branch	Main branch name	No
dashboard_start_date	Default start date in dashboard	No
dashboard_end_date	Default end date in dashboard	No
dashboard_color	Dashboard color theme value	No
log_level	Logging level (DEBUG, INFO, WARN, ERROR, CRITICAL)	No
jira_url	Jira base URL	No
jira_email	Jira account email	No
jira_token	Jira API token	No
jira_project	Jira project key	No
sonar_url	SonarQube server URL	No
sonar_token	SonarQube token	No
sonar_project	SonarQube project key	No
sonar_local_runner_token	SonarQube local analysis runner token (generated by local analysis)	No
store_logs	Store log files to disk (true/false)	No
timezone	IANA timezone identifier (for example Europe/Madrid, UTC)	No