Skip to main content

Sync with GitHub

Amplication can seamlessly synchronize with GitHub. The code generated by Amplication gets pushed to a GitHub repository of your choosing. You own the code and have full control to customize it to your needs in your favorite IDE.

This page provides you with everything you need to work with GitHub. You'll learn how to do the following:

You'll also learn how Amplication manages your repo from GitHub's side.

Let's get started.

Prerequisites​

If you are running Amplication locally, you should first read Connect Amplication server to GitHub. It'll show you how to configure the server to work with a new GitHub application.

Authorize Amplication to access GitHub​

Before you can integrate your application with GitHub, you need to authorize Amplication to get access to your GitHub account.

info

This is separate and distinct from logging in with GitHub on Amplication's login page.

When you create a service on a project for the first time on Amplication, you have the option of selecting your preferred git provider.

If you haven't connected a git repo to your service yet, go to your project's dashboard. You'll need to go to the Sync with Git Provider page. There are 3 ways to do this:

  1. Click Sync with git provider on the sidebar.
  2. Click on the Sync with git provider tile on your project's dashboard.
  3. Click Connect to git on the footer at the bottom of the page.

You're now on the Sync with Git Provider page. Proceed with the following steps to connect a GitHub repository to your service:

  1. Click on the Select organization dropdown.
  2. Click on the Add Organization button at the bottom of the dropdown.
  3. Click on the Connect button for GitHub that appears in the Select Git Provider modal.
info

If you're already connected to GitHub, you can either add another GitHub organization or select an account you connected previously.

You can then go to selecting your repository

Install Amplication's GitHub App​

Now the Install Amplication GitHub App page opens. Select your preferred account or organization on GitHub.

Set Amplication's Configuration Settings​

After selecting your preferred account or organization, you'll be led to the configuration page. You can configure the GitHub App to only allow access specific repositories in your account, or allow Amplication to access all of your repositories.

After selecting your repositories, click on the Next button. You'll be brought back to Amplication.

Select or Create Your Repository​

You'll see a modal appear with a populated list of repositories based on your configuration settings from above. You can also create a new repository by clicking on the Create repository button.

This repository is where Amplication will put your generated code.

tip

If you create a new repository, you'll to update the Amplication GitHub App settings to allow access to the new repository.

Change Your Service's Repository​

A project can have many services. The GitHub repository you chose when creating the initial service for the project will be set as the default repository for the project. Each new service you create will inherit the repo settings from the project settings.

But, it's possible to override these settings for each individual service. To do this when you're creating a service, turn on the Override default settings toggle during the Git Provider selection step.

The repository selection modal will appear again. You can select a new repository based on the configuration settings you set for Amplication's GitHub App.

Change Your Service's Connected Git Provider​

Besides changing your selected GitHub repository, you can change your git provider to Bitbucket. See the Sync with Bitbucket page.

Create a new Pull Request​

To make a new pull request, first make a change in your application and click the Commit changes & build button on the right side panel.

Amplication service dashboard with "Commit changes & build" button outlined.

tip

For an example of changes you can make to your service, see Building New Versions of Your Service.

To view your previous commits for a project, select the drop down at the top of the page, and click Commits.

Amplication service dashboard with "Commits" button outlined.

You'll now see a list of your commits for the project. You can go to a specific commit by clicking on it in the sidebar. Each commit will contain changes, if any, for all services.

Now click on the specific service that you're interested in seeing the build for. A build contains a log of all the updates and changes that were made to that specific service during that commit.

To view the Pull Request in GitHub, select the most recent commit and click Open With GitHub in the footer.

You can now view the code changes generated by Amplication, and merge them.

Now let's review what happens from GitHub's side when Amplication generates a new Pull Request on your repository.

Merging Amplication's Pull Request into your branch​

Amplication triggers the creation of a commit on the changed files whenever a new build is performed on a project. The changed files are all the files that were added, removed, or changed from the last build.

note

Do not delete the amplication branch.

Do not modify the amplication branch, except to resolve conflicts. Handle conflicts directly on the amplication branch. Avoid creating new commits or merging changes from other branches to prevent bugs and inconsistencies.

A pull request generated by Amplication on GitHub

Amplication reduces the chances of user changes being overridden by interacting with the user’s repository through an amplication branch. This branch is created in your selected repository by Amplication's GitHub App.

info

If you're on the Free Plan, Amplication will create multiple amplication branches and pull requests for each commit. The format will be amplication-build-{id}.

If you're on the paid plan, Amplication will instead manage all commits on a single branch called amplication.

Let's review what's happening here in its entirety.

The amplication branch​

Users can merge Amplication-made changes by merging pull requests created by Amplication from the amplication branch to the user repository's base branch.

tip

The ability to change your base branch is a feature that's available for Enterprise plan users.

The commit message​

The title of the pull request and the commit message will both come from the message you enter into the commit message box in Amplication's pending changes section.

Also included is a direct link to your build. It will take you to the specific build log for this commit on Amplication.

Merging your pull request​

After clicking on Merge, do not delete the amplication branch. You can then navigate back to your main branch where you will find your Amplication code.

Next Steps​

Now you're more familiar with how the pull request process works with Amplication and GitHub.

There are differences between the free plan and the paid plan for Amplication's Sync with GitHub feature. Learn more about them here.