Skip to main content

​
Overview

The GitHub installer runs after the shared GCP install and layers GitHub-specific infrastructure onto that base. It reads generated/gcp/<project-id>/install-state.json, creates or reuses GitHub App credentials, deploys the Cloud Run job used for call graph bootstrap, and triggers one execution. Before you run the GitHub installer, make sure:
  • ./providers/gcp/install-gcp.sh has already completed for the same gcp.project_id
  • You have Terraform >= 1.9, gcloud, jq, curl, and openssl installed
  • You have already authenticated with Application Default Credentials using gcloud auth application-default login
  • You also have python3 installed if github.mode is self-hosting

​
What permissions the installer needs

The identity running ./providers/gcp/install-gcp-integration.sh github should have permissions equivalent to the following:
What the installer needs to doGCP IAM permissions
Create the GitHub integration subnet, Artifact Registry repository, service account, Secret Manager secret, and VPC connectorcompute.subnetworks.create, artifactregistry.repositories.create, iam.serviceAccounts.create, secretmanager.secrets.create, vpcaccess.connectors.create
Grant the build service accounts and Cloud Run job access to project resources and secretsresourcemanager.projects.setIamPolicy, secretmanager.secrets.setIamPolicy
Store or reuse GitHub App credentials, build the bootstrap image, deploy the Cloud Run job, and trigger the first executionsecretmanager.versions.add, secretmanager.versions.access, cloudbuild.builds.create, run.jobs.create, run.jobs.update, run.jobs.run
In self-hosting mode, you also need permission to create and install a GitHub App in the target GitHub organization.

​
Fill the GitHub config file

The installer reads providers/gcp/integrations/github/config/install-gcp-github.yaml by default. Fill in the required values, then leave optional fields blank unless you need custom names. This is the full template with comments explaining each field: 
# Fill in this file before running ./providers/gcp/install-gcp-integration.sh github.
#
# Keep string values quoted to avoid YAML booleans such as "on", "off", "yes",
# and "no" being coerced unexpectedly.

gcp:
  # Required. Must match the project created by ./providers/gcp/install-gcp.sh.
  project_id: "your-integrations-project-id"

github:
  # Optional. Defaults to "self-hosting". Set to "cloud-hosting" to supply app credentials via environment variables instead of creating a new app.
  mode: "self-hosting"
  # Optional. Defaults to "github-vpc-subnet".
  connector_subnet_name: ""
  # Optional. Defaults to "10.44.0.0/28".
  connector_subnet_cidr: ""
  # Required. Every repository that should be processed by the bootstrap job.
  repositories:
    - "your-org/repo-one"
    - "your-org/repo-two"
  app:
    # Required in self-hosting mode. GitHub organization that should own the app.
    organization: "your-org"
    # Optional. Defaults to "Asymptote Integrations".
    app_name: ""
    # Optional. Leave blank unless you already have a public webhook receiver.
    webhook_url: ""
  # Optional. Defaults to "github-app".
  app_secret_name: ""
  # Optional. Defaults to "github".
  artifact_registry_repository_id: ""
  # Optional. Defaults to "github-bootstrap".
  job_name: ""
If you override connector_subnet_cidr, keep it as a non-overlapping IPv4 /28 range.

​
GitHub App modes

​
Self-hosting mode

self-hosting is the default mode. The installer opens a browser, registers an organization-owned GitHub App from a manifest, waits for the manifest callback on 127.0.0.1, stores the returned credentials in Secret Manager, and then waits for the app to be installed on the configured repositories before triggering the Cloud Run job. If GitHub asks which repositories the app can access, choose Only select repositories and select every repository listed in github.repositories. On reruns, if those GitHub App credentials already exist in Secret Manager and still validate against GitHub, the installer reuses them instead of creating another app. If GITHUB_TOKEN is set, the installer uses it for the GitHub manifest conversion API call.

​
Cloud-hosting mode

cloud-hosting keeps the hosted ownership split. In that mode, do not put app credentials in YAML. Export them in the shell that runs the installer:
  • ASYMPTOTE_GITHUB_APP_ID
  • ASYMPTOTE_GITHUB_APP_PRIVATE_KEY_PEM or ASYMPTOTE_GITHUB_APP_PRIVATE_KEY_PEM_FILE
  • ASYMPTOTE_GITHUB_APP_WEBHOOK_SECRET if you need to provide a webhook secret

​
Run the GitHub installer

1

Update `providers/gcp/integrations/github/config/install-gcp-github.yaml`

Fill in the GCP project ID and every GitHub repository that should be processed.
2

Run the script

From the repository root, run:
./providers/gcp/install-gcp-integration.sh github
3

Approve the planned changes

The installer will show the planned GitHub integration infrastructure changes before applying them. Review and approve those changes to continue.
If you want to use a different config file or skip confirmation prompts: 
./providers/gcp/install-gcp-integration.sh github --config /path/to/install-gcp-github.yaml
./providers/gcp/install-gcp-integration.sh github --auto-approve

​
What the installer does

After the GitHub App setup completes successfully, the installer:
  • Reads the base install state from generated/gcp/<project-id>/install-state.json.
  • Creates the GitHub-specific connector subnet, Artifact Registry repository, service account, Secret Manager secret, and VPC connector.
  • Creates or reuses a GitHub App credential set.
  • Builds the jobs/call-graph-bootstrap container image with Cloud Build.
  • Creates or updates the Cloud Run job used for call graph generation.
  • Triggers one job execution for the repositories in your config.
The installer prints the execution ID and returns immediately. It does not wait for the full call graph build to finish. At the end of the run, it also prints the project ID, install mode, GitHub App ID, GitHub App secret name, and Cloud Run job name.

​
Add more repositories later

1

Update the config file

Add the new repositories to github.repositories.
2

Update the existing GitHub App installation

Edit the GitHub App installation and grant it access to the same newly added repositories.
3

Rerun the installer

Run ./providers/gcp/install-gcp-integration.sh github again. It will reuse the existing GitHub App when possible and trigger processing for the repositories now listed in your config.
If a repository is missing from either github.repositories or the GitHub App installation, it will not be processed by the bootstrap job.

​
Troubleshooting

If the installer says the base install state is missing, run ./providers/gcp/install-gcp.sh first or confirm that gcp.project_id points to the correct generated project. If a previous self-hosting run already created the GitHub App and a later step failed, rerun the GitHub integration installer. It reuses the stored GitHub App credentials from Secret Manager when they are still valid.