Installation

Learn how to connect your repositories to Hypermod

This guide will walk you through the process of connecting your GitHub repositories to Hypermod. Once connected, you'll be able to deploy automated code transformations across your codebase.

Prerequisites

Before you begin, ensure you have:

  • A GitHub account
  • Admin access to the repositories you want to connect
  • Installed the Hypermod GitHub App

Connection Process

1. Access the Dashboard

After logging in, navigate to your Hypermod dashboard. Press the "Manage installation" button to install the Hypermod GitHub App. Select the orgs and repositories you want to connect to Hypermod. Once you have installed the Github App you will be redirected back to the dashboard. You'll now see a list of repositories that are available for connection.

Connect Github App

2. Select Repositories

You can now select the repositories you want to connect to Hypermod.

In the dashboard view:

  1. Review the list of available repositories
  2. Select the checkboxes next to the repositories you want to connect
  3. You can connect multiple repositories at once

Dashboard showing available repositories

3. Initiate Connection

Click the "Connect Repositories" button to start the connection process.

This will:

  • Create pull requests in each selected repository
  • Add the necessary GitHub workflow file for Hypermod integration

Connect Repositories

4. Review Pull Requests

For each selected repository, Hypermod will create a pull request that adds a GitHub workflow file. This workflow file:

  • Is essential for Hypermod's operation
  • Should not be modified
  • Enables secure communication between Hypermod and your repository
  • Handles the execution of code transformations

The Hypermod workflow file will be added to the .github/workflows/ directory in your repository. This workflow file is how Hypermod will be able to securely dispatch transformations to your repository. For more information on the workflow file, see our Security Policy.

Review Pull Requests

Example workflow file:

# Preview of the workflow file (DO NOT MODIFY)
name: Hypermod

on:
  workflow_dispatch:
    inputs:
      deploymentId:
        description: 'The deployment ID containing instructions to apply on a repository'
      deploymentKey:
        description: 'The deployment key to authenticate the request'
jobs:
  receive_hypermod_event:
    permissions: write-all
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run Hypermod CLI
        uses: hypermod-io/action@v1
        with:
          deploymentId: ${{ inputs.deploymentId }}
          deploymentKey: ${{ inputs.deploymentKey }}
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

5. Merge Pull Requests

To complete the connection:

  1. Review the pull request in each repository
  2. Merge the pull requests to enable Hypermod integration
  3. The workflow file will be added to .github/workflows/ in your repository

Merge Pull Requests

6. Verification

Once the pull requests are merged:

  • The repositories will show as "Connected" in your dashboard
  • You'll be able to deploy code transformations to these repositories
  • The connection status will update automatically

Connection Status

Your repositories can have the following statuses:

  • Pending: Pull request has been created but not yet merged
  • Connected: Pull request has been merged and repository is ready for transformations
  • Failed: Connection attempt failed (check repository permissions)

Next Steps

After connecting your repositories, you can:

Troubleshooting

If you encounter any issues during the connection process:

Common Issues

  1. Workflow Permissions
  • In your repository settings, ensure Workflow permissions are set to "Read and write".
  • Go to your repository settings
  • Navigate to "Actions"
  • Under "Workflow permissions", set the permissions to "Read and write"
  • Save the settings

  1. Pull Request Creation Failed

    • Verify you have admin access to the repository
    • Check GitHub App permissions

  2. Workflow File Conflicts

    • If you have existing workflows, ensure there are no naming conflicts
    • Do not modify the Hypermod workflow file

  3. Connection Status Issues

    • Try refreshing the dashboard
    • Check GitHub Actions permissions in your repository settings

Need more help?

FAQUsing the editor