Question: need to store credentials?

[bwalsh]

ADR 0002: Repository Access via GitHub App Installation Tokens

Status

Discussion

Context

The platform must read repository contents in order to:

• clone repositories
• inspect source code
• validate pull requests
• launch workflows
• compute status checks
• perform deployment automation

A design decision is required regarding how the platform authenticates to GitHub repositories.

Potential approaches include:

1. User credentials (username/password)
2. Personal Access Tokens (PATs)
3. OAuth user tokens
4. GitHub App installation tokens

The platform is intended to be multi-tenant and must minimize credential management, privilege escalation risk, and operational burden.

---

Decision

The platform SHALL access repositories using GitHub App installation access tokens.

The platform SHALL NOT require individual user credentials, personal access tokens, or OAuth user access tokens for normal repository operations.

Repository access will be granted by installing the GitHub App into an organization or repository.

The platform will:

1. Generate a GitHub App JWT using the App private key.

2. Exchange the JWT for an installation access token.

3. Use the installation access token to:

   • read repository contents
   • clone repositories
   • access pull request metadata
   • create checks
   • update commit statuses
   • perform workflow-related GitHub API operations

The installation token represents the permissions granted to the GitHub App installation and is independent of any individual user account.

---

Rationale

GitHub Apps provide a server-to-server authentication model.

Repository access is authorized through the installation of the GitHub App rather than through an individual user's credentials.

This provides several advantages:

Security

• No storage of user passwords.
• No storage of personal access tokens.
• Fine-grained repository permissions.
• Short-lived installation tokens.
• Independent credential rotation.

Multi-Tenancy

• Installation tokens are scoped to a specific GitHub installation.
• Different tenants may use different installations.
• Access boundaries are enforced by GitHub.

Operational Simplicity

• Users only install the App.
• No user login flow required.
• No token copy/paste workflow.
• No PAT lifecycle management.

Auditability

GitHub records:

• App installation events
• Permission grants
• App-generated actions

allowing administrators to audit platform access independently from user actions.

---

Consequences

Positive

• No user credentials required.
• No PAT management.
• Least-privilege repository access.
• Short-lived credentials.
• Simplified onboarding.
• Strong compatibility with multi-tenant architecture.

Negative

• GitHub App must be installed before repository access is possible.
• Additional implementation complexity around JWT generation and token exchange.
• Installation token caching and renewal must be implemented.

---

Authentication Flow

sequenceDiagram
    participant Platform
    participant GitHub

    Platform->>GitHub: Create JWT signed with App private key
    GitHub-->>Platform: JWT accepted

    Platform->>GitHub: Request installation token
    GitHub-->>Platform: Installation Access Token

    Platform->>GitHub: Clone repository / call APIs
    GitHub-->>Platform: Repository data

Loading

---

Authorization Model

GitHub App
    │
    ├── Installation A
    │      ├── Repository 1
    │      └── Repository 2
    │
    └── Installation B
           ├── Repository 3
           └── Repository 4

The platform resolves:

(installation_id, repository_id)

to determine tenant ownership and authorization.

---

Alternatives Considered

Personal Access Tokens

Rejected because:

• tied to individual users
• difficult rotation lifecycle
• excessive permissions
• poor multi-tenant isolation

OAuth User Tokens

Rejected because:

• requires user login flow
• permissions tied to users
• unsuitable for server-side automation

Shared Service Account

Rejected because:

• difficult auditing
• broad permissions
• weak tenant isolation

---

References

GitHub documentation states that installation access tokens may be used for server-to-server API access and repository access, including cloning repositories over HTTPS.

Repository access is granted through App installation permissions and does not require individual user credentials.

Therefore, a properly configured GitHub App can read repository contents without requiring a user's GitHub username, password, personal access token, or OAuth credentials.

[bwalsh]

Recommended Reading Order for a Multi-Tenant GitHub App

GitHub Fundamentals

1. [GitHub Apps Overview](https://docs.github.com/en/apps/overview?utm_source=chatgpt.com)
2. [Creating GitHub Apps](https://docs.github.com/en/apps/creating-github-apps?utm_source=chatgpt.com)
3. [GitHub App Best Practices](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app?utm_source=chatgpt.com)

Authentication (Must Read)

4. [Authenticating as a GitHub App Installation](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation?utm_source=chatgpt.com)
5. [Choosing GitHub App Permissions](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app?utm_source=chatgpt.com)

Key takeaway: Repository access is granted via installation tokens, not user credentials.

---

Webhooks

6. [Webhook Validation](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries?utm_source=chatgpt.com)
7. [Webhook Events and Payloads](https://docs.github.com/en/webhooks/webhook-events-and-payloads?utm_source=chatgpt.com)

Focus on:

• push
• pull_request
• installation
• installation_repositories

---

Status Reporting

8. [Checks API](https://docs.github.com/en/rest/checks?utm_source=chatgpt.com)
9. [Commit Status API](https://docs.github.com/en/rest/commits/statuses?utm_source=chatgpt.com)

---

Go Libraries

10. [go-github](https://github.com/google/go-github?utm_source=chatgpt.com)
11. [ghinstallation](https://github.com/bradleyfalzon/ghinstallation?utm_source=chatgpt.com)
12. [go-githubapp](https://github.com/palantir/go-githubapp?utm_source=chatgpt.com)

---

Reference Implementations

13. [Actions Runner Controller](https://github.com/actions/actions-runner-controller?utm_source=chatgpt.com)
14. [Renovate Bot](https://github.com/renovatebot/renovate?utm_source=chatgpt.com)

---

[matthewpeterkort]

this is not an issue. Mostly just docs.