Connect to GitHub

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This page describes how to use Developer Connect to create connections to GitHub and links to your GitHub repositories. You can use the Google Cloud console or the Google Cloud CLI to complete these actions.

After you link your GitHub repositories, you can use them in Firebase App Hosting, a Google product for hosting modern frameworks-based web apps.

To learn more about Developer Connect, see Overview.

Before you begin

1. Sign in to your Google Account.

   If you don't already have one, sign up for a new account.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Developer Connect and Secret Manager APIs.

   Enable the APIs

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Developer Connect and Secret Manager APIs.

   Enable the APIs

8. Ensure that you have access to a GitHub account and a repository hosted on GitHub.com. To create new ones:
   • Create a GitHub account
   • Create a repository on GitHub.com
9. If you're using an existing repository and you aren't the owner, ask the owner to grant admin-level permissions to the repository. If the repository is in a GitHub organization, request admin-level permissions from the organization owner. To learn more about GitHub organizations, see GitHub account types.
10. To use the command-line examples in this guide, install and configure the Google Cloud CLI.
    
    If you've installed gcloud CLI previously, make sure you have the latest available version by running gcloud components update.

Create a service account

If you plan to create connections using the gcloud CLI, create a Developer Connect service account by running the following command:

gcloud beta services identity create \
    --service=developerconnect.googleapis.com \
    --project=PROJECT_ID

Where:

• PROJECT_ID: your Google Cloud project ID.

Grant the required IAM permissions

1. To create connections and links, grant the Developer Connect Admin role (roles/developerconnect.admin)to your Google Cloud user account by running the following command:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=user:EMAIL_ID \
       --role="roles/developerconnect.admin"
   

   Where:

   • "EMAIL_ID": the email ID for your Google Cloud account.

2. If you plan to create connections using the gcloud CLI steps, grant the Secret Manager Admin role (roles/secretmanager.admin) to the Developer Connect Service Agent by running the following command in your Google Cloud project:

   PN=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
   DEVELOPER_CONNECT_SERVICE_AGENT="service-${PN}@gcp-sa-devconnect.iam.gserviceaccount.com"
   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:${DEVELOPER_CONNECT_SERVICE_AGENT}" \
       --role="roles/secretmanager.admin"
   

   Where:

   • PROJECT_ID: your Google Cloud project ID.
   Note: You can revoke the Secret Manager Admin role after your connection is in state COMPLETE.

To learn more about managing IAM roles, see Manage access to projects, folders, and organizations.

To learn more about IAM roles associated with Developer Connect, see IAM roles and permissions.

Create a connection

With Developer Connect, you can create a connection to GitHub and then link to one or more source code repositories:

console

Initiate a connection

1. Open Developer Connect in the Google Cloud console.

   Go to Developer Connect

2. Click the Connections tab.

3. Click Create connection.

4. Choose GitHub as your provider.

5. Choose a region.

6. Enter a name for your new connection.

7. Click Continue.

   The Google Developer Connect dialog appears, requesting authorization to use your GitHub OAuth token.

   If you don't see a dialog, turn off any pop-up blocking browser plug-ins and makes sure that your browser settings allow pop-ups. For example, in Chrome, follow the instructions to allow pop-ups.

8. Click I understand and continue to agree to share your GitHub OAuth token with Developer Connect and store it in Secret Manager.

9. Sign-in to GitHub if prompted to do so.

10. Click Authorize Developer Connect to allow the Google Developer Connect app to access your GitHub account. If you don't see this prompt, authorization has already been granted on this account.

GitHub creates a token and Developer Connect stores it in your Google Cloud project as a Secret Manager secret. To view your secrets, list secrets in Secret Manager.

Content from Google Cloud resources linked to this connection might be transferred to GitHub. This applies to all existing and future resources utilizing this connection. You may revoke access to Developer Connect through GitHub at any time.

Configure the connection

Grant permissions on your GitHub account and repositories using the following steps. The prompts you see depend on whether the GitHub account already has the Google Developer Connect app installed.

If you see a list of GitHub accounts: You don't have the app installed yet. Install and configure it by following these steps:

1. Choose the GitHub account that has access to the repository you want to link.

2. Specify GitHub repository permissions and permit the app installation.

   We recommend that you select only the repositories you need. You can add more repositories to the connection at any time.

If you see a prompt to re-use an existing installation: Choose where to install and configure the app by following these steps:

1. Click GitHub Account to see accounts that have the Google Developer Connect app installed. If you see the account you want to use, choose it.

2. Click Confirm.

3. If you don't see the account that you want to use, choose Install the GitHub App on another GitHub account.

4. Click Confirm.

5. Choose the GitHub account you want to use.

6. Specify GitHub repository permissions and permit the app installation.

   We recommend that you select only the repositories you need. You can add more repositories to the connection at any time.

   When the dialog closes, the app installation is complete.

7. In the list of repositories, choose one or more GitHub repositories to create links to.

8. Select Generated to use a generated repository resource name, or select Manual and input a name manually.

9. Click Link.

Your connection is added to the Connections page and your repository links are added to the Repositories page.

glcloud

Note: The following steps require gcloud version 476. To check your gcloud CLI version, run the gcloud version command. If version 476 is not yet available in your location, you can use the gcloud commands with one modification: change developer-connect to developerconnect.

Initiate a connection

The following steps require actions in your web browser.

1. Run the following command to initiate a connection to GitHub:

   gcloud alpha developer-connect connections create CONNECTION_NAME \
       --location=REGION \
       --github-config-app=firebase
   

   Where:

   • CONNECTION_NAME: the name for your connection.
   • REGION: the region for your connection. Supported regions include: us-central1, asia-east1, and europe-west1.

   When choosing a region, consider latency and availability. You can generally select the region closest to your users, but you should also consider the location of the other products and services that your project might integrate with.

   A connection name is created.

2. You must complete the creation of the connection by installing the Developer Connect GitHub app. Run the following command to get the URI for app installation.

   gcloud alpha developer-connect connections describe CONNECTION_NAME \
       --location=REGION
   

   Where:

   +   CONNECTION_NAME: the name of your connection.
   +   REGION: the region for your connection.
   

   Developer Connect returns a link to install the Google Developer Connect app in a browser window. Copy this link.

3. Open the link in a web browser.

4. Sign-in to GitHub if prompted to do so.

5. Click I understand and continue to agree to share your GitHub OAuth token with Developer Connect and store it in Secret Manager.

6. Click Authorize Developer Connect to allow the Google Developer Connect app to access your GitHub account. If you don't see this prompt, authorization has already been granted on this account.

GitHub creates a token and Developer Connect stores it in your Google Cloud project as a Secret Manager secret. To view your secrets, list secrets in Secret Manager. You may revoke access to Developer Connect through GitHub at any time.

Content from Google Cloud resources linked to this connection might be transferred to GitHub. This applies to all existing and future resources utilizing this connection. You may revoke access to Developer Connect through GitHub at any time.

Configure the connection

Grant permissions on your GitHub account and repositories using the following steps. The prompts you see depend on whether the GitHub account already has the Google Developer Connect app installed.

If you see a list of GitHub accounts: You don't have the app installed yet. Install and configure it by following these steps:

1. Choose the GitHub account that has access to the repository you want to link.

2. Specify GitHub repository permissions and permit the app installation.

   We recommend that you select only the repositories you need. You can add more repositories to the connection at any time.

If you see a prompt to re-use an existing installation: Choose where to install and configure the app by following these steps:

1. Click GitHub Account to see accounts that have the Google Developer Connect app installed. If you see the account you want to use, choose it.

2. Click Confirm.

3. If you don't see the account that you want to use, choose Install the GitHub App on another GitHub account.

4. Click Confirm.

5. Choose the GitHub account you want to use.

6. Specify GitHub repository permissions and permit the app installation.

   We recommend that you select only the repositories you need. You can add more repositories to the connection at any time.

When the dialog closes, the app installation is complete.

Verify the connection

Verify the creation of your GitHub connection by running the following command:

gcloud alpha developer-connect connections describe CONNECTION_NAME \
    --location=REGION

Where:

• CONNECTION_NAME: the name of your connection.
• REGION: the region for your connection.

Developer Connect returns a status in the installationState field. If the value of this field is COMPLETE, your app installation is done. Otherwise, Developer Connect returns a URI to return you to configuration in the browser.

Link to repositories

Add repository links to existing connections by completing the following steps.

console

1. Open the Repositories page in the Google Cloud console.

Open the Repositories page

1. Click Link repository.

2. Leave Use existing connection selected and choose from the list of connections.

3. Click Continue.

4. Select the repositories you want to link to.

5. Select Generated to use a generated repository resource name, or select Manual and input a name manually.

6. Click Create.

gcloud

Run the following command:

gcloud alpha developer-connect connections git-repository-links create REPO_NAME \
    --clone-uri=REPO_URI \
    --connection=CONNECTION_NAME \
    --location=REGION

Where:

• REPO_NAME: the name of your repository.
• REPO_URI: the link to your GitHub repository. For example, https://github.com/cloud-build/test-repo.git.
• CONNECTION_NAME: the name of your connection.

What's next

• Build web apps in Firebase App Hosting using your GitHub repositories.