Service accounts

Service accounts (also known as bot accounts or machine users) are GitHub accounts created specifically for automated scenarios such as CI/CD pipelines. Unlike personal accounts which are tied to individuals, service accounts are designed for non-human use cases where automation needs to access repositories.

Why use a service account?

When automating tasks that require repository access, you might be tempted to use a personal access token (PAT) from your own account. However, this approach has several drawbacks:

Security risk: If the token is compromised, an attacker could access all repositories your account has access to.
Attribution: Commits and actions appear under your personal account, making it harder to distinguish automated activity from manual changes.
Account dependency: If you leave the organisation or your account is suspended, any automation using your token will break.
Permission scope: Personal tokens often have broader access than necessary for specific automation tasks.

Service accounts solve these problems by providing:

Isolation: A separate account with only the permissions needed for automation.
Clear attribution: Actions are clearly labelled as automated.
Continuity: The account isn’t tied to any individual’s employment status.
Principle of least privilege: Access can be scoped to exactly what’s needed.

Creating a service account

Service accounts on GitHub are standard user accounts that are designated for automation purposes. Follow these steps to create one:

1. Create a new GitHub account

Go to github.com/signup.
Use a dedicated email address for the service account. This should be a shared mailbox or distribution list that your team can access (for example, my-project-bot@imperial.ac.uk).
Choose a username that clearly identifies the account as a bot. Common naming conventions include:
- myproject-bot
- myproject-automation
- myproject-ci
Complete the account creation process.

Use a shared mailbox or distribution list for the service account email rather than an individual’s email address. This ensures the account remains accessible if team members change.

2. Secure the service account

Once the account is created, secure it properly:

Enable two-factor authentication (2FA): Navigate to Settings > Password and authentication and enable 2FA. Store the recovery codes securely in a shared secrets manager (e.g. Password Manager).
Document ownership: Record who has access to the service account and where its credentials are stored. This should be documented in your team’s internal documentation.

3. Obtain organisation membership

The service account needs to be a member of the Imperial College London organisation to access internal and private repositories. To add the service account as a member, follow the instructions gaining access to the Imperial College London organisation. When linking the GitHub account with the Imperial account, ensure to use the email address of the service account (e.g. my-project-bot@imperial.ac.uk).

Granting repository access

Once the service account is part of the organisation, you need to grant it access to the specific repositories it needs.

Adding to a repository

Navigate to your repository on GitHub.
Go to Settings > Collaborators and teams.
Click Add people.
Search for your service account username and select it.
Choose an appropriate role:
- Read: For read-only access (cloning, fetching).
- Triage: For managing issues and pull requests without code access.
- Write: For pushing commits and managing branches.
- Maintain: For managing the repository without access to sensitive settings.
- Admin: For full repository access (use sparingly).

Follow the principle of least privilege. Only grant the minimum permissions required for the automation to function. For most CI/CD scenarios, Write access is sufficient.

Adding to a team

If the service account needs access to multiple repositories, consider adding it to a team instead:

Navigate to your organisation’s Teams page.
Select the appropriate team or create a new one.
Click Members > Add a member.
Search for your service account and add it to the team.

The service account will inherit access to all repositories the team has access to.

Creating credentials for automation

Service accounts can authenticate using personal access tokens (PATs). There are two types of PATs available:

Fine-grained personal access tokens (recommended)

Fine-grained PATs offer more granular control over permissions and are the recommended choice for service accounts.

Log in to the service account on GitHub.
Navigate to Settings > Developer settings > Personal access tokens > Fine-grained tokens.
Click Generate new token.
Configure the token:
- Token name: Use a descriptive name (for example, ci-pipeline-repo-access).
- Resource owner: Select ImperialCollegeLondon.
- Expiration: Set an appropriate expiration date.
- Repository access: Select Only select repositories and choose only the repositories the automation needs.
- Permissions: Grant only the specific permissions required. Common permissions include:
  - Contents: Read and write (for cloning and pushing code).
  - Metadata: Read (required for most operations).
  - Pull requests: Read and write (if creating/updating PRs).
Click Generate token.
Copy the token immediately and store it securely.

The token is only displayed once. Store it immediately in a secure location such as a secrets manager or GitHub Actions secrets.

Classic personal access tokens

Classic PATs are simpler but offer less granular control. Use these only if fine-grained PATs don’t meet your needs.

Log in to the service account on GitHub.
Navigate to Settings > Developer settings > Personal access tokens > Tokens (classic).
Click Generate new token (classic).
Configure the token:
- Note: Use a descriptive name.
- Expiration: Set an appropriate expiration date.
- Scopes: Select only the scopes required:
  - repo: Full control of private repositories.
  - read:org: Read organisation membership (if needed).
Click Generate token.
Copy the token immediately and store it securely.

Storing tokens securely

Never store tokens in plain text in your code or configuration files. Instead, follow the guidelines under Secrets management.

Using the service account in GitHub Actions

Here’s an example of how to use a service account PAT in a GitHub Actions workflow to clone a private repository:

name: Build with private dependency

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Clone private dependency
        run: |
          git clone https://x-access-token:$@github.com/ImperialCollegeLondon/private-dependency.git

In this example, SERVICE_ACCOUNT_PAT is a repository secret containing the personal access token from the service account.

For GitHub Actions workflows that only need to access the repository they’re running in, consider using the built-in GITHUB_TOKEN instead of a service account PAT. The GITHUB_TOKEN is automatically generated and scoped to the current repository.

Best practices

Token management

Set expiration dates: Always set an expiration date on tokens.
Rotate tokens regularly: Even with expiration dates, rotate tokens periodically and whenever team members with access leave.
Use minimal scopes: Only grant the permissions that are actually needed.
Monitor usage: Regularly review the service account’s activity in the Security log.

Account management

Document the account: Maintain documentation about what the service account is used for and who manages it.
Use a shared mailbox: Ensure the email address is accessible to multiple team members.
Review access periodically: Regularly audit which repositories the service account has access to and remove unnecessary permissions.
Enable security alerts: Configure the service account to receive security notifications for repositories it has access to.