diff --git a/docs/assets/gitstream-black.png b/docs/assets/gitstream-black.png
new file mode 100644
index 00000000..40d0b0e7
Binary files /dev/null and b/docs/assets/gitstream-black.png differ
diff --git a/docs/assets/gitstream-white.png b/docs/assets/gitstream-white.png
new file mode 100644
index 00000000..a27db46f
Binary files /dev/null and b/docs/assets/gitstream-white.png differ
diff --git a/docs/custom-github-app.md b/docs/custom-github-app.md
new file mode 100644
index 00000000..d4989821
--- /dev/null
+++ b/docs/custom-github-app.md
@@ -0,0 +1,115 @@
+---
+title: How to Setup Custom GitHub App and connect to gitStream services
+description: Install gitStream on your GitHub Server.
+---
+
+!!! Note
+
+ This guide is for installations on self-hosted GitHub Server. If you are using the gitStream cloud service, please refer to [this guide](github-installation.md).
+
+# Create GitHub App
+
+A GitHub application serves as the link between gitStream and GitHub. It facilitates user authentication via OAuth2 and allows users to select repositories accessible by gitStream.
+
+In this section, we'll guide you through creating a GitHub app for your self-hosted gitStream installation. By the end, you should have the following values noted down:
+
+* App ID
+* App URL
+* Client ID
+* Client secret
+* Private Key
+
+!!! Note
+
+ Throughout this document, when we refer to a GitHub account, it can be an individual or organization account on github.com or your own GitHub Enterprise installation, depending on the GitHub offering you are using.
+
+## Prerequisite
+
+1. Self-hosted GitHub Server
+2. Login, or create a free account on the LinearB app, and follow the steps to connect gitStream Using a GitLab Integration.
+3. Decide the endpoint at which you'll be running gitStream. It's typically `gitstream..com`. Your application won't be running there yet, but you need to know the endpoint you'll be using.
+
+!!! warning
+ For integrating with GitHub Enterprise Server (GHE), the top-level domain for gitStream must be the same as the top-level GHE domain. For example, if your GHE is running on `github.prod.company.com`, then gitStream should also run at a `.company.com` endpoint.
+
+## Create New App
+
+Any GitHub account can own the app, but we recommend creating it under the organization account of the team who will maintain the gitStream installation.
+
+- Log in to GitHub and go to your organization account page (e.g., `https://github.com/`).
+- Click on *Settings -> Developer Settings -> GitHub Apps -> New GitHub App* as shown below.
+- Or go directly to `https://github.com/organizations//settings/apps/new`
+
+
+
+## Setup URLs and General Information
+
+Fill in the app information as shown in the screenshot below. For URLs, replace `gitstream..com` with the actual endpoint at which you'll be hosting the gitStream application.
+
+!!! Warning
+ Do not forget trailing slashes for the URLs.
+
+!!! Warning
+ Do not forget to disable the "Expire user authorization tokens" checkbox.
+
+
+
+!!! Note
+ Use the webhook URL you got from the LinearB setup page.
+
+
+
+## Setup Permissions
+
+We need the following permissions to enable all gitStream functionality:
+
+- **Write access to dedicated gitStream app files:** Used to set up the gitStream workflow files
+- **Write access to code:** To allow gitStream to approve PRs once all conditions are met
+- **Read access to administration, issues, and metadata:** To get user team membership and branch protection settings
+- **Read and write access to actions, checks, pull requests, and workflows:** Trigger workflows, create and update pull requests and their checks, and modify workflow files
+- **User email:** Used to identify users |
+
+You need to enable these under the permissions section as shown below:
+
+
+
+
+
+
+## Webhook Events & Scope
+
+* Subscribe to events so gitStream is notified when a PR is created or changed, or being commented etc.
+
+
+
+
+!!! Note
+
+ *"Where can this GitHub App be installed?"* choose *"Any account"* so other orgs in your company can use gitStream as well. For on-prem installations that work with github.com, only repositories under your company's org account can be accessed via gitStream.
+
+
+
+## Generate Private Key
+
+Once the app is created, scroll down and click *Generate private key*. This will create and download a .pem file for you. Please keep this file safe.
+
+
+
+## Upload Logo
+
+Download the logo file and upload the logo to your app.
+
+- [Black logo](assets/gitstream-black.png)
+- [White logo](assets/gitstream-white.png)
+
+## Get App Config
+
+On your newly created app page, you can find the Client ID, Client Secret, App ID, and App URL. Please note down these fields along with the private key generated in the above step. We'll need to plug them back in LinearB setup.
+
+*Public link* is the App URL and *ID* is the App ID.
+
+
+
+## Finish Setup in LinearB
+
+To complete the integration, fill in the App ID and Private Key in the LinearB setup screen.
diff --git a/docs/screenshots/create-new-github-app-config.png b/docs/screenshots/create-new-github-app-config.png
new file mode 100644
index 00000000..9ed3f1e8
Binary files /dev/null and b/docs/screenshots/create-new-github-app-config.png differ
diff --git a/docs/screenshots/create-new-github-app-pkey.png b/docs/screenshots/create-new-github-app-pkey.png
new file mode 100644
index 00000000..3c9eb5f8
Binary files /dev/null and b/docs/screenshots/create-new-github-app-pkey.png differ
diff --git a/docs/screenshots/create-new-github-app-setup-permissions-1.png b/docs/screenshots/create-new-github-app-setup-permissions-1.png
new file mode 100644
index 00000000..98a48c66
Binary files /dev/null and b/docs/screenshots/create-new-github-app-setup-permissions-1.png differ
diff --git a/docs/screenshots/create-new-github-app-setup-permissions-2.png b/docs/screenshots/create-new-github-app-setup-permissions-2.png
new file mode 100644
index 00000000..1952189e
Binary files /dev/null and b/docs/screenshots/create-new-github-app-setup-permissions-2.png differ
diff --git a/docs/screenshots/create-new-github-app-setup-permissions-3.png b/docs/screenshots/create-new-github-app-setup-permissions-3.png
new file mode 100644
index 00000000..ad0435ed
Binary files /dev/null and b/docs/screenshots/create-new-github-app-setup-permissions-3.png differ
diff --git a/docs/screenshots/create-new-github-app-setup-permissions-4.png b/docs/screenshots/create-new-github-app-setup-permissions-4.png
new file mode 100644
index 00000000..b10c8c70
Binary files /dev/null and b/docs/screenshots/create-new-github-app-setup-permissions-4.png differ
diff --git a/docs/screenshots/create-new-github-app-setup-permissions-5.png b/docs/screenshots/create-new-github-app-setup-permissions-5.png
new file mode 100644
index 00000000..2e32ae32
Binary files /dev/null and b/docs/screenshots/create-new-github-app-setup-permissions-5.png differ
diff --git a/docs/screenshots/create-new-github-app-setup-permissions-6.png b/docs/screenshots/create-new-github-app-setup-permissions-6.png
new file mode 100644
index 00000000..d54b9a4e
Binary files /dev/null and b/docs/screenshots/create-new-github-app-setup-permissions-6.png differ
diff --git a/docs/screenshots/create-new-github-app-setup-permissions-7.png b/docs/screenshots/create-new-github-app-setup-permissions-7.png
new file mode 100644
index 00000000..be1491b1
Binary files /dev/null and b/docs/screenshots/create-new-github-app-setup-permissions-7.png differ
diff --git a/docs/screenshots/create-new-github-app-setup-post-installation.png b/docs/screenshots/create-new-github-app-setup-post-installation.png
new file mode 100644
index 00000000..065f0d8a
Binary files /dev/null and b/docs/screenshots/create-new-github-app-setup-post-installation.png differ
diff --git a/docs/screenshots/create-new-github-app-setup-register.png b/docs/screenshots/create-new-github-app-setup-register.png
new file mode 100644
index 00000000..181d4602
Binary files /dev/null and b/docs/screenshots/create-new-github-app-setup-register.png differ
diff --git a/docs/screenshots/create-new-github-app.png b/docs/screenshots/create-new-github-app.png
new file mode 100644
index 00000000..97dfc30e
Binary files /dev/null and b/docs/screenshots/create-new-github-app.png differ
diff --git a/mkdocs.yml b/mkdocs.yml
index c056e51d..d2d4a942 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -11,6 +11,7 @@ nav:
- Guide:
- GitHub Setup: github-installation.md
- GitLab Setup: gitlab-installation.md
+ - Custom GitHub App: custom-github-app.md
- How gitStream works: how-it-works.md
- Your First Automation: quick-start.md
- How to Test Your Automations: dry-run-mode.md
@@ -23,22 +24,22 @@ nav:
- Context variables: context-variables.md
- Filter functions: filter-functions.md
- Automation actions: automation-actions.md
- - Plugins:
+ - Plugins:
- Overview: plugins.md
- Filter Functions: filter-function-plugins.md
- Playground: gitStream-playground.md
- Troubleshooting: troubleshooting.md
- FAQ: faq.md
- - Login: https://app.gitstream.cm/login
+ - Login: https://app.gitstream.cm/login
theme:
name: material
logo: assets/gitstream-w.webp
icon:
repo: fontawesome/brands/github
- # When the user first visits your site, the media queries are evaluated in the order
+ # When the user first visits your site, the media queries are evaluated in the order
# of their definition. The first media query that matches selects the default color palette.
- palette:
+ palette:
- media: "(prefers-color-scheme: light)"
scheme: default
toggle:
@@ -97,7 +98,7 @@ markdown_extensions:
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
- alternate_style: true
+ alternate_style: true
extra:
analytics:
provider: google