Skip to main content

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

This guide shows how to create a new GitHub App named ts-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.

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 + ts-002 + ts-ci-actions)
  • Avoid long-lived PATs (more secure)

Before you start​

You will need:

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

Step 1 — Navigate to GitHub Apps creation​

  1. Go to GitHub and open your organization: ts-001-org
  2. Navigate to:
Settings → Developer settings → GitHub Apps
  1. Click:
New GitHub App

Step 2 — Fill in the GitHub App identity fields​

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

  1. GitHub App name
ts-ci-cd-app
  1. Homepage URL
    Use your site URL (example):
https://tidyshelves.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.

Step 3 — 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.

Step 4 — 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.

Step 5 — Set the minimum required permissions​

Scroll to Permissions and configure Repository permissions.

Set:

Repository permissions​

  • Contents: Read-only

That’s the minimum required for:

  • actions/checkout@v4 to clone private repos using the GitHub App token

If you later decide the app must do more than checkout (rare), you can add permissions then. Start minimal.

Step 6 — 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.

Step 7 — Record the GitHub App ID (needed by CI/CD)​

On the GitHub App settings page, locate the App ID.

Save it for later as:

TS_CI_APP_ID

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

Step 8 — Generate a private key for the App​

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

  1. Click:
Generate a private key
  1. A .pem file downloads immediately.
  2. Store this file securely.
  3. 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:

TS_CI_APP_PRIVATE_KEY

Step 9 — Set repository access to least privilege (recommended)​

When choosing which repositories the GitHub App can access, use the least-privilege model:

  • Choose Only select repositories
  • Select only the repos your workflow needs, for example:
    • ts-002
    • ts-ci-actions
    • ts-gw-srvc-002
    • ts-data-srvc-002 (when you add it)

This keeps the blast radius small. You can add more repos later as new services are introduced.

Step 10 — Add secrets to each repo that runs CI/CD​

For each repo that uses the workflow (example: ts-gw-srvc-002, ts-data-srvc-002):

  1. Open the repo → Settings
  2. Go to:
Secrets and variables → Actions
  1. Create these Repository Secrets:

Secret: TS_CI_APP_ID​

  • Value: the GitHub App App ID

Secret: TS_CI_APP_PRIVATE_KEY​

  • Value: the full PEM contents of the private key

Step 11 — Validate in your workflow​

Your workflow should include a step like:

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

Then actions/checkout@v4 should succeed using the generated 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
  • Rotate the private key periodically (generate a new key and update the TS_CI_APP_PRIVATE_KEY 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 org-wide permissions unless required