GitHub App Authentication

Using the CCBR Bot for secure workflow authentication

Author

Kelly Sovacool

Overview

The CCBR Bot is a GitHub App that provides secure authentication for automated workflows without requiring personal access tokens. This approach offers better security, granular permissions, and easier token management for organization-wide automation.

Setting Up the CCBR Bot

An admin should install the app in the organization, then store each of these in your organization’s variables and secrets:

  • CCBR_BOT_CLIENT_ID (variable): The GitHub App Client ID
  • CCBR_BOT_PRIVATE_KEY (secret): The GitHub App private key

Using GitHub App Authentication in Workflows

When using actions that support GitHub App authentication, pass the Client ID and private key as inputs. CCBR composite actions also retain the legacy app-id input for compatibility.

with:
  client-id: ${{ vars.CCBR_BOT_CLIENT_ID }}
  app-private-key: ${{ secrets.CCBR_BOT_PRIVATE_KEY }}

Example Workflows

user-projects

Automatically add issues and pull requests to a user’s project board:

Source

name: personal-projects

on:
  issues:
    types:
      - assigned
  pull_request:
    types:
      - assigned

permissions:
  issues: write
  pull-requests: write

jobs:
  add-to-project:
    runs-on: ubuntu-latest
    steps:
      - uses: CCBR/actions/user-projects@latest
        with:
          client-id: ${{ vars.CCBR_BOT_CLIENT_ID }}
          app-private-key: ${{ secrets.CCBR_BOT_PRIVATE_KEY }}

Implementation Details

The user-projects action supports both authentication methods: provide a github-token directly, or provide client-id and app-private-key for on-demand generation. The legacy app-id input is also accepted. Here’s the relevant configuration:

inputs:
  github-token:
    description: "Pre-generated GitHub token. Optional - use client-id (or legacy app-id) and app-private-key instead."
    required: false
  client-id:
    description: "GitHub App Client ID for token generation."
    required: false
  app-id:
    description: "Legacy GitHub App ID input. Prefer client-id."
    required: false
  app-private-key:
    description: "GitHub App private key for token generation."
    required: false
  token-owner:
    description: "Owner of GitHub App resources (default: CCBR)"
    required: false
    default: "CCBR"

runs:
  using: composite
  steps:
    - name: Generate token from client ID
      if: ${{ inputs.github-token == '' && inputs.client-id != '' }}
      uses: actions/create-github-app-token@v3
      id: generate-token-client
      with:
        client-id: ${{ inputs.client-id }}
        private-key: ${{ inputs.app-private-key }}
        owner: ${{ inputs.token-owner }}

    - name: Generate token from legacy App ID
      if: ${{ inputs.github-token == '' && inputs.client-id == '' && inputs.app-id != '' }}
      uses: actions/create-github-app-token@v3
      id: generate-token-app
      with:
        app-id: ${{ inputs.app-id }}
        private-key: ${{ inputs.app-private-key }}
        owner: ${{ inputs.token-owner }}

    - name: Set GITHUB_TOKEN
      shell: bash
      run: |
        TOKEN=${{ inputs.github-token || steps.generate-token-client.outputs.token || steps.generate-token-app.outputs.token }}
        echo "GITHUB_TOKEN=$TOKEN" >> $GITHUB_ENV

Troubleshooting

  • Verify Client ID and private key are stored as organization variables/secrets
  • Ensure the GitHub App has required permissions configured
  • Check that the app is installed on the target repository/organization
  • Review workflow logs for errors from actions/create-github-app-token

Resources