Skip to main content

GitHub Integration

The GitHub integration enables AstroPulse to access private repositories for application deployments. This is required when your Helm charts, Kubernetes manifests, or application source code are stored in private GitHub repositories.

How It Works​

AstroPulse uses a GitHub App model for repository access. The GitHub App is installed at the organization level on GitHub, and AstroPulse automatically syncs the credentials needed for deployments. You choose which repositories to grant access to during installation.

Quick Start​

Install the GitHub App and connect it to your AstroPulse organization with one command:

astroctl integrations github install

The CLI uses smart 3-step detection:

  1. Already linked -- verifies the existing connection and optionally refreshes credentials
  2. Installed on GitHub but not linked -- auto-detects and links without opening a browser
  3. Not installed -- opens your browser to the GitHub App approval page

Installation Flow​

Step 1: Run the install command​

astroctl integrations github install

Step 2: Approve in browser​

If this is a first-time installation, your browser opens to the GitHub App approval page. Select the GitHub organization and choose which repositories to grant access to.

Step 3: Automatic linking​

Once you approve the app in GitHub, the CLI automatically detects the new installation and links it to your AstroPulse organization. Deployment credentials are created automatically.

GitHub App installed and connected!
  Account:         my-github-org
  Status:          ACTIVE

Verify with: astroctl integrations github repositories

Managing Installations​

List installations​

# List all GitHub installations linked to your org
astroctl integrations github list

List accessible repositories​

# Auto-selects if only one installation
astroctl integrations github repositories

# List repos for a specific GitHub account
astroctl integrations github repos --account my-org

Validate repository access​

Before deploying an application from a private repo, verify that the GitHub App has access to the specific path:

astroctl integrations github validate-path \
  --repo-url https://github.com/my-org/my-repo.git \
  --branch main \
  --path helm/my-chart

Remove an installation​

# Auto-selects if only one installation
astroctl integrations github delete

# Delete by GitHub account name
astroctl integrations github delete --account my-org

Using with Applications​

Once the GitHub App is installed, reference private repositories in your application spec just like public ones:

apiVersion: platform.astropulse.io/v1
kind: Application
spec:
  appName: my-app
  clusterName: my-cluster
  source:
    repoURL: https://github.com/my-org/my-private-repo.git
    path: helm/my-chart
    targetRevision: main

The platform automatically uses the GitHub App credentials for private repository access. No additional configuration is needed in the application spec.

Refreshing Credentials​

After a platform redeployment or when credentials become stale, force a credential refresh:

astroctl integrations github install --refresh

This re-verifies the GitHub App connection and re-creates the deployment credentials without requiring a new browser approval.

Troubleshooting​

"No GitHub App installation is linked"​

Run the install command to set up the integration:

astroctl integrations github install

Repository not showing in list​

The GitHub App may not have access to the repository. Go to your GitHub organization settings → Installed GitHub Apps → AstroPulse, and add the repository to the allowed list.

Credentials stopped working​

After platform redeployments, credentials may need refreshing:

astroctl integrations github install --refresh

Multiple GitHub organizations​

If you have installations from multiple GitHub accounts, specify which one to use:

astroctl integrations github repos --account my-specific-org