Authentication

Configure authentication for your self-hosted Stormkit instance with GitHub, GitLab, or Bitbucket integration

Authentication is a critical component of your self-hosted Stormkit instance. This guide covers setting up admin accounts and configuring Git provider integrations.

Admin Account

During the initial setup, you’ll create an admin account with full access to your Stormkit instance.

Admin Capabilities

The admin account can:

• Access the admin interface at /admin
• Configure global instance settings
• Import public repositories
• Create bare applications
• Manage user access and permissions
• Configure Git provider authentication

To import private repositories, you must configure at least one Git provider (GitHub, GitLab, or Bitbucket).

Accessing Git Provider Configuration

1. Open Your Profile

   Click on your profile in the top right corner of the Stormkit interface.

2. Navigate to Admin

   Select Admin from the dropdown menu.

3. Go to Git Settings

   Navigate to Git or go directly to /admin/git.

GitHub Authentication

GitHub authentication is the simplest provider to configure. Stormkit automatically creates a GitHub App with all necessary permissions and configurations.

Setup Steps

1. Navigate to Git Settings

   Go to /admin/git in your Stormkit instance.

2. Click GitHub

   Click the GitHub button to begin configuration.

3. Enter App Name

   Provide a unique App Name for your GitHub App. This name will be visible to users when they authorize the app.

4. Create App

   Click Create. Stormkit will automatically:

   • Create the GitHub App with correct permissions
   • Configure webhook endpoints
   • Set up callback URLs
   • Enable authentication immediately

No manual configuration is required. Stormkit handles all GitHub App settings automatically.

Environment Variables

After creating the GitHub App, the following environment variables will be used:

.env

GITHUB_APP_ID=your_app_id
GITHUB_APP_NAME=your_app_name
GITHUB_CLIENT_ID=your_client_id
GITHUB_PRIV_KEY=your_private_key
GITHUB_SECRET=your_secret

These are automatically configured through the admin interface.

GitLab Authentication

To enable GitLab authentication, you need to manually create a GitLab Application first.

Step 1: Create GitLab Application

1. Go to GitLab Settings

   Navigate to GitLab Developer Settings.

2. Add New Application

   Click Add new application.

3. Configure Application

   Fill in the required fields:

   • Name: Choose a unique name for your application (e.g., “Stormkit Self-Hosted”)
   • Redirect URI: Get this from the Stormkit configuration modal (pre-configured and displayed)
4. Select Scopes

   Grant the following permissions:

   • read_user - Read user profile information
   • read_repository - Read repository data
   • write_repository - Write to repositories (for webhooks and deployment status)
5. Save and Copy Credentials

   Click Save application and copy:

   • Application ID
   • Secret

Step 2: Configure in Stormkit

1. Navigate to Git Settings

   Go to /admin/git in your Stormkit instance.

2. Click GitLab

   Click the GitLab button.

3. Enter Credentials

   The Redirect URI will be displayed automatically. Enter:

   • Client ID: Your GitLab Application ID
   • Client Secret: Your GitLab Secret key
4. Save Configuration

   Click Save to enable GitLab authentication.

Environment Variables

GitLab authentication uses these environment variables:

.env

GITLAB_CLIENT_ID=your_application_id
GITLAB_SECRET=your_secret_key
GITLAB_REDIRECT_URL=https://your-domain.com/auth/gitlab/callback

Bitbucket Authentication

To enable Bitbucket authentication, you need to create a Bitbucket OAuth Consumer.

Step 1: Create Bitbucket OAuth Consumer

1. Go to Workspace Settings

   Navigate to your Bitbucket workspace settings.

2. Access OAuth Consumers

   Go to OAuth consumers in the workspace settings.

3. Add Consumer

   Click Add consumer.

4. Configure Consumer

   Fill in the required fields:

   • Name: Choose a unique name (e.g., “Stormkit Self-Hosted”)
   • Callback URL: Get this from the Stormkit configuration modal (pre-configured)
5. Grant Permissions

   Select the necessary permissions for repository access:

   • Repository read access
   • Repository write access (for webhooks)
6. Save and Copy Credentials

   Click Save and copy:

   • Key (Client ID)
   • Secret

Step 2: Configure in Stormkit

1. Navigate to Git Settings

   Go to /admin/git in your Stormkit instance.

2. Click Bitbucket

   Click the Bitbucket button.

3. Enter Credentials

   Enter the following information:

   • Client ID: Your OAuth consumer Key
   • Client Secret: Your OAuth consumer Secret
   • Deploy Key (optional): Specific deploy key for repository access
4. Save Configuration

   Click Save to enable Bitbucket authentication.

Environment Variables

Bitbucket authentication uses these environment variables:

.env

BITBUCKET_CLIENT_ID=your_oauth_key
BITBUCKET_SECRET=your_oauth_secret
BITBUCKET_DEPLOY_KEY=your_deploy_key  # Optional

Webhook Configuration

After configuring Git provider authentication, Stormkit will automatically set up webhooks for your repositories. These webhooks enable:

• Automatic deployments on push events
• Pull request previews for code review
• Deployment status updates back to your Git provider
• Branch protection integration

Webhook endpoints are automatically configured based on your STORMKIT_WEBHOOKS_URL environment variable. If not set, it defaults to STORMKIT_API_URL.

Security Best Practices

Follow these security recommendations when configuring authentication:

Secure Secrets

• Store all credentials in environment variables, never in code
• Use strong, randomly generated secrets for STORMKIT_APP_SECRET
• Rotate credentials periodically
• Limit OAuth app permissions to only what’s necessary

Network Security

• Always use HTTPS in production (STORMKIT_HTTPS=on)
• Configure proper TLS certificates
• Use the STORMKIT_ACME_EMAIL variable for automatic Let’s Encrypt certificates

.env

STORMKIT_HTTPS=on
STORMKIT_ACME_EMAIL=[e-mail]

Access Control

• Limit admin access to trusted team members
• Regularly review authorized applications and users
• Enable user management controls (see Managing Users)

Troubleshooting Authentication

OAuth Callback Errors

If you see “redirect_uri_mismatch” errors:

1. Verify the Redirect URI in your Git provider settings matches exactly
2. Ensure STORMKIT_APP_URL is set correctly in your .env file
3. Check that your domain is accessible from the internet

API Connection Issues

If authentication fails with API errors:

1. Verify STORMKIT_API_URL is accessible
2. Check that Redis is running: docker compose ps redis
3. Review logs: docker compose logs -f hosting

Invalid Credentials

If Git provider authentication fails:

1. Verify Client ID and Secret are correct
2. Check that OAuth app permissions include required scopes
3. Ensure the OAuth app is not suspended or revoked

Environment Variables Summary

Here’s a complete reference of authentication-related environment variables:

.env

# Core Authentication
STORMKIT_APP_SECRET=your_random_secret_key
STORMKIT_API_URL=https://api.yourdomain.com
STORMKIT_APP_URL=https://yourdomain.com
STORMKIT_WEBHOOKS_URL=https://api.yourdomain.com/webhooks

# HTTPS Configuration
STORMKIT_HTTPS=on
STORMKIT_ACME_EMAIL=[e-mail]

# GitHub
GITHUB_APP_ID=
GITHUB_APP_NAME=
GITHUB_CLIENT_ID=
GITHUB_PRIV_KEY=
GITHUB_SECRET=

# GitLab
GITLAB_CLIENT_ID=
GITLAB_SECRET=
GITLAB_REDIRECT_URL=

# Bitbucket
BITBUCKET_CLIENT_ID=
BITBUCKET_SECRET=
BITBUCKET_DEPLOY_KEY=

Next Steps

Managing Users

Configure user access and sign-up controls

Runtimes

Manage programming language runtimes