Connecting GitHub as a CI/CD provider

This section deals with setting up a GitHub App which is required for sfp-pro server to integrate with your GitHub org

sfp server requires additional permissions which allow it to write into your repository, sync environments, and trigger workflows.

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 sfp-server GitHub App to integrate with sfp-server. 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 sfp server GitHub App

• Navigate to your GitHub organization's settings.

• Click on "Developer settings" and select "GitHub Apps".

• Hit "New GitHub App" and input codev as the name.

• Add an icon and background color in the 'Display Information' to make the app identifiable in your workflows

Step 2: Permissions Configuration

• Assign the app permissions based on the requirements for codev:

Repository Permissions

• Contents: Set to read and write for the app to manage code, branches, commits, and merges. This access allows the app to automate code integration processes.

• Issues: Read and write permissions enable the app to automate issue tracking, commenting, and labeling.

• Checks: Read and write permissions to create CI/CD Checks

• Commit statuses : Read and write permissions to create CI/CD Checks

• Pull Requests: Read and write permissions are necessary for the app to automate the handling of pull requests, including merging and labeling.

• Webhooks: Readn and write permission to automatically create webhooks for integrating GitHub events with Server

Step 3: Generate and Secure a Private Key

• In the 'General' section of your app's settings, locate the 'Private keys' subsection.

• Click on "Generate a private key" and download the .pem file immediately to your secure location.

Step 4: Installation of the App

• Navigate to the 'Install App' tab within your app settings.

• Click "Install" to initiate the installation process.

• Select your organization and choose to install the app on all repositories or specific ones such as Salesforce repositories

Step 5: Storing the Private Key and App ID as Secrets

• Store these keys in your secrets provider or in the .env file under GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY

You would also need to configure a GITHUB_TOKEN env variable, which has the following scope, packages:write and repo:read This is due to the fact the GITHUB Apps currently do not support operations on GitHub packages.