> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/stormkit-io/stormkit-io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

## Accessing Git Provider Configuration

<Steps>
  <Step title="Open Your Profile">
    Click on your **profile** in the top right corner of the Stormkit interface.
  </Step>

  <Step title="Navigate to Admin">
    Select **Admin** from the dropdown menu.
  </Step>

  <Step title="Go to Git Settings">
    Navigate to **Git** or go directly to `/admin/git`.
  </Step>
</Steps>

## GitHub Authentication

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

### Setup Steps

<Steps>
  <Step title="Navigate to Git Settings">
    Go to `/admin/git` in your Stormkit instance.
  </Step>

  <Step title="Click GitHub">
    Click the **GitHub** button to begin configuration.
  </Step>

  <Step title="Enter App Name">
    Provide a unique **App Name** for your GitHub App. This name will be visible to users when they authorize the app.
  </Step>

  <Step title="Create App">
    Click **Create**. Stormkit will automatically:

    * Create the GitHub App with correct permissions
    * Configure webhook endpoints
    * Set up callback URLs
    * Enable authentication immediately
  </Step>
</Steps>

<Note>
  No manual configuration is required. Stormkit handles all GitHub App settings automatically.
</Note>

### Environment Variables

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

```bash .env theme={null}
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

<Steps>
  <Step title="Go to GitLab Settings">
    Navigate to [GitLab Developer Settings](https://gitlab.com/-/user_settings/applications).
  </Step>

  <Step title="Add New Application">
    Click **Add new application**.
  </Step>

  <Step title="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)
  </Step>

  <Step title="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)
  </Step>

  <Step title="Save and Copy Credentials">
    Click **Save application** and copy:

    * **Application ID**
    * **Secret**
  </Step>
</Steps>

### Step 2: Configure in Stormkit

<Steps>
  <Step title="Navigate to Git Settings">
    Go to `/admin/git` in your Stormkit instance.
  </Step>

  <Step title="Click GitLab">
    Click the **GitLab** button.
  </Step>

  <Step title="Enter Credentials">
    The **Redirect URI** will be displayed automatically. Enter:

    * **Client ID**: Your GitLab Application ID
    * **Client Secret**: Your GitLab Secret key
  </Step>

  <Step title="Save Configuration">
    Click **Save** to enable GitLab authentication.
  </Step>
</Steps>

### Environment Variables

GitLab authentication uses these environment variables:

```bash .env theme={null}
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

<Steps>
  <Step title="Go to Workspace Settings">
    Navigate to your Bitbucket workspace settings.
  </Step>

  <Step title="Access OAuth Consumers">
    Go to **OAuth consumers** in the workspace settings.
  </Step>

  <Step title="Add Consumer">
    Click **Add consumer**.
  </Step>

  <Step title="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)
  </Step>

  <Step title="Grant Permissions">
    Select the necessary permissions for repository access:

    * Repository read access
    * Repository write access (for webhooks)
  </Step>

  <Step title="Save and Copy Credentials">
    Click **Save** and copy:

    * **Key** (Client ID)
    * **Secret**
  </Step>
</Steps>

### Step 2: Configure in Stormkit

<Steps>
  <Step title="Navigate to Git Settings">
    Go to `/admin/git` in your Stormkit instance.
  </Step>

  <Step title="Click Bitbucket">
    Click the **Bitbucket** button.
  </Step>

  <Step title="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
  </Step>

  <Step title="Save Configuration">
    Click **Save** to enable Bitbucket authentication.
  </Step>
</Steps>

### Environment Variables

Bitbucket authentication uses these environment variables:

```bash .env theme={null}
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

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

## Security Best Practices

<Warning>
  Follow these security recommendations when configuring authentication:
</Warning>

### 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

```bash .env theme={null}
STORMKIT_HTTPS=on
STORMKIT_ACME_EMAIL=admin@yourdomain.com
```

### Access Control

* Limit admin access to trusted team members
* Regularly review authorized applications and users
* Enable user management controls (see [Managing Users](/self-hosting/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:

```bash .env theme={null}
# 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=admin@yourdomain.com

# 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

<CardGroup cols={2}>
  <Card title="Managing Users" icon="users" href="/self-hosting/managing-users">
    Configure user access and sign-up controls
  </Card>

  <Card title="Runtimes" icon="code" href="/self-hosting/runtimes">
    Manage programming language runtimes
  </Card>
</CardGroup>