> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Providers

> Connect GitHub, GitLab, and Bitbucket for CI/CD pipelines

Git Providers connect your source code repositories to the CI Platform. Configure provider credentials to enable automatic pipeline triggers, code checkout, and repository management.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Provider" icon="git-alt">
    A connection to a Git hosting service (GitHub, GitLab, or Bitbucket) with authentication credentials.
  </Card>

  <Card title="Access Token" icon="key">
    A personal access token or app password used to authenticate API requests and Git operations.
  </Card>

  <Card title="Default Provider" icon="star">
    The provider automatically selected when creating new pipeline projects.
  </Card>

  <Card title="Organization" icon="building">
    Optional organization or workspace scope for accessing organization-level repositories.
  </Card>
</CardGroup>

## Required Permissions

| Action           | Permission                          |
| ---------------- | ----------------------------------- |
| View providers   | `iam:project:cicd:providers:read`   |
| Create providers | `iam:project:cicd:providers:write`  |
| Edit providers   | `iam:project:cicd:providers:write`  |
| Test connection  | `iam:project:cicd:providers:write`  |
| Delete providers | `iam:project:cicd:providers:delete` |

## Supported Providers

| Provider      | Token Type                                      | Organization Field |
| ------------- | ----------------------------------------------- | ------------------ |
| **GitHub**    | Personal Access Token (Classic or Fine-grained) | Organization       |
| **GitLab**    | Personal Access Token                           | Group/Organization |
| **Bitbucket** | App Password                                    | Workspace          |

## How to Add a Provider

<Steps>
  <Step title="Click Add Provider">
    Click the **Add Provider** button in the header.
  </Step>

  <Step title="Select Provider Type">
    Choose GitHub, GitLab, or Bitbucket. This cannot be changed after creation.
  </Step>

  <Step title="Enter Provider Name">
    Give the provider a descriptive name (e.g., "Production GitHub", "Team GitLab").
  </Step>

  <Step title="Enter Username">
    Provide your Git username for the provider.
  </Step>

  <Step title="Enter Access Token">
    Paste your personal access token or app password.
  </Step>

  <Step title="Configure Organization (Optional)">
    Enter the organization, group, or workspace name to scope repository access.
  </Step>

  <Step title="Set Status">
    Toggle **Active** to enable the provider. Toggle **Default** to use as default for new projects.
  </Step>

  <Step title="Create">
    Click **Add Provider** to save.
  </Step>
</Steps>

## Token Requirements

### GitHub

Create a Personal Access Token at GitHub → Settings → Developer settings → Personal access tokens.

**Required Scopes (Classic Token):**

* `repo` - Full control of private repositories
* `admin:repo_hook` - Full control of repository hooks (for webhooks)
* `read:org` - Read organization membership (if using organization)

**Fine-grained Token Permissions:**

* Repository access: All repositories or specific repositories
* Permissions: Contents (Read and write), Webhooks (Read and write), Metadata (Read)

### GitLab

Create a Personal Access Token at GitLab → User Settings → Access Tokens.

**Required Scopes:**

* `api` - Full API access
* `read_repository` - Read repository content
* `write_repository` - Write to repository

### Bitbucket

Create an App Password at Bitbucket → Personal settings → App passwords.

**Required Permissions:**

* Account: Read
* Repositories: Read, Write, Admin
* Webhooks: Read and write

<Warning>
  Store tokens securely. Tokens are encrypted at rest but provide full access to your repositories.
</Warning>

## How to Edit a Provider

<Steps>
  <Step title="Find the Provider">
    Locate the provider in the list.
  </Step>

  <Step title="Click Edit">
    Click the edit (pencil) icon on the provider row.
  </Step>

  <Step title="Modify Settings">
    Update name, username, organization, or status. Leave access token blank to keep the existing token.
  </Step>

  <Step title="Update Token (Optional)">
    Enter a new access token only if you need to rotate credentials.
  </Step>

  <Step title="Save">
    Click **Save Changes** to apply updates.
  </Step>
</Steps>

<Info>
  Provider type cannot be changed after creation. Create a new provider if you need a different type.
</Info>

## How to Test Connection

<Steps>
  <Step title="Find the Provider">
    Locate the provider in the list.
  </Step>

  <Step title="Click Test">
    Click the **Test** button on the provider row.
  </Step>

  <Step title="Review Result">
    A success or failure message indicates connection status.
  </Step>
</Steps>

<Tip>
  Test connection after creating or updating a provider to verify credentials are valid.
</Tip>

## How to Set Default Provider

<Steps>
  <Step title="Edit the Provider">
    Click the edit icon on the provider you want as default.
  </Step>

  <Step title="Enable Default">
    Toggle **Default Provider** to on.
  </Step>

  <Step title="Save">
    Click **Save Changes**. The previous default (if any) is automatically unset.
  </Step>
</Steps>

## How to Delete a Provider

<Steps>
  <Step title="Find the Provider">
    Locate the provider to delete.
  </Step>

  <Step title="Click Delete">
    Click the delete (trash) icon.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. This action cannot be undone.
  </Step>
</Steps>

<Warning>
  Deleting a provider may break existing projects that use it. Reassign projects to another provider before deletion.
</Warning>

## Provider-Specific Configuration

### GitHub

| Field            | Description                                                       |
| ---------------- | ----------------------------------------------------------------- |
| **Username**     | Your GitHub username                                              |
| **Organization** | Optional. GitHub organization name for accessing org repositories |
| **Access Token** | Personal access token with required scopes                        |

### GitLab

| Field            | Description                                                  |
| ---------------- | ------------------------------------------------------------ |
| **Username**     | Your GitLab username                                         |
| **Organization** | Optional. GitLab group name for accessing group repositories |
| **Access Token** | Personal access token with api scope                         |

### Bitbucket

| Field            | Description                                                   |
| ---------------- | ------------------------------------------------------------- |
| **Username**     | Your Bitbucket username                                       |
| **Email**        | Your Bitbucket email (used for authentication)                |
| **Workspace**    | Bitbucket workspace slug for accessing workspace repositories |
| **Access Token** | App password with required permissions                        |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection test failed" icon="circle-question">
    * Verify access token has required scopes/permissions
    * Check if token has expired
    * Ensure username is correct
    * For Bitbucket, verify email is provided
    * Check if organization/workspace name is spelled correctly
  </Accordion>

  <Accordion title="Cannot see repositories" icon="circle-question">
    * Verify token has repository read permissions
    * Check organization/workspace is set correctly
    * Ensure token has access to the organization
    * For private repos, verify token scope includes private repository access
  </Accordion>

  <Accordion title="Webhook not triggering pipelines" icon="circle-question">
    * Verify provider is active
    * Check webhook configuration in repository settings
    * Ensure token has webhook permissions
    * Verify the webhook URL is accessible from the internet
  </Accordion>

  <Accordion title="Cannot create provider" icon="circle-question">
    * Access token is required for new providers
    * Verify you have write permission
    * Check if provider name is unique
  </Accordion>

  <Accordion title="Clone/checkout failing in pipelines" icon="circle-question">
    * Verify provider is active
    * Check if token has write permission for the repository
    * Ensure organization/workspace settings match repository location
    * Token may have expired - update with new token
  </Accordion>

  <Accordion title="Cannot delete provider" icon="circle-question">
    * Check if projects are using this provider
    * Reassign projects to another provider first
    * Verify you have delete permission
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can I use the same token for multiple providers?">
    Yes, but it's not recommended. Use separate tokens for each provider configuration to enable independent rotation and access control.
  </Accordion>

  <Accordion title="How do I rotate access tokens?">
    Edit the provider and enter the new token in the Access Token field. The old token is replaced immediately. Update any external systems using the old token.
  </Accordion>

  <Accordion title="What happens if a token expires?">
    Pipelines using that provider will fail authentication. Update the provider with a new token as soon as possible.
  </Accordion>

  <Accordion title="Can I have multiple providers of the same type?">
    Yes. You can have multiple GitHub, GitLab, or Bitbucket providers. This is useful for different organizations, teams, or access levels.
  </Accordion>

  <Accordion title="What's the difference between organization and personal repositories?">
    Personal repositories are under your username. Organization repositories are under an org/group/workspace. Set the organization field to access org-level repositories.
  </Accordion>

  <Accordion title="Are access tokens encrypted?">
    Yes. Access tokens are encrypted at rest in the database. They are decrypted only when needed for Git operations.
  </Accordion>

  <Accordion title="Can I use SSH keys instead of tokens?">
    Currently, only personal access tokens and app passwords are supported. SSH key authentication is not available.
  </Accordion>

  <Accordion title="What if I change my Git username?">
    Edit the provider to update the username. Ensure the access token is still valid for the new username.
  </Accordion>
</AccordionGroup>

## Best Practices

### Security

* Use tokens with minimum required permissions
* Rotate tokens regularly (every 90 days recommended)
* Create separate tokens for each environment
* Never share tokens between team members
* Use fine-grained tokens when available (GitHub)

### Organization

* Use descriptive provider names (include environment, team, or purpose)
* Set a default provider for consistent project creation
* Deactivate unused providers instead of deleting (preserves history)
* Document which provider each project uses

### Token Management

* Store tokens in a password manager before adding to the platform
* Set calendar reminders for token rotation
* Test connection after token rotation
* Monitor provider status in the dashboard

### Multi-Provider Setup

For organizations with multiple Git platforms:

```
production-github    → Production repositories (GitHub)
development-gitlab   → Development repositories (GitLab)
vendor-bitbucket     → Vendor integrations (Bitbucket)
```

This allows:

* Different access levels per environment
* Separate token rotation schedules
* Clear project organization by provider