Service accounts

Supported on Enterprise plans.

Available via the Web app.

Service accounts in Sourcegraph are special types of accounts designed for automated tasks and integrations. Unlike regular user accounts, service accounts cannot sign into Sourcegraph directly and can only be used through their associated access tokens.

What are service accounts?

Service accounts are non-human accounts that enable:

  • Automated operations: Run scripts, CI/CD pipelines, or other automated processes that interact with Sourcegraph
  • API integrations: Build applications that need to access Sourcegraph programmatically
  • Secure token management: Create dedicated tokens for specific purposes without using personal user accounts

Key characteristics of service accounts:

  • Cannot sign in: Service accounts cannot access the Sourcegraph web interface directly
  • Token-based access only: All operations must be performed using access tokens
  • No user seat usage: Service accounts don't count toward your user seat limit and won't affect billing
  • RBAC compatible: Can be assigned custom roles and permissions like regular users

Why use service accounts?

Service accounts provide several advantages over using personal user accounts for automated tasks:

Security benefits

  • Isolated permissions: Scope access to only what's needed for specific automation tasks
  • No human login: Eliminates risk of compromised human credentials affecting automation
  • Audit trail: Clearly identify automated vs. human actions in logs and audit trails

Management benefits

  • Independent lifecycle: Service accounts persist even if team members leave or change roles
  • Dedicated purpose: Each service account can be tailored for specific use cases
  • No billing impact: Unlimited service accounts without affecting user seat counts

Common use cases

  • CI/CD pipelines: Automate code analysis, search operations, or batch changes
  • Monitoring and alerting: Create dashboards or alerts based on Sourcegraph data
  • Data integration: Sync repository data with external systems
  • Batch operations: Perform bulk operations across multiple repositories

Creating service accounts

To create a service account:

  1. Navigate to Site admin > Users & auth > Service accounts
  2. Click + Create service account
  3. Provide a descriptive name for the service account
  4. Optionally add a description explaining its purpose
  5. Click Create

NOTE: Only site administrators can create and manage service accounts.

Managing access tokens

Once you've created a service account, you'll need to create access tokens for it to perform operations:

Creating access tokens

  1. From the service accounts list, click on the service account you want to create a token for
  2. In the Access tokens section, click + Generate new token
  3. Provide a descriptive name for the token
  4. Set an expiration date (recommended for security)
  5. Click Generate token
  6. Important: Copy the token immediately - it will not be shown again

Token security best practices

  • Use descriptive names: Clearly identify what each token is used for
  • Set expiration dates: Regularly rotate tokens by setting reasonable expiration periods
  • Limit scope: Assign minimal necessary permissions to the service account
  • Secure storage: Store tokens securely in your automation systems (environment variables, secret managers)
  • Monitor usage: Review access logs to ensure tokens are being used appropriately

Permissions and role-based access control

Service accounts can be assigned custom roles just like regular users, enabling fine-grained permission control.

Assigning roles

  1. Navigate to Site admin > Users & auth > Users
  2. Find the service account in the user list
  3. Click the triple dots to open the context menu
  4. Select Manage roles
  5. Assign or remove roles as needed
  6. Click Update to save changes

Permission scoping

Use RBAC to limit service account permissions:

  • Batch Changes: Control whether the service account can create, modify, or execute batch changes
  • Repository access: Combine with repository permissions to limit which repositories the service account can access
  • Custom roles: Create specific roles tailored to your automation needs

Example role configurations:

  • CI/CD Service: Read-only access to repositories, can trigger searches
  • Batch Change Automation: Can create and execute batch changes on specific repositories
  • Monitoring Service: Read-only access for generating reports and dashboards

API usage with service accounts

Service accounts work with all Sourcegraph APIs using their access tokens:

GraphQL API

BASH
curl -H "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"query": "{ currentUser { username } }"}' \
     https://your-sourcegraph-instance.com/.api/graphql

REST APIs

BASH
curl -H "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>" \
     https://your-sourcegraph-instance.com/.api/search/stream?q=test

Monitoring service account activity

Track service account usage through:

  • Audit logs: All service account actions are logged with clear identification
  • Security event logs: Monitor for unusual access patterns or failures
  • Access token usage: Review when tokens were last used and from where

Troubleshooting

Common issues

Service account token not working

  • Verify the token hasn't expired
  • Check that the service account has the necessary permissions
  • Ensure the token is being passed correctly in API requests

Permission denied errors

  • Review the service account's assigned roles
  • Check repository-level permissions if accessing specific repositories
  • Verify the required permissions are included in the service account's roles

Token generation fails

  • Ensure you have site administrator privileges
  • Check that the service account exists and is active
  • Verify there are no conflicting token names

Best practices

  1. Use meaningful names: Name service accounts and tokens descriptively (e.g., ci-batch-changes, monitoring-dashboard)
  2. Regular token rotation: Set expiration dates and rotate tokens periodically
  3. Minimal permissions: Grant only the permissions necessary for each use case
  4. Monitor and audit: Regularly review service account activity and permissions
  5. Document usage: Keep records of what each service account is used for and by which systems
  6. Secure token storage: Never commit tokens to code repositories; use secure secret management