Skip to main content

GitHub Actions

PlatformWorks Hub uses GitHub Actions as orchestration provider to run workflows for actions. To enable this, you must register a GitHub App and provide the necessary credentials via environment variables.

🌍 Required Environment Variables​

VariableDescription
HUB_PROVIDERS_GITHUB_APP_IDGitHub App ID
HUB_PROVIDERS_GITHUB_INSTALLATION_IDGitHub App Installation ID
HUB_PROVIDERS_GITHUB_PRIVATE_KEYBase64-encoded GitHub App private key
HUB_PROVIDERS_GITHUB_BASE_URLGitHub API URL (e.g. https://api.github.com)

🛠️ GitHub App Setup (One-time)​

  1. Go to GitHub Developer Settings
  2. Click "New GitHub App"
  3. Fill in the required details:
    • GitHub App name: Hub App (or any name)
    • Homepage URL: https://your-domain.com
      (replace with your actual deployment domain)
    • Callback URL: (leave blank)
    • Webhook URL: 
      https://your-domain.com/api/github/webhook
    • Repository permissions:
      • Actions: Read & write
      • Contents: Read & write
      • Metadata: Read-only
      • Workflows: Read & write
    • Subscribe to events:
      • workflow_run
      • workflow_job
    • Where can this GitHub App be installed?
      • Select Only on this account
  4. After creation:
    • Generate a private key (you will receive a .pem file)
    • Copy the App ID
    • Install the GitHub App into your organization or user account

🆔 How to Get the Installation ID​

  1. Install the GitHub App into your organization or user account
  2. After installation, you'll be redirected to a URL like:
https://github.com/organizations/<your-org>/settings/installations/<installation-id>
  1. The number at the end is your Installation ID — use it as:
HUB_PROVIDERS_GITHUB_INSTALLATION_ID=<your-installation-id>

🔐 Convert the Private Key​

GitHub provides the private key as a multiline .pem file. It must be converted to a base64-encoded, single-line string before setting it as an environment variable.

You can use the following script:

convert-github-key.sh​

#!/bin/bash

set -e

# Usage: ./convert-github-key.sh input.pem [output-file]

if [ "$#" -lt 1 ]; then
  echo "Usage: $0 <input-pem-file> [output-file]"
  exit 1
fi

INPUT_PEM="$1"
OUTPUT_FILE="$2"
TMP_DER_FILE=$(mktemp)

# Step 1: Convert PEM to DER (PKCS#8)
openssl pkcs8 -topk8 -inform PEM -outform DER -in "$INPUT_PEM" -out "$TMP_DER_FILE" -nocrypt

# Step 2: Base64 encode without line breaks
BASE64_STRING=$(base64 "$TMP_DER_FILE" | tr -d '\n')

if [ -z "$OUTPUT_FILE" ]; then
  echo "$BASE64_STRING"
else
  echo "$BASE64_STRING" > "$OUTPUT_FILE"
  echo "Base64-encoded private key (no line breaks) saved to: $OUTPUT_FILE"
fi

rm -f "$TMP_DER_FILE"

How to use:​

chmod +x convert-github-key.sh
./convert-github-key.sh ./private-key.pem

Copy the output and use it as:

HUB_PROVIDERS_GITHUB_PRIVATE_KEY=<base64-encoded-private-key>