> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp-server/setting-up/connecting-github-as-a-ci-cd-provider.md).

# Connecting GitHub as a CI/CD provider

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

{% hint style="info" %}
This **GitHub App** is the **automation identity** for repository operations and webhooks. It is **separate** from the GitHub **OAuth App** used to log users in (see [Setting up sfp server → \[6\] Configure login](/flxbl/sfp-server/setting-up/setting-up-sfp-server.md#6-configure-login)). A typical setup has both: a login provider for users, and this GitHub App for CI/CD. On **Azure DevOps**, the equivalent automation identity is a **service principal**. You connect either one **after the server is up**, in **Settings → Integrations** — see [Setting up sfp server → \[5\] Configure your git provider](/flxbl/sfp-server/setting-up/setting-up-sfp-server.md#5-configure-your-git-provider).
{% endhint %}

{% hint style="info" %}
**Automation vs. user attribution.** The App is the actor for machine-driven work — cloning, checks, statuses, webhook creation. Actions that should be traceable to a person — opening a release issue, or raising a PR on a user's behalf through IssueOps — run under that **signed-in user's OAuth token**, so they appear under the user's name, not the App's. The user OAuth token comes from the login provider, not from this App.
{% endhint %}

These permissions are beyond what GitHub Actions' default `GITHUB_TOKEN` provides, which is why sfp-server uses a dedicated GitHub App.

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 <a href="#step-by-step-creation-and-configuration" id="step-by-step-creation-and-configuration"></a>

#### **Step 1: Registration of sfp server GitHub App** <a href="#step-1-registration-of-sfops-bot-github-app" id="step-1-registration-of-sfops-bot-github-app"></a>

* 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** <a href="#step-2-permissions-configuration" id="step-2-permissions-configuration"></a>

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

**Repository Permissions**

* **Contents**: Read and write — manage code, branches, commits, and merges; clone repositories.
* **Issues**: Read and write — automate issue tracking, commenting, and labeling.
* **Checks**: Read and write — create and update CI/CD check runs.
* **Commit statuses**: Read and write — set commit status for CI/CD.
* **Pull Requests**: Read and write — automate handling of pull requests, including merging, labeling, reviews, and comments.
* **Webhooks**: Read and write — automatically create, update, and delete webhooks that integrate GitHub events with the server.
* **Members**: Read-only — resolve team members for environment approvers.
* **Metadata**: Read-only — mandatory baseline access (installations, user and team lookups).

**Subscribe to events**

* Subscribe the app to: `push`, `pull_request`, `pull_request_review`, `pull_request_review_comment`, `issues`, `issue_comment`.

**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** <a href="#step-4-installation-of-the-app" id="step-4-installation-of-the-app"></a>

* 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: Enter the App ID and Private Key in codev** <a href="#step-5-enter-the-app-id-and-private-key-in-codev" id="step-5-enter-the-app-id-and-private-key-in-codev"></a>

* Keep the **App ID** and the downloaded **private key** (`.pem`) from Steps 1 and 3 to hand.
* You enter them in the **codev onboarding wizard** after first login — its integration step stores them encrypted at rest. They are not set at `sfp server init`.
* GitHub.com (cloud) users skip the manual App entirely: codev installs the prebuilt `flxbl-cloud` app via **Install GitHub App** during onboarding. The manual App above is for **GitHub Enterprise Server**.

{% hint style="warning" %}
If your pipelines publish or consume **GitHub Packages** (npm), you must also configure a `GITHUB_TOKEN` env variable — a token with `read:packages` and `write:packages` scope.

This is required because GitHub Apps currently cannot operate on GitHub Packages; the server uses this token only to authenticate against `npm.pkg.github.com`. If you do not use GitHub Packages, this token is not needed.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp-server/setting-up/connecting-github-as-a-ci-cd-provider.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.