Private Repository (GitHub App)

Deploy GitHub repos via a GitHub App — one auth surface, many repos.

Application #git#github#app#private#repository

Deploy private (and public) GitHub repositories using a GitHub App you own. Install the app on your org or selected repos, paste the app credentials into Pier, and clone / build / deploy any of those repos without per-repo deploy keys. The recommended auth method for teams deploying many private repos to one Pier instance.

Deploy with Pier

1 Open the Pier dashboard and click Add service.
2 Pick Private Repository (GitHub App) from the template list.
3 Choose the version, set a service name, and Pier provisions the container, storage, and ports automatically.
4 Attach a domain if you want HTTPS. Traefik auto-provisions the Let's Encrypt certificate.

What is the GitHub App template?

Deploy GitHub repositories (private or public) using a GitHub App you control. You create the app under your account or org, install it on specific repos (or org-wide), download its private key, and paste the credentials into Pier. Pier uses the GitHub API to request short-lived installation access tokens at clone time — no long-lived PATs, no per-repo deploy keys.

This is the recommended auth pattern for teams deploying many private repos to one Pier instance. One app authorizes any number of repos; revocation is per-install or per-repo; the audit trail lives on the GitHub side.

How Pier deploys it

You provide:

A Git URL (HTTPS) for the target repo
The GitHub App’s App ID, Installation ID, and private key (.pem)
Branch / tag / commit, Dockerfile path, port, env vars

At clone time, Pier signs a JWT with the app’s private key, requests an installation access token from the GitHub API, and uses that token to git clone over HTTPS. Tokens expire in ~1 hour and Pier refreshes them automatically.

For webhook-driven push-to-deploy, configure the app’s webhook URL to point at the Pier-generated webhook URL for the service, set a webhook secret, and Pier verifies and acts on push events.

When NOT to use this template

For 1-5 private repos under personal accounts, the simpler Deploy Key template (per-repo SSH key) is easier. For public repos, the Public Repository template needs no auth at all. For non-GitHub hosts (GitLab, Bitbucket, Gitea, …), use Deploy Key. GitHub App is the right answer specifically for “team / org with many GitHub private repos and we want one auth surface.”

Key features

One app, many repos

Install the GitHub App on your org or per-repo. Pier uses the app's installation token to clone any authorized repo — no per-repo deploy keys.

Org-level or repo-level scope

Install on the whole org (all current and future repos) or pick specific repos. Revoke per-repo or per-org at any time.

Auto-rotating tokens

GitHub Apps generate short-lived installation access tokens. Pier requests fresh tokens automatically; nothing long-lived to leak.

Fine-grained permissions

The app declares exactly what it needs (Contents — read). No access to Actions, secrets, organization billing, or anything else.

Webhook redeploys included

GitHub Apps can subscribe to push events at install time. Configure once; pushes auto-trigger Pier redeploys.

Audit trail

Every clone is logged on the GitHub side as an app installation event — useful for security audits.

Use cases

Org with many private repos

Your org has dozens of private repos and you don't want per-repo deploy keys for each. Install one GitHub App, deploy any repo via Pier.

Polyglot monorepo decomposition

A single Pier instance hosting N services from N separate private repos — all authorized via one app.

Continuous deploy for product teams

Each team's repo is auto-deployed on push to main, all authenticated via the same org-scoped app.

Audit-conscious deployments

Compliance / security teams prefer a single, audited app with a per-repo scope over a sea of long-lived SSH keys.

Replacing PATs

Personal Access Tokens grant repo-wide access tied to a human account. Apps are repo-scoped, machine-owned, short-lived tokens — strictly better.

Code examples

Create a GitHub App text

GitHub → Settings → Developer settings → GitHub Apps → New GitHub App
  Name: pier-deployments
  Homepage URL: https://pier.example.com
  Webhook: (we'll set this up via Pier later; leave blank for now)
  Permissions:
    Contents: Read-only
    Metadata: Read-only
  Subscribe to events: Push
→ Create
→ Generate a private key (download .pem)
→ Note the App ID and Client ID

Install the app on your org / repos text

App settings → Install App → Pick your org
→ Choose: "All repositories" or "Only selected repositories"
→ Install
→ Note the Installation ID (from URL: https://github.com/settings/installations/<ID>)

Connect to Pier text

Pier → New service → Private Repository (GitHub App)
  Git URL: https://github.com/myorg/myrepo
  Branch: main
  App ID: 12345
  Installation ID: 67890
  Private Key: (paste contents of the .pem you downloaded)
  Dockerfile path: /Dockerfile
  Port: 3000
→ Deploy

Set up webhook-driven deploys text

Pier service → Settings → Copy webhook URL
GitHub App → settings → Webhook URL: paste it.
Webhook secret: (Pier shows one to copy in)
→ Save
→ Push to main → auto-rebuild + redeploy

How it compares

vs Deploy Key template (this catalog)	Deploy Keys are simpler for 1-5 private repos. GitHub Apps scale better at 10+ private repos under one org. Apps also have audit trails and short-lived tokens.
vs Personal Access Token (PAT)	PATs are tied to a human account and grant access to ALL their repos. Apps are scoped to specific repos and owned by your org/account separately. Apps are strictly better security.
vs GitLab / Bitbucket / Gitea	This template is GitHub-specific. For GitLab use deploy tokens; for Bitbucket use OAuth apps; for Gitea use deploy keys.
vs Public Repository (this catalog)	Public works without any auth — use it when the repo is genuinely public.

Frequently asked questions

Why is this better than a PAT?

PATs are tied to a human account, grant broad access, and expire infrequently. GitHub App installation tokens are scoped to specific repos, owned by the app (not a person), and auto-rotated.

Where does the private key live in Pier?

Encrypted in Pier's database, decrypted at request time to sign JWTs for the GitHub App API. The key itself never leaves Pier.

Can I use one app for multiple Pier services?

Yes — that's the design. One app authorizes many repos; create one Pier service per repo, all referencing the same app credentials.

What permissions does the app need?

Contents — Read-only and Metadata — Read-only is enough to clone. Subscribe to Push events for webhook redeploys.

How are webhook signatures verified?

Pier verifies the webhook secret you configured on the GitHub App. Reject any webhook without a valid signature.

Can I deploy public repos with this template?

Yes — once the app is installed, it can clone any authorized repo, public or private.

Token expiration / refresh?

Installation tokens expire in ~1 hour. Pier requests fresh ones from the GitHub API before each clone. You don't manage this.

Related services

Deploy on your VPS

Deploy this service →