Integrating GitHub with Meshery

Introduction

Meshery’s GitHub Integration is a powerful feature that lets you authorize your GitHub account and import infrastructure files into Meshery. These files are then readily available in the Meshery catalog and can be easily opened in the Meshery Playground for viewing and configuration.

The GitHub integration offers an alternative to importing designs from the canvas or through mesheryctl. It simplifies configuration management and enhances deployment workflow efficiency. By leveraging this integration, you ensure your infrastructure designs are easily accessible and always up-to-date.

This integration offers the following benefits:

1. Easy Design Imports: Quickly import existing configuration files directly from GitHub.

2. Designs Available in Meshery Catalog: The files imported from GitHub will be available in your Meshery catalog, allowing you to easily open the designs in the Meshery Playground to view and work with them.

3. Collaboration: Integrating Meshery with GitHub fosters collaboration by providing a streamlined process for teams to quickly access and collaborate on their designs.

How to Integrate GitHub with Meshery

You can commence the integration process from the “Extensions Page in Meshery”, or alternatively from the “Layer5 Cloud Dashboard”.

Access Integrations Page from the Meshery Extensions Page

1. Go to Extensions.

2. Click on Enable for GitHub Action: Kanvas Snapshot.

3. You will be redirected to the Integrations page.

   

Navigate to the Integrations Page via the Layer5 Cloud Dashboard

1. On Layer5 Cloud, click on the menu icon on the navigation bar to open the global navigation menu.

   

2. From the Spaces drop down, select Integrations.

   

3. You will be redirected to the Integrations page. Click Connect to begin the integration process.

   

Connect GitHub and Import Designs

Let’s go through the steps required to connect your GitHub account and import files from your repository.

1. Connect GitHub App: This initiates the authorization process where you’ll link your GitHub account with Meshery.

   • Click Connect.

     

   • You will be asked to sign in to your GitHub account if you are not already signed in.

   • Once signed in, GitHub will prompt you to select the GitHub account where you want to install the Meshery GitHub App. This account could be your personal account or an organization account you can access.

     

   • After selecting the account, GitHub will prompt you to authorize the Meshery GitHub App so it can access your account.

   • You can choose to allow access to all repositories or select specific ones.

   • After making your selection, click Install and Authorize to complete the authorization process.

     

Note: When you install a GitHub App on your account or organization, you grant the app permission to access the organization and repository resources that it requested. You also specify which repositories the app can access.

2. Select Repositories: After authorization, you will be redirected back to this page to select the GitHub repository you want to import files from.

   • Select the repository or repositories you want, then click Next.

     

   Reconfigure Repository Selection

   If you are reconfiguring your existing GitHub integration, you will see the Add Repository button. This takes you to the “Install Meshery” page where you can either:

   1. Select a new repository you want to import files from.

   2. Reconfigure repository access for GitHub accounts that already have the Meshery GitHub App installed or

   3. Install the Meshery GitHub App on a new GitHub account to gain access to the repositories there.

      

3. Import Design Files: The files in the repository are displayed for you to select the ones you want to import as designs.

   • There is a checkbox that allows you to choose between displaying all file types or only the file types that are typically supported by Meshery for import.

     

   • The file types supported for import are:

     1. Helm charts
     2. Docker Compose files
     3. Kubernetes manifests
     4. Meshery Designs

   • Select the checkbox beside the directory name to import all the files in the directory, or individually select the files you want to import and click Import.

   • If you want to go back and change your selection or choose a different repository, click Back.

     

   • After the import, the files that were imported successfully and those that weren’t will be indicated on the screen.

[Optional] Enabling Snapshots

These next steps are optional. By enabling snapshots, you can choose a design from each repository to configure Meshery snapshots. This feature allows you to capture snapshots of design infrastructure changes with each pull request made using a GitHub workflow that Meshery will add to your repository.

1. Select Designs: Select the design from the repository you want to enable snapshots for, then click Next.

   

   Warning: Workflow Already Exists

   If you attempt to add a workflow to a repository that already contains an existing workflow from this process, you will see a warning message. Proceeding to the next step after receiving this warning will overwrite the existing snapshot workflow in that repository.

   

2. Configure Secrets:

   • Copy the API TOKEN and add it to the secrets page of your selected repository. To learn more about configuring secrets check out Using secrets in GitHub Actions.

   • Tick the check box to confirm that you have added the token.

     

3. Add workflows: Allowing Meshery to add this workflow ensures the smooth integration of Meshery Snapshot with your GitHub repository. The workflow:

   • Triggers on Pull Requests: Automatically runs when a pull request is opened, synchronized, or reopened.

   • Assigns Permissions: Provides necessary permissions for reading actions, writing content, handling security events, statuses, and pull requests.

   • Captures Snapshots: Uses the Kanvas-Snapshot action to capture snapshots of your infrastructure based on the specified application_type (e.g. Kubernetes Manifest, Docker Compose, Helm Chart).

   With the workflow active in your repository, you can now visualize changes to your infrastructure directly in your pull requests, making it easier to track and review updates on designs.

   

   Click Next to finish setting up!

Finish Setup

You have successfully Integrated GitHub with Meshery! This page provides an overview of the steps you completed.

1. Click on the commit hash link (e.g. #7f2d9) to see where the workflow was added in your repository.

2. Click on the View icon to open the Meshery Catalog and see the design.

3. If everything looks good, click Finish. If you need to make any updates, you can go Back to the previous steps.

   

View Imported Designs

To view imported designs:

1. Go to Meshery Catalog.

2. Click on My Designs on the navigation bar.

   

View GitHub Integration Connection on Meshery Playground

To view and manage the GitHub connection, on the left sidebar of the playground, click on Lifecycle > Connections.

Delete GitHub Integration

You can delete the GitHub Integration Connection from the “Connections page in Meshery" shown in the preceding section or “Integrations page in Layer5 cloud".

On the Connections page in Meshery:

1. Identify the connection and click on its checkbox.
2. Click Delete.

On the Integrations Page in Layer5 Cloud page:

1. Click on the GitHub Connection.

   

2. Tick the checkbox then delete.

   

Conclusion

In this guide, you walked through the steps to integrate your GitHub account with Meshery.

You authorized Meshery to access your GitHub account, imported designs from repositories, and viewed them in the Meshery Catalog. You also learned how to enable Meshery Snapshots for your GitHub repositories, allowing you to version and track changes to your infrastructure configurations.

Additionally, you saw how to view, manage, and delete your GitHub connection within Meshery and Layer5 Cloud.

By connecting your GitHub account, you gain seamless access to your resources, streamline your deployment workflow, and ensure your design infrastructure configurations are always up-to-date.