Skip to content

Github

GitHub App Authentication Documentation

1. Register a GitHub App

To create a GitHub app, follow the instructions provided by GitHub:

  • Visit: Registering a GitHub App
  • Procedure:
  • Fill in the necessary details for your app.
  • Note the App ID provided after registration.
  • At the bottom of the registration page, click on Generate a private key. Download and securely store this key.

2. Store the Private Key

After generating your private key, you need to store it securely. If you are using Kubernetes, you can store it as a secret:

kubectl create secret generic github-app-pem --from-file=key=path/to/your/private-key.pem

3. Set Permissions for the GitHub App

Configure the necessary permissions for your GitHub app depending on what actions it needs to perform:

4. Install Your GitHub App

Install the GitHub app on your repository or organization to start using it:

5. Obtain an Installation ID

After installation, you need to get the installation ID to authenticate API requests:

Example Kubernetes Manifest for GitHub Access Token Generator

# 1. Register Github app https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app#registering-a-github-app
#   `App ID: 123456` will be displayed after you create an app. Next on the bottom of the page, you'll find `Generate a private key` button.
# 2. Get privateKey https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#generating-private-keys put it in e.g `github-app-pem` k8s secret
# 3. Set permissions for the app, e.g if you want to push OCI images to ghr set RW for packages https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app#choosing-permissions-for-rest-api-access
# 4. Install your Github app https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app
# 5. Get `installID` https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app#generating-an-installation-access-token (2)
---
apiVersion: generators.external-secrets.io/v1alpha1
kind: GithubAccessToken
metadata:
  name: github-auth-token
spec:
  appID: "0000000" # (1)
  installID: "00000000" # (5)
  url: "" # (Default https://api.github.com.)
  repositories: # Optional
    - "Hello-World"
  permissions: # Optional
    contents: read
  auth:
    privateKey:
      secretRef:
        name: github-app-pem # (2)
        key: key

---
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: github-auth-token
spec:
  refreshInterval: "30m"
  target:
    name: github-auth-token # Name for the secret to be created on the cluster
  dataFrom:
  - sourceRef:
      generatorRef:
        apiVersion: generators.external-secrets.io/v1alpha1
        kind: GithubAccessToken
        name: github-auth-token

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: github-auth-template
spec:
  dataFrom:
  - sourceRef:
      generatorRef:
        apiVersion: generators.external-secrets.io/v1alpha1
        kind: GithubAccessToken
        name: github-auth-token
  refreshInterval: "15m"
  target:
    template:
      metadata:
        annotations:
          tekton.dev/git-0: "https://github.com"
      type: kubernetes.io/basic-auth
      engineVersion: v2
      data:
        username: "token"
        password: "{{ .token }}"
    name: github-auth-template

Notes

  • Ensure that all sensitive data such as private keys and IDs are securely handled and stored.
  • Adjust the permissions and configurations according to your specific requirements and security policies.