Skip to main content

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.

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

Provider

A connection to a Git hosting service (GitHub, GitLab, or Bitbucket) with authentication credentials.

Access Token

A personal access token or app password used to authenticate API requests and Git operations.

Default Provider

The provider automatically selected when creating new pipeline projects.

Organization

Optional organization or workspace scope for accessing organization-level repositories.

​
Required Permissions

ActionPermission
View providersiam:project:cicd:providers:read
Create providersiam:project:cicd:providers:write
Edit providersiam:project:cicd:providers:write
Test connectioniam:project:cicd:providers:write
Delete providersiam:project:cicd:providers:delete

​
Supported Providers

ProviderToken TypeOrganization Field
GitHubPersonal Access Token (Classic or Fine-grained)Organization
GitLabPersonal Access TokenGroup/Organization
BitbucketApp PasswordWorkspace

​
How to Add a Provider

1

Click Add Provider

Click the Add Provider button in the header.
2

Select Provider Type

Choose GitHub, GitLab, or Bitbucket. This cannot be changed after creation.
3

Enter Provider Name

Give the provider a descriptive name (e.g., “Production GitHub”, “Team GitLab”).
4

Enter Username

Provide your Git username for the provider.
5

Enter Access Token

Paste your personal access token or app password.
6

Configure Organization (Optional)

Enter the organization, group, or workspace name to scope repository access.
7

Set Status

Toggle Active to enable the provider. Toggle Default to use as default for new projects.
8

Create

Click Add Provider to save.

​
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
Store tokens securely. Tokens are encrypted at rest but provide full access to your repositories.

​
How to Edit a Provider

1

Find the Provider

Locate the provider in the list.
2

Click Edit

Click the edit (pencil) icon on the provider row.
3

Modify Settings

Update name, username, organization, or status. Leave access token blank to keep the existing token.
4

Update Token (Optional)

Enter a new access token only if you need to rotate credentials.
5

Save

Click Save Changes to apply updates.
Provider type cannot be changed after creation. Create a new provider if you need a different type.

​
How to Test Connection

1

Find the Provider

Locate the provider in the list.
2

Click Test

Click the Test button on the provider row.
3

Review Result

A success or failure message indicates connection status.
Test connection after creating or updating a provider to verify credentials are valid.

​
How to Set Default Provider

1

Edit the Provider

Click the edit icon on the provider you want as default.
2

Enable Default

Toggle Default Provider to on.
3

Save

Click Save Changes. The previous default (if any) is automatically unset.

​
How to Delete a Provider

1

Find the Provider

Locate the provider to delete.
2

Click Delete

Click the delete (trash) icon.
3

Confirm

Confirm the deletion. This action cannot be undone.
Deleting a provider may break existing projects that use it. Reassign projects to another provider before deletion.

​
Provider-Specific Configuration

​
GitHub

FieldDescription
UsernameYour GitHub username
OrganizationOptional. GitHub organization name for accessing org repositories
Access TokenPersonal access token with required scopes

​
GitLab

FieldDescription
UsernameYour GitLab username
OrganizationOptional. GitLab group name for accessing group repositories
Access TokenPersonal access token with api scope

​
Bitbucket

FieldDescription
UsernameYour Bitbucket username
EmailYour Bitbucket email (used for authentication)
WorkspaceBitbucket workspace slug for accessing workspace repositories
Access TokenApp password with required permissions

​
Troubleshooting

  • 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
  • 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
  • Verify provider is active
  • Check webhook configuration in repository settings
  • Ensure token has webhook permissions
  • Verify the webhook URL is accessible from the internet
  • Access token is required for new providers
  • Verify you have write permission
  • Check if provider name is unique
  • 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
  • Check if projects are using this provider
  • Reassign projects to another provider first
  • Verify you have delete permission

​
FAQ

Yes, but it’s not recommended. Use separate tokens for each provider configuration to enable independent rotation and access control.
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.
Pipelines using that provider will fail authentication. Update the provider with a new token as soon as possible.
Yes. You can have multiple GitHub, GitLab, or Bitbucket providers. This is useful for different organizations, teams, or access levels.
Personal repositories are under your username. Organization repositories are under an org/group/workspace. Set the organization field to access org-level repositories.
Yes. Access tokens are encrypted at rest in the database. They are decrypted only when needed for Git operations.
Currently, only personal access tokens and app passwords are supported. SSH key authentication is not available.
Edit the provider to update the username. Ensure the access token is still valid for the new username.

​
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