# GitHub Integration

{% hint style="info" %}
Generally, you can connect only to public repositories. However, with a valid Monaca subscription plan, you can also connect to private repositories. Please refer to [Monaca Subscription Plan](https://monaca.io/pricing.html).
{% endhint %}

## Setup

In this section, you will learn how to link a Monaca account to your GitHub account. Please follow the instructions below:

1. Go to the [Link to GitHub](https://monaca.mobi/en/vcs) page.

![](/files/-MfjfqXK1rW6YnPWZ9jQ)

2\. Click the **Link** button. You are required to login with your GitHub account before being redirected to the GitHub’s `Authorize Application` page.

![](/files/-Mfjfxj8FYmYNqaVcCHm)

3\. In the `Authorize Application` page, you will be asked to authorize the application in order to link your Monaca account to GitHub. Click **Authorize application** to proceed.

![](/files/-Mfjg1-osDb_TrD6o8PB)

4\. Now your Monaca account is linked to your GitHub account.

![](https://docs.monaca.io/images/monaca_ide/manual/version_control/4.png)

{% hint style="warning" %}
Please note that you can only link one GitHub account to a Monaca account. If you try to link with multiple accounts, you will encounter an error.
{% endhint %}

## Connecting a Monaca project to a new GitHub repository

### Step 1: Creating a new empty repository

Go to your GitHub account and create a new empty repository (without a `readme` file).

### Step 2: Connecting a Monaca project with the repository

At this point you should have linked your Monaca account to GitHub. To connect a Monaca project to the new repository, you will need to do some configurations in the Monaca Cloud IDE:

1. From the Monaca Dashboard, open the project you want to connect to a repository.
2. From the Monaca Cloud IDE menu, go to **Project → VCS Configure** .
3. Select **GitHub**.

![](/files/-MfjiWlBH9axxyC5_ZuP)

4\. Select your remote empty repository. Then, click **Initialize** to save the configuration.

![](/files/-MfjijQ_R3jbdkuaxi-9)

{% hint style="warning" %}
The repository cannot be changed after configured.
{% endhint %}

5\. Your project is then uploaded to your new repository in GitHub. By default, your working branch will be configured as `master`. If you want to switch to another working branch, please go to **Project → VCS Configure** .

![](https://docs.monaca.io/images/monaca_ide/manual/version_control/branch.png)

## Importing a project from a GitHub repository to Monaca

Once you have linked your Monaca account with GitHub, you can import any existing projects from the GitHub repositories to the Monaca Cloud IDE.

1. From the dashboard, click **Import**.
2. In the `Import Project` dialog, fill in the necessary information and choose **Import from GitHub Repository**. Then, select the repository and click the **Import** button.

![](/files/-MfjjXA_XG_5amOrvh6d)

3\. If the import is successful, the new project will be added to the dashboard. By default, your working branch will be configured as `master`. If you want to switch to another working branch, please go to **Project → VCS Configure**.

![](https://docs.monaca.io/images/monaca_ide/manual/version_control/branch.png)

## Working with a remote repository

Once you have successfully connected your project with a repository, you can start working on the same project with your team members and keep it synchronized to the latest updates in the Monaca Cloud IDE.

Monaca Cloud IDE provides a very user-friendly interface supporting the version control of your code. Without learning how to use Git, you can still perform some basic Git commands directly from the IDE.

### Checkout from the current working branch

If you have more than one branch and want to change the current working branch, please do as follows:

1. From the Monaca Cloud IDE menu, go to **Project → VCS Configure**.
2. Choose the branch you want to switch to and click the **Clear Cache & Save** button.

![](https://docs.monaca.io/images/monaca_ide/manual/version_control/branch.png)

{% hint style="info" %}
You will get an error message if you try to checkout to a new branch while you have not committed changes on the current working branch yet. Please push your changes to the current branch before checking out to another branch.
{% endhint %}

### Retrieve changes from a remote branch

If you are familiar with Git commands, retrieving changes from a remote branch refers here to the `git pull` command. To retrieve changes from a remote branch, go to **Project → Pull** in the Monaca Cloud IDE menu. If there are changes in your remote branch, you will receive those updates in your working branch.

{% hint style="info" %}
When you create a project in the IDE, Monaca keeps all the files in the `www` folder. Files outside of this folder are also synced even though they will not appear in the IDE.
{% endhint %}

### Commit changes to a remote repository

After making changes in the current working branch, you are able to commit them back to your remote repository. To commit your changes, please do as follows:

1. From the Monaca Cloud IDE menu, go to **Project → Commit** .
2. Fill in your commit message and check the files you want to commit. Then, click the **Commit** button.
3. Once you are ready to push the updates to the remote repository, select **Project → Push**. After the push, your remote repository will contain the latest changes made in the Monaca Cloud IDE.

### Show the remote commit history

In order to see the full history of your previous commits in the remote repository, go to **Project → Show Remote History**. You will be redirected to the remote Git service provider’s website showing the commit history of your current branch.

### Show the local commit history

Every commit you make in your Monaca Cloud IDE is called a local commit. You are able to view your local commit history through **Project → Show Commit History**. To view the changes of each commit, click the commit on the left panel.

## Unlink Monaca account from GitHub

To unlink your Monaca account from GitHub, please do as follows:

1. Go to the [Link to GitHub](https://monaca.mobi/en/vcs) page.
2. Click the **Unlink** button.

![](/files/-Mfjq1WX0_OuBTrkNnbG)

## Unable to relink to GitHub

If you accidentally unlink your Monaca account from Github, relinking it with the steps described in [Setup](/products_guide/monaca_ide/version_control/github_integration.md#setup) will not work. You will see the following error:

![](/files/-Mfjqt-9NFepl6vvmk_H)

Therefore, to re-link your account, please do as follows:

1. Logout from the Monaca Cloud IDE.
2. Go to the [Monaca Login](https://monaca.mobi/en/login) page and choose **Sign in with GitHub**.

![](/files/-MfjqMFxHSgVVEg9-gkP)

3\. Fill in your GitHub account information.

4\. Then, you will be redirected to the GitHub’s `Authorize application` page. Click **Authorize application** to proceed.

![](/files/-MfjrAI8m3O7as0fez1c)

5\. After this, your Monaca account should be linked to your GitHub account. You can confirm this on the `Link to GitHub` page. It should look like this:

![](/files/-MfjrNkHSacykNPLqW4n)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://en.docs.monaca.io/products_guide/monaca_ide/version_control/github_integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.