2. Create a GitHub App

This section deals with setting up a GitHub App which is required for sfops to function. sfops require additional permissions which allow to write into other repository such as 'sfops-dev-central' and also permission to trigger workflows etc. These permissions are beyond what is being provided by the built in GITHUB_TOKEN. A Github App is recommended over using a Service Account and its Personal Access Token, as the service account takes an additional license and has limitations on the api requests.

This guide is crafted to facilitate the user to create a sfops-bot GitHub App to automate the worflows provided out of the box with sfops. It provides a step-by-step approach for creating the app, elaborating on the necessary permissions, installation, and secure storage of sensitive information.

You can refer to this link to understand how this work behind the scenes

https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow#authenticating-with-a-github-app\

Step-by-Step Creation and Configuration

Step 1: Registration of sfops-bot GitHub App

• Navigate to: GitHub org → Settings → Developer settings → GitHub Apps → New GitHub App
  • Direct URL: https://github.com/organizations/YOUR_ORG/settings/apps/new
• Configure the app:
  • GitHub App name: sfops-bot
  • Homepage URL: https://github.com/YOUR_ORG/sfops (or your organization URL)
  • Webhook: Uncheck "Active" (webhooks are not needed for sfops-bot)
• Add an icon and background color in the 'Display Information' to make the app identifiable in your workflows

Step 2: Permissions Configuration

Configure the following permissions for the sfops-bot app:

Repository Permissions

Organization Permissions

Step 3: Configure Installation Settings

• In the Where can this GitHub App be installed? section:
  • Select "Only on this account" to restrict the app to your organization
  • This ensures the app can only be installed within your organization

Step 4: Create the GitHub App

• Click "Create GitHub App" at the bottom of the form
• You'll be redirected to your new app's settings page
• Keep this tab open - you'll need information from this page in Step 6

Step 5: Install the App

• Navigate to the 'Install App' tab within your app settings
• Click "Install" to initiate the installation process
• Select your organization and choose either:
  • All repositories (recommended for simplicity), or
  • Selected repositories: Include at minimum:
    • sfops
    • sfops-gh-actions
    • sfops-dev-central
    • Your Salesforce project repositories

Step 6: Collect App Credentials and Store as Secrets

Collect the required credentials (from Step 4's settings page):

1. App ID: Note the App ID displayed at the top of your app's settings page
2. Private Key:
   • Scroll down to the Private keys section on your app's settings page
   • Click "Generate a private key"
   • The .pem file will download automatically - save it securely

Store as GitHub secrets:

• Navigate to your sfops repository → Settings → Secrets and variables → Actions
• Create the following:
  • SFOPSBOT_APP_ID: Paste the App ID number from the settings page (store as Repository variable)
  • SFOPSBOT_APP_PRIVATE_KEY: Paste the entire contents of the downloaded .pem file (store as Repository secret)

The workflows provided by sfops utilizes the above variables to authenticated to do repository operations as provided in the below example\

// Sample code demonstrating how the token is used
      - name: Generate a token
        id: generate_token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ var.SFOPSBOT_APP_ID }}
          private-key: ${{ secrets.SFOPSBOT_APP_PRIVATE_KEY }}

      - name: Use the token
        env:
          GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
        run: |
          gh workflow <>

Troubleshooting

Error: Failed to create Environment - Resource not accessible by integration

You see this error in your workflow logs:

Error: Failed to create Environment due to Resource not accessible by integration
https://docs.github.com/rest/deployments/environments#create-or-update-an-environment

About this error

The GitHub App token lacks permission to create environments via the REST API. This occurs when the IssueOps request-an-env operation runs.

Confirming the cause

Check which scenario applies to your setup:

1. Missing Administration permission (most common): The GitHub API requires administration: write to create environments—the environments permission alone is insufficient. Check your app permissions at:

   https://github.com/organizations/YOUR_ORG/settings/apps/sfops-bot

   Look for Administration under Repository permissions.

2. Pending permission acceptance: Permissions were added to the app but not yet accepted at the installation level. Check for a yellow banner at:

   https://github.com/YOUR_ORG/YOUR_REPO/settings/installations

3. Repository not in installation scope: If the app is installed on "Selected repositories", verify your repository is included in the list.

Fixing the problem

If Administration permission is missing:

1. Go to https://github.com/organizations/YOUR_ORG/settings/apps/sfops-bot
2. Click Permissions & events
3. Under Repository permissions → Set Administration to Read and write
4. Click Save changes
5. Accept the new permission at https://github.com/YOUR_ORG/YOUR_REPO/settings/installations
6. Re-run the failed workflow

If permissions are pending acceptance:

1. Go to https://github.com/YOUR_ORG/YOUR_REPO/settings/installations
2. Click Configure next to sfops-bot
3. Accept the pending permission request
4. Re-run the failed workflow

If repository is not in installation scope:

1. Go to https://github.com/organizations/YOUR_ORG/settings/installations
2. Click Configure next to sfops-bot
3. Add your repository to the selected list, or switch to All repositories
4. Re-run the failed workflow