Configure a GitHub App for CI/CD

Configure a GitHub App for CI/CD (se-ci-cd-app)

This guide shows how to create a new GitHub App named se-ci-cd-app in your GitHub Organization and configure it for CI/CD access to private repositories (service repo, shared repo, and centralized CI actions repo) using short-lived GitHub App tokens.

🧩 Inputs

GitHub Organization

GitHub App Name

Homepage URL

Shared Repo (common modules)

Central CI Actions Repo

Service Repo (example)

App ID Secret Name

Private Key Secret Name

Computed App ID Secret:

SE_CI_APP_ID

Computed Private Key Secret:

SE_CI_APP_PRIVATE_KEY

Example repos your token must access:

- ShelveraApp/se-gw-srvc
- ShelveraApp/se
- ShelveraApp/se-ci-actions

GitHub Apps navigation:

Settings → Developer settings → GitHub Apps

What this GitHub App will be used for

Your CI/CD workflow will use this GitHub App to:

Generate a short-lived token at runtime
Checkout multiple private repositories (example: service repo + se + se-ci-actions)
Avoid long-lived PATs (more secure)

Before you start

You will need:

Organization owner access for ShelveraApp
A list of repos the workflow must read (example):
- se
- se-ci-actions
- Your service repo(s) (ex: se-gw-srvc, ts-data-srvc-002, etc.)
A safe place to store the downloaded private key (.pem)

Navigate to GitHub Apps creation

Go to GitHub and open your organization: ShelveraApp

Navigate to:

Settings → Developer settings → GitHub Apps

Click:
```
New GitHub App
```

Fill in the GitHub App identity fields

On the “Create a new GitHub App” page, set:

GitHub App name

se-ci-cd-app

Homepage URL

https://shelvera.com

Notes:
- You do not need a Callback URL for CI/CD-only usage.
- You do not need a Setup URL for CI/CD-only usage.

Skip user authorization and device flow options

In the Identifying and authorizing users section:

Leave Callback URL empty
Leave Request user authorization (OAuth) during installation unchecked
Leave Enable Device Flow unchecked

CI/CD token generation does not require end-user OAuth flows.

Keep Webhooks disabled

In the Webhook section:

Leave Active unchecked
Leave Webhook URL empty
Leave Secret empty

Webhooks are not required for your CI/CD checkout/token flow.

Set the required permissions

Scroll to Permissions and configure both Repository permissions and Organization permissions.

Repository permissions

Administration: Read and write
Contents: Read-only
Metadata: Read-only

Organization permissions

Self-hosted runners: Read and write

Contents — Read-only allows actions/checkout@v4 to clone private repositories.
Administration — Read and write is required for repository-scoped ARC to create a runner registration token.
Self-hosted runners — Read and write is required for organization-level runner registration and ARC runner management.
If either runner permission is missing, the GitHub App can still authenticate and see the repository, but ARC registration can fail with 403 Resource not accessible by integration.

Create the GitHub App

Scroll to the bottom and click:

Create GitHub App

After the app is created, you will be taken to the app’s settings page.

Record the GitHub App ID (needed by CI/CD)

On the GitHub App settings page, locate the App ID. Save it for later as:

SE_CI_APP_ID

You will store this value as a GitHub Actions Secret in each repo that runs the workflow.

Generate a private key for the App

On the GitHub App settings page, find the Private keys section.

Click:
```
Generate a private key
```
A .pem file downloads immediately.
Store this file securely.
Open the .pem file and copy the full contents (including header/footer):
```
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
```

You will store this PEM content as a GitHub Actions Secret:

SE_CI_APP_PRIVATE_KEY

Install App and select required repositories

Install the GitHub App into your organization and select only the repositories required for CI/CD.

On the GitHub App page, click Install App.
Choose Only select repositories.
Select the required repositories:
- se-gw-srvc
- se
- se-ci-actions
Click Install.

Keep repo access minimal. Add more repositories later only when a workflow truly needs them.

Approve updated permissions for an existing installation

If the GitHub App was already installed before you added or changed any permissions, an organization owner must approve the updated permission request before the installation token receives those permissions.

Open the organization:

ShelveraApp → Settings → GitHub Apps → Installed GitHub Apps

Select se-ci-cd-app, then click Configure.
Look for an action such as Review request, Approve new permissions, or Accept new permissions. The exact wording can vary.
Approve the request and confirm the required repositories, including se-gw-srvc, remain selected.

No approval step is normally shown when the required permissions were configured before the first installation. After approval, generate a fresh installation token; existing tokens do not gain the new permissions retroactively.

10.

Add secrets to each repo that runs CI/CD

For each repo that uses the workflow (example: se-gw-srvc):

Open the repo → Settings
Go to:
```
Secrets and variables → Actions
```
Create these Repository Secrets:

Secret: SE_CI_APP_ID

Value: the GitHub App App ID (numeric)

Secret: SE_CI_APP_PRIVATE_KEY

Value: the full PEM contents of the private key

11.

Validate in your workflow

Your workflow should include a step like:

actions/create-github-app-token@v2
- Uses SE_CI_APP_ID and SE_CI_APP_PRIVATE_KEY
- Requests tokens for the specific repos needed (service repo + shared repo + ci actions repo)

Example (token + checkout):

- name: Create GitHub App token
  id: app-token
  uses: actions/create-github-app-token@v2
  with:
    app-id: ${{ secrets.SE_CI_APP_ID }}
    private-key: ${{ secrets.SE_CI_APP_PRIVATE_KEY }}
    owner: ShelveraApp
    repositories: se-gw-srvc,se,se-ci-actions

- name: Checkout centralized CI actions repo
  uses: actions/checkout@v4
  with:
    repository: ShelveraApp/se-ci-actions
    ref: main
    path: .ci-actions
    token: ${{ steps.app-token.outputs.token }}

✅ Success criteria:

GitHub App token is generated successfully
All required private repos checkout successfully
Your build context and Docker build steps can see both service code and shared modules

Optional hardening (recommended)

Rotate the private key periodically (generate a new key and update the secret)
Keep permissions minimal (Contents read-only unless you truly need more)
Keep repo access restricted to only repos you need (least privilege)
Avoid adding other organization-wide permissions; Self-hosted runners — Read and write is required for ARC