Skip to main content

Connect Amplication server to GitHub

Amplication already provides built-in integration with GitHub to push the generated application to a GitHub repository.

When running a local Amplication server you first need to configure the server to integrate with a new GitHub app, following the steps below.

Step 1: Create a new GitHub App​

  1. Login in your GitHub account and create a new GitHub App here

  1. Enter the fields as follows:
    • Application name - [your-github-username]-amplication-local
    • Homepage URL - http://localhost:3001. If you are hosting the Amplication client on any other address, use the specific address.
    • Application description - optional
    • Callback URL - http://localhost:3000. If you are hosting the Amplication server on any other address, use the specific address.
    • Post installation > Setup URL - http://localhost:3001/github-auth-app/callback. If you are hosting the Amplication server on any other address, use the specific address.
    • Webhook > Active - "unchecked"
    • Permissions > Repository permissions
      • Administration - Access: Read and Write
      • Content - Access: Read and Write
      • Metadata - Access: Read-only
      • Pull requests - Access: Read and Write
      • Webhooks - Access: Read and Write
  2. Click Create GitHub app
  3. Click Generate a new client secret and copy the resulting secret
  4. Click Generate a private key, download, open the generated certificate, add \n at the end of each line except the last line and join all lines to obtain a single line string
  5. Under the "Generate a private key" section, click "Generate private key" to download a PEM file containing your app's private key
  6. Note the App ID shown on the "General" tab of your app's settings page
  7. On your local machine, set the GITHUB_APP_APP_ID and GITHUB_APP_PRIVATE_KEY environment variables to the App ID and the contents of the PEM file, respectively
  8. Once you have set up these credentials, you should be able to complete the build process locally using git pull.

Step 2: Configure Amplication server to work with the new GitHub app​

  1. Clone /packages/amplication-server/.env into /packages/amplication-server/.env.local

  2. Update /packages/amplication-server/.env.local with the following variables

    .env.local
    # GitHub App (Git sync)
    GITHUB_APP_APP_ID="replace with the github App ID"
    GITHUB_APP_CLIENT_ID="replace with the github app Client ID"
    GITHUB_APP_CLIENT_SECRET="replace with secret created as step 1.4"
    GITHUB_APP_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\nContent of the key created in step 1.5\n-----END RSA PRIVATE KEY-----

    # replace [your-github-username]-amplication-local with your chosen name
    GITHUB_APP_INSTALLATION_URL='https://github.com/apps/[your-github-username]-amplication-local/installations/new?state={state}'

Step 3: Configure Amplication git pull request service to work with the new GitHub app​

  1. Clone /packages/amplication-git-pull-request-service/.env into /packages/amplication-git-pull-request-service/.env.local

  2. Update /packages/amplication-git-pull-request-service/.env.local with the following variables

    GITHUB_APP_APP_ID="replace with the github App ID"
    # replace [your-github-username]-amplication-local with your chosen name
    GITHUB_APP_INSTALLATION_URL='https://github.com/apps/[your-github-username]-amplication-local/installations/new?state={state}'
    GITHUB_APP_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\nContent of the key\n-----END RSA PRIVATE KEY-----

  3. Restart Amplication server.