Skip to main content

Set up your organization

Use this guide to complete the initial configuration of your organization once your on-premises server is up and you can sign in to the portal. You'll install the license key, connect source control, add co-administrators, and get developer data flowing.

  • Deployment: On-premises
  • Role: Owner, Admin

The order matters: each step depends on the one before it, and configuring work areas before data arrives is guesswork you will redo.

Before you begin​

To set up your organization, you need all of the following:

  • A running on-premises server: You can sign in to the portal and reach the home page. See On-premises deployment.
  • Your license key: Obtain it from CodeTogether before starting.
  • Permission to install a GitHub App (for step 2): Required if you intend to connect GitHub.

1. Install your license key​

Your license key activates the platform. Install it before any other configuration, because most portal areas require an active license to render.

  1. In the portal, go to Settings, then select the License tab.
  2. Select Update license, paste your license key, and select Save.

The platform activates immediately. The License tab reports the status as Valid. A key that is expired or malformed shows a distinct status on the same screen.

License tab

The License tab in Settings showing a valid license with its expiry date.

2. Connect GitHub​

Connecting GitHub gives the platform merge-outcome data. Without this connection the platform captures commits and push events, but cannot resolve a push to a merged pull request, so merge-based metrics read as unavailable.

If your organization does not use a supported source-control host, skip this step — see Connect integrations for what's supported. Workstation capture of commits and push events does not depend on this connection, but merge-based metrics stay unavailable.

  1. Go to Settings > Integrations, then select the Source Control tab.
  2. Select Create from Manifest to provision a customer-owned GitHub App.
  3. Select Connect to install the App in your GitHub organization.

See Connect integrations for the full procedure, credential rotation, and troubleshooting.

Source Control tab

The Source Control tab in Settings > Integrations before a GitHub App is provisioned, showing the Create from Manifest button.

3. Add co-administrators​

Add at least one other person with Admin or Owner access. A co-administrator can carry ongoing configuration tasks, including managing work areas, integrations, and users, so that initial setup does not depend on a single account.

An Admin can do everything except billing and Owner-level role grants. An Owner has full control, including billing.

  1. Go to Settings > Access > Users.
  2. Select Invite Admin.
  3. Enter the co-administrator's email address and select Send invite.

The person accepts the invite and receives Admin access on acceptance. To grant Owner access instead, change the role on the Users page after the invite is accepted. See Invite users to your organization for invite kinds, expiry settings, and troubleshooting.

Users tab

The Users tab in Settings > Access showing the active user list and the Invite Admin button.

Invite Admin dialog

The Invite Admin dialog with the email field and Send invite button.

4. Get developer data flowing​

Developers are not invited like members. Their work is captured from the moment the AITrax tracker runs on their machine, and is attributed to their existing Git committer identity — see Members and developers. Sending the workstation setup link is the fastest way to onboard a team.

  1. Select Onboarding in the sidebar.
  2. Under For Managers and Admins, copy the workstation setup link using the Copy link button.
  3. Send the link to your developers. Each developer opens it, picks their editor, and completes installation without needing a portal login.

The Onboarding page also lists pre-configured IDE plugin download links — direct links to the plugin artifacts served from your on-premises server, one per IDE family. Use these when developers need to install manually rather than following the setup link.

Onboarding page

Onboarding page showing the workstation setup URL with Copy link and Open page buttons, and IDE download links below.

For the developer's own steps, see Onboard a developer and Set up your workstation.

5. Shape the views​

Work areas define the slices of activity you want to report on. Configure them after data is arriving, not before — the activity that exists makes the right coverage obvious. Your organization already has a company-wide work area provisioned automatically.

See Your first ten days for what to do as the first data arrives, and Create a work area when you are ready to build additional views.

Troubleshooting​

The license status reads Expired, Invalid, or Not active after saving the key​

The key was accepted but may be for a different deployment or may not yet be active. Confirm the license key matches the one issued for this server. If the status remains Expired, Invalid, or Not active, contact support with the key's issuance date and the status the portal displays.

Developers are not appearing in dashboards after completing setup​

Activity processing is asynchronous. Allow a few minutes after a developer completes setup before checking. If a developer stays absent, see No activity appears for a developer.

If this doesn't fix it​

Contact support with all of the following. Tickets missing these take longer to resolve:

  • The step that failed and the error text or behavior you observed.
  • Your server version (shown at the bottom of the portal sidebar).
  • Your deployment kind (on-premises, Helm).