Quickstart

This section provides a step-by-step guide to help you get started with Pulzen. Here, you'll find everything you need to enable Pulzen for your organization and configure extractors according to your preferred data sources. Whether you are connecting to GitHub, GitLab, Bitbucket, Azure DevOps, Microsoft Teams, or Jira, this guide will walk you through the essential setup and configuration required to begin extracting and analyzing your development data with Pulzen.

Step-by-Step Setup

Below you will find a detailed step-by-step guide to help you start using Pulzen—from creating your company’s Pulzen instance to having everything configured and ready to go. If you need more details, Pulzen also provides explanatory videos covering installation, setup, and usage, all available at:

https://<your-company>.pulzen.ai/private/home

Step 1: Register your organization in Pulzen

Go to https://app.pulzen.ai/new-organization?step=1 and follow the guided process to create your organization. Complete each step until your tenant is created at a unique URL like:

https://<your-company>.pulzen.ai

Step 2: Create an admin user for your client

Access your tenant at:

https://<your-company>.pulzen.ai/private/config/users

Create a user with the ADMIN profile for your client. This will allow them to manage and create additional users directly from their own Pulzen web portal.

Step 3: Create an extractor for your data source

  • Choose an extractor name: Start by giving your extractor a unique and descriptive name.
  • Select the hosting type: Choose between Pulzen Hosted (recommended) or Self Hosted depending on your infrastructure and preferences.

Pulzen Hosted: The extractor is installed in Cleverit's environment. This option makes installation, maintenance, and support much easier for the Cleverit team. All infrastructure costs are covered by Cleverit and are not charged to the client.

Self Hosted: The extractor and database are installed in the client's environment. This provides the client with full control over their data, but makes platform support and maintenance more challenging for the Cleverit team. All infrastructure costs are the responsibility of the client.

  • Select your Version Control System (VCS): Pick the main data source you want to connect (e.g., GitHub, GitLab, Bitbucket, Azure DevOps). You will need to provide the required SECRETS for your VCS. Refer to the appropriate settings section for details:
  • Optional integrations: You can also choose to activate additional integrations:
  • Test & Start Pulzen Gateway:
    • Set the start date from which you want to collect data in your extractor. This allows you to define how much historical data will be loaded and processed.
  • Test your extractor:
    • Once everything is configured, run a test to ensure your extractor is working correctly and data is being ingested as expected.

Step 4: Extract initial data from schemas

  • Go to https://<your-company>.pulzen.ai/private/schemas in your tenant.
  • Select Contributor schema and click Extract contributors.
  • Select Team schema and click Extract teams.
  • Select Repository schema and click Extract repositories.
  • This will ensure that your contributors, teams, and repositories are loaded and available for further configuration and analysis in Pulzen.
  • In the schemas menu, you can exclude contributors, teams, or repositories that you do not want to include in your analysis.
  • You can also merge contributors from different data sources (for example, a GitHub user with a Jira or Teams user). This allows you to perform cross-source queries and ensures Pulzen recognizes them as the same user for unified analytics.

That's it! Everything is now configured and you're ready to start using Pulzen.

General Settings

Environment variables that must be configured in the project.

  • MONGODB Environment variable that stores the value of the connection url to the Database example: mongodb+srv://username:[email protected]/performance-persistence
  • AUTH_BASIC_USERNAME Username for connection to the API
  • AUTH_BASIC_PASSWORD Password for connection to the API
  • PROFILES_DEFAULT Environment variable that stores the value of the profiles or platforms to process

    Possible profile values ​​are: github, gitlab, bitbucket, ado and jira. For local tests, the local profile is also used. Examples:

    • PROFILES_DEFAULT = local
    • PROFILES_DEFAULT = gitlab
    • PROFILES_DEFAULT = bitbucket
    • PROFILES_DEFAULT = github
    • PROFILES_DEFAULT = ado
    • PROFILES_DEFAULT = jira
    • PROFILES_DEFAULT = copilot
  • LICENSE_API_APP_KEY Connection key with the license API

GitHub Settings

Environment variables that must be configured in the project for GitHub

  • GITHUB_ORGANIZATION Environment variable that stores the value of the workspace to process

    The account owner of the repository. (Organization)

  • GITHUB_ENTERPRISE Environment variable that stores the value of the GitHub enterprise to process

    If the enterprise and the organization have the same value, it is not necessary to define the environment variable GITHUB_ENTERPRISE, only the environment variable GITHUB_ORGANIZATION must be defined.

  • GITHUB_WEBHOOK_SECRET Environment variable that stores the secret key value to process webhooks

    If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.

  • GITHUB_TOKEN Environment variable that stores the value of the token for the connection to GRAPHQL and API

    How to obtain the GITHUB_TOKEN:

    1. Go to this direct link to create a new GitHub token with pre-selected scopes.
    2. Review the pre-selected scopes and modify if needed. If you do not want to use Copilot features, you can remove the manage_billing:copilot scope.
    3. Set an appropriate expiration date for the token.
    4. Click on Generate token and copy the generated token value.

    This token already includes Copilot permissions (manage_billing:copilot) and can be used for both the GITHUB_TOKEN and COPILOT_TOKEN environment variables. If you removed the Copilot scope when creating the token, you'll need to create a separate token for Copilot with manage_billing:copilot or read:enterprise scope.

GitLab Settings

Only the Cloud version is supported

Environment variables that must be configured in the project for GitLab

  • GITLAB_CLIENT_AUTHORIZATION Environment variable that stores the value of the token to connect to the API

How to obtain the GITLAB_CLIENT_AUTHORIZATION:

  1. Navigate to Gitlab and click on your Preferences.
  2. Click on Access tokens and the page is loading.
  3. Click Add new token button.
  4. Ensure you create a token with
  • read_api
  • read_user
  • manage_runner
  • self_rotate
  • read_repository
  • read_registry
  1. Click on Create personal access token button.
  2. Copy the token value and set it as the GITLAB_CLIENT_AUTHORIZATION environment variable.

Azure DevOps Settings

Environment variables that must be configured in the project for Azure DevOps

  • AZURE_DEVOPS_TOKEN Environment variable that stores the value of the token to connect to the API

    How to obtain the AZURE_DEVOPS_TOKEN:

    1. Navigate to Azure DevOps (https://dev.azure.com/{your_organization}).
    2. Click on your profile picture in the upper-right corner and select User Setting.
    3. Click on Personal Access Tokens and the page is loading.
    4. Click blue New Token button.
    5. Ensure you create a token (this often means selecting a scope such as Organization or User with the necessary permissions) with
    • Build (Read)
    • Code (Read)
    • Team Dashboard (Read)
    • Entitlements (Read)
    • Environment (Read & manage)
    • Extension Data (Read)
    • Graph (Read)
    • Identity (Read)
    • Deployment Groups (Read & manage)
    • Member Entitlement Management (Read)
    • Pipeline Resources (Use)
    • User Profile (Read)
    • Project and Team (Read)
    • Security (Manage)
    • Task Groups (Read)
    • Pull Request Threads (Read & write)
    • Variable Groups (Read)
    • Notifications(Read)
    • Packaging (Read)
    • Release (Read)
    • Service Connections (Read)
    • Test Management (Read)
    1. Copy the token value and set it as the AZURE_DEVOPS_TOKEN environment variable.
    2. Note: For operations involving team management, the token must have elevated permissions or be a super token.
  • AZURE_DEVOPS_ORGANIZATION Environment variable that stores the value of the workspace to process, and the token should be created by Team Project Administrator Role.

    How to obtain the AZURE_DEVOPS_ORGANIZATION:

    1. Go to your Azure DevOps organization URL (e.g., https://dev.azure.com/{your_organization}).
    2. The organization name is part of the URL and is typically found after dev.azure.com/. For example, in https://dev.azure.com/cleverit, the organization is cleverit.
    3. Set this value as the AZURE_DEVOPS_ORGANIZATION environment variable.

Bitbucket Settings

Only the Cloud version is supported

Environment variables that must be configured in the project for Bitbucket

  • BITBUCKET_CLIENT_ID Environment variable that stores the value of the user's KEY token to connect to the API
  • BITBUCKET_CLIENT_SECRET Environment variable that stores the value of the user's SECRET token to connect to the API

    How to obtain the BITBUCKET_CLIENT_ID and BITBUCKET_CLIENT_SECRET: To obtain the value of the BITBUCKET_CLIENT_ID and BITBUCKET_CLIENT_SECRET variables we can access it by following Settings->Workspace settings->OAuth consumers->Add OAuth consumer.

    1. Click Settings and then click Workspace settings.
    2. In the Workspace settings section, locate the OAuth consumers option in the menu and click on it.
    3. Click the Add consumer button and configure the properties for the connection to Bitbucket. You must provide a name (Name), any url (Callback URL), check the This is a private consumer option and check all read permissions.
    4. Save the changes by clicking the Save button. Copy the generated Key and Secret values.
  • BITBUCKET_WORKSPACE Environment variable that stores the value of the workspace to process

GitHub Copilot Settings

Environment variables that must be configured in the project for obtain GitHub Copilot metrics usage

  • COPILOT_ENTERPRISE Environment variable that stores the value of the GitHub Copilot enterprise to process

  • COPILOT_ORGANIZATION Environment variable that stores the value of the GitHub Copilot organization to process

    If the enterprise and the organization have the same value, it is not necessary to define the environment variable COPILOT_ORGANIZATION, only the environment variable COPILOT_ENTERPRISE must be defined.

  • COPILOT_TOKEN Environment variable that stores the value of the OAuth app tokens for the connection

    OAuth app tokens and personal access tokens (classic) need either the manage_billing:copilot or read:enterprise scopes to use this endpoint.

  • COPILOT_METRICS_LEVEL Environment variable that indicates the load level of the metrics

    Its possible values ​​are organization | enterprise. By default, if this variable is not set, enterprise is assumed.

  • To create a new OAuth app, go to the GitHub Developer settings.

Jira Settings

Only the Cloud version is supported

Environment variables that must be configured in the project for Jira

  • JIRA_URL Environment variable with the connection URL to Jira
  • JIRA_TOKEN Environment variable with the token to connect

    Create an API token for basic authentication (Admin user):

    1. Log in to your Atlassian account
    2. Go to https://id.atlassian.com/manage-profile/security/api-tokens
    3. Select Create API token
    4. Name the token and set an expiration date
    5. Select Create
    6. Select Copy to clipboard
  • JIRA_USER Environment variable with the user's email associated with the token to connect

Microsoft Teams Settings

Environment variables that must be configured in the project for Microsoft Teams integration:

  • TEAMS_TENANT_ID: Directory (tenant) ID of your Azure Active Directory.
  • TEAMS_CLIENT_ID: Application (client) ID of your registered app in Azure.
  • TEAMS_CLIENT_SECRET: Secret value generated for your app registration.
  • TEAMS_PERMISSIONS: Required Microsoft Graph API permissions (see below).
How to register your application and obtain the required values:
  1. Go to Azure Portal and sign in.
  2. Navigate to Azure Active Directory → App registrations → New registration.
  3. Fill in the required fields and click Register.
  4. Copy the Directory (tenant) ID and Application (client) ID.
  5. Go to Certificates & Secrets → Client secrets, click New client secret, and copy the secret value (⚠️ it will only be shown once).
  6. Go to API permissions → Add a permission → Microsoft Graph and add the following Application permissions:
  • Reports.Read.All
  • User.Read.All
  1. Click Grant admin consent for your tenant to apply the permissions.