Quick Start Guide

Installation

NPM

npm install @trippl/triview -g

Local Installation

git clone https://github.com/trippl-hq/triview.git
npm install
npm install ./ -g

Guide: Reviewing a Merge Request

1. Initialize triview in your project: You can start a fresh setup or reuse existing configuration, guideline, or review prompt files. All flags are optional:

triview init azure-openai 

or

triview init azure-openai \
  --guideline-prompt ./oldtriview/guidelines.md \
  --review-prompt ./oldtriview/review.md \
  --source-config ./oldtriview/.triview-settings/.config.json

• Use --guideline-prompt, --review-prompt, or --source-config to point to your existing files if you want to migrate settings or prompts from a previous setup.
• If you don't specify these options, triview will generate new default files.

2. Configure triview:

• Edit the generated .triview/.triview-settings/.config.json file to add your AI provider config.
• Optionally, update .triview/guidelines.md to customize review instructions.
• Set required environment variables (e.g., AZURE_OPENAI_API_KEY, OPENAI_API_KEY, etc.). Example .config.json for Azure OpenAI:

{
    "llm": {
        "type": "azure-openai",
        "azureOpenAIApiInstanceName": "YOUR_AZURE_OPENAI_INSTANCE_NAME",
        "azureOpenAIApiDeploymentName": "YOUR_AZURE_OPENAI_DEPLOYMENT_NAME",
        "azureOpenAIApiVersion": "YOUR_AZURE_OPENAI_API_VERSION"
        // "azureOpenAIApiKey": "YOUR_AZURE_OPENAI_API_KEY" // (optional, see below)
    }
}

API Key Setup:

• You can provide your Azure OpenAI API key in two ways:
  1. Environment Variable: Set AZURE_OPENAI_API_KEY in your environment. This is the recommended and more secure approach.
  2. Config File: Add "azureOpenAIApiKey": "YOUR_AZURE_OPENAI_API_KEY" directly to your .config.json file under the llm section.

Note: If both are set, the value in .config.json will take precedence. Storing secrets in environment variables is generally safer than committing them to files.

3. Install GitLab CLI and authenticate:

• Windows: For Microsoft Windows GitLab CLI for Windows.
• Linux: Follow instructions at GitLab CLI Linux Install.
• macOS: Use Homebrew or download from GitLab CLI macOS Install.
• See the official GitLab CLI installation guide for details.
• Authenticate with your GitLab account:

  glab auth login

4. Review a Merge Request:

triview mr <MR_NUMBER> --comment --desc

Replace <MR_NUMBER> with your actual merge request number.

• Allows the user to provide a comment and a description for the merge request.
• --comment (optional) AI agent adds a comment to the merge request.
• --desc (optional) AI agent sets the description for the merge request.
• --preview (optional) Preview comments or description without posting/updating when used with --comment or --desc.
• Both flags are optional and can be used independently or together to enhance the merge request with additional information.

Preview Mode: Use the --preview flag to see what would be posted without actually updating the MR:

# Preview comments before posting
triview mr 123 --comment --preview

# Preview description before updating
triview mr 123 --desc --preview

# Preview both comments and description
triview mr 123 --comment --desc --preview

This is useful for reviewing AI-generated content before making it public.

5. For GitHub Pull Requests: You can also use triview with GitHub Pull Requests using the pr command:

# Basic PR review
triview pr 123 --comment --desc

# Preview PR comments and description
triview pr 123 --comment --desc --preview

6. Check logs:

• After running the review, triview creates a log file in .triview/logs/ for reference and debugging.

Guide: Using Jira Integration with MR Command

Triview supports fetching requirements from Jira tickets when reviewing merge requests. This allows you to automatically include ticket details in your code reviews.

Setup Options

Option 1: Modern Jira REST API (Recommended)

Prerequisites:

1. Find your Atlassian Cloud ID:

   • Visit https://yourcompany.atlassian.net/_edge/tenant_info while logged in
   • Copy the cloudId value

2. Create a Personal Access Token (PAT):

   • Go to Atlassian Account Settings → Security → Create and manage API tokens
   • Create a new token with read:jira-work permission
   • Save the token securely

Setup via Environment Variables (Recommended):

export JIRA_USERNAME="[email protected]"
export JIRA_API_PAT_TOKEN="your-pat-token"
export JIRA_CLOUD_ID="your-cloud-id"

Setup via Configuration File: Edit your .triview/.triview-settings/.config.json:

{
  "llm": {
    "type": "azure-openai",
    "azureOpenAIApiInstanceName": "your-instance",
    "azureOpenAIApiDeploymentName": "your-deployment",
    "azureOpenAIApiVersion": "2024-12-01-preview"
  },
  "commands": {
    "mr": {
      "requirementsProvider": "jira",
      "contentProvider": "gitlab"
    }
  },
  "requirementsProviderConfig": {
    "jira": {
      "username": "[email protected]",
      "token": "YOUR_JIRA_PAT_TOKEN",
      "cloudId": "YOUR_ATLASSIAN_CLOUD_ID",
      "displayUrl": "https://yourcompany.atlassian.net/browse/"
    }
  }
}

Option 2: Legacy Jira API (Alternative)

Prerequisites:

1. Create a Legacy API Token:
   • Go to Atlassian Account Settings → Security → Create and manage API tokens
   • Create an API token without scopes (legacy token)

Setup via Environment Variables:

export JIRA_USERNAME="[email protected]"
export JIRA_LEGACY_API_TOKEN="your-legacy-token"

Setup via Configuration File:

{
  "llm": {
    "type": "azure-openai",
    "azureOpenAIApiInstanceName": "your-instance",
    "azureOpenAIApiDeploymentName": "your-deployment",
    "azureOpenAIApiVersion": "2024-12-01-preview"
  },
  "commands": {
    "mr": {
      "requirementsProvider": "jira-legacy",
      "contentProvider": "gitlab"
    }
  },
  "requirementsProviderConfig": {
    "jira-legacy": {
      "username": "[email protected]",
      "token": "YOUR_JIRA_LEGACY_TOKEN",
      "baseUrl": "https://yourcompany.atlassian.net/rest/api/2/issue/",
      "displayUrl": "https://yourcompany.atlassian.net/browse/"
    }
  }
}

Usage Examples

Basic review with Jira requirements:

triview mr 123 ABC-456

• 123 = GitLab MR number
• ABC-456 = Jira ticket ID

Review with explicit provider:

triview mr 123 ABC-456 --requirements-provider jira

Review with additional files and actions:

triview mr 123 ABC-456 -f src/component.js tests/component.test.js --comment --desc

Preview before posting:

triview mr 123 ABC-456 --comment --desc --preview

Review with custom message:

triview mr 123 ABC-456 --message "Please focus on security aspects" --comment

Optional Features

Automatic Time Logging

Add automatic time logging to Jira after reviews:

{
  "commands": {
    "mr": {
      "requirementsProvider": "jira",
      "logWorkForReviewInSeconds": 1800
    }
  }
}

This logs 30 minutes (1800 seconds) to the Jira ticket after each review.

Command Options

• --requirements-provider jira: Override the requirements provider
• -f, --file [files...]: Include additional files in the review
• -m, --message <message>: Add extra context to the review
• --comment: Post the review as a comment to the MR
• -d, --desc: Update the MR description with the review results
• --preview: Preview comments or description without posting/updating (use with --comment or --desc)

Troubleshooting

Common Issues:

1. "Missing JIRA Cloud ID": Ensure you've set JIRA_CLOUD_ID or added cloudId to your config
2. "Failed to fetch Jira issue": Check your token permissions and network connectivity
3. "No Jira config provided": Verify your requirementsProviderConfig section is properly configured

Testing Your Setup:

triview mr <MR_NUMBER> <JIRA_TICKET> --requirements-provider jira

Replace <MR_NUMBER> and <JIRA_TICKET> with actual values to test the integration.