GitHub OAuth Setup

Configure GitHub OAuth App for browser-based GitHub login.

Table of contents
  1. When to Use OAuth
  2. Step 1: Create a GitHub OAuth App
  3. Step 2: Configure the Container
  4. Step 3: Sign In with GitHub
  5. Using Both OAuth and PAT
  6. Troubleshooting OAuth Issues

When to Use OAuth

  • You prefer the standard Sign in with GitHub browser flow
  • Your team members will log in with their own GitHub accounts
  • Your organization manages app access through GitHub OAuth App approvals

For the fastest single-user setup, a Personal Access Token may be simpler.

Step 1: Create a GitHub OAuth App

  1. Go to GitHub → Settings → Developer settings → OAuth Apps
  2. Click New OAuth App
  3. Fill in the application details:
Field Value
Application name ActionsManager (or your preferred name)
Homepage URL http://localhost:8080 (or your deployment URL)
Authorization callback URL http://localhost:8080/auth/callback
  1. Click Register application
  2. Copy the Client ID
  3. Click Generate a new client secret and copy the Client Secret

If you deploy ActionsManager on a real domain (e.g., https://actions.example.com), update both the Homepage URL and Authorization callback URL to that domain before registering.

Step 2: Configure the Container

Pass the OAuth credentials as environment variables when starting ActionsManager:

docker run -d \
  --name actions-manager \
  -p 8080:8080 \
  -v actions-manager-data:/app/backend \
  -e INSTALLATION_MODE=self-hosted \
  -e SECRET_KEY=$(openssl rand -hex 32) \
  -e REACT_APP_BACKEND_URL=http://localhost:8080 \
  -e REACT_APP_FRONTEND_URL=http://localhost:8080 \
  -e REACT_APP_WEBSOCKET_URL=ws://localhost:8080/ws \
  -e GITHUB_CLIENT_ID=your_client_id \
  -e GITHUB_CLIENT_SECRET=your_client_secret \
  ghcr.io/turbo5000c/actions-manager/self-hosted:latest

Or in Docker Compose (using a .env file):

environment:
  - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
  - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}

Never commit your GITHUB_CLIENT_SECRET to source control. Use environment variables, a .env file that is excluded from git, or a secrets manager.

Step 3: Sign In with GitHub

  1. Open http://localhost:8080
  2. Click Sign in with GitHub
  3. GitHub redirects to the authorization page
  4. Authorize the OAuth App
  5. GitHub redirects back to ActionsManager

Using Both OAuth and PAT

You can use OAuth login AND save a Personal Access Token for API operations:

  • OAuth provides the browser login session
  • The saved PAT is used for GitHub API calls (workflow management, PR creation, etc.)
  • If a PAT is saved, it takes precedence over the OAuth token for API operations

See GitHub PAT Setup for PAT management.

Troubleshooting OAuth Issues

Redirect URI mismatch: The REACT_APP_BACKEND_URL environment variable must exactly match the Homepage URL registered in your GitHub OAuth App. Update both if you change deployment URLs.

OAuth App requires approval: Some GitHub organizations require OAuth Apps to be approved by an organization admin before members can authorize them.

Sign in button not appearing: Check that GITHUB_CLIENT_ID is set and the container was restarted after adding it.