Docker GitHub Runner

This project provides a self hosted GitHub Actions runner that can be registered to a personal repository or to a single repository inside an organisation. The setup uses a fine grained personal access token with minimal permissions for better security.

Personal Repository Setup

1. Log in to your personal GitHub account.

2. Create a fine grained personal access token with:

   • Repository access: only the target repository
   • Permissions:
     • Administration: Read and write (required for runner registration)
     • Actions: Read and write
   • All other permissions set to No access

3. Create a .env file in the same directory as docker-compose.yml:

   GITHUB_USERNAME=your-github-username
   GITHUB_REPO=your-repo-name
   ACCESS_TOKEN=your-fine-grained-token
   

4. Start the runner:

   docker-compose up --build
   

The runner will register itself only to the selected repository.

Organisation Repository Setup

Use this setup when the runner should work with one specific repository inside your organisation.

1. (Recommended) Create a service account, for example: pc-actions-bot

2. Add the service account to your organisation as a member.

3. Grant the account access to the specific repository that will use the runner.

4. Log in as the service account and create a fine grained personal access token with:

   • Repository access: only the target repository
   • Permissions:
     • Administration: Read and write (required for runner registration)
     • Actions: Read and write
   • No organisation permissions required

5. Create a .env file next to docker-compose.yml:

   GITHUB_USERNAME=pc-actions-bot
   GITHUB_REPO=your-repo-name
   ACCESS_TOKEN=your-fine-grained-token
   

   Do not set GITHUB_ORGNAME. Leaving it unset ensures the runner registers at the repository level.

6. Start the runner:

   docker-compose up --build
   

Security Notes

• Use fine grained personal access tokens only.
• Scope the token to a single repository.
• Grant Administration and Actions read write permissions only.
• Do not mount .env into any location used inside workflow jobs.
• Rotate the token regularly.