# GitHub Integration





<iframe width="100%" height="400" src="https://www.youtube.com/embed/oHyOIIX4ecY" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" style="{ borderRadius: &#x22;0.5rem&#x22; }" />

Integrating GitHub with your Ideavo project gives you full version control, collaborative workflows, and the freedom to deploy your code anywhere.

## Benefits [#benefits]

<Cards>
  <Card title="Version History & Backup" icon="<IoIosGitBranch />" description="All code is tracked with Git. Review diffs, revert to previous states, and rely on GitHub as an external backup." />

  <Card title="Team Collaboration" icon="<RiTeamFill />" description="Code lives on GitHub — enabling reviews, comments, and contributions via pull requests." />

  <Card title="Workflow Integration" icon="<FcWorkflow style={{ filter: &#x22;grayscale(100%)&#x22; }} />" description="Use branches, pull requests, issues, and CI/CD pipelines alongside Ideavo." />

  <Card title="Deployment Flexibility" icon="<AiOutlineDeploymentUnit />" description="Deploy anywhere. Your code is always available on GitHub regardless of how you deploy." />
</Cards>

## Setting Up GitHub [#setting-up-github]

<DocVideo src="features/github/git-flow" alt="The GitHub panel from no repository linked, through creating boardly and the connected panel, to pressing Push Changes, committing a message and seeing Pushed successfully" width="1000" height="560" maxWidth="800" />

### 1. Connect Your GitHub Account [#1-connect-your-github-account]

<Steps>
  <Step>
    Click the **GitHub icon** in the top-right of your project to begin
    authorization.
  </Step>

  <Step>
    In the popup, click 

    **Connect**

    .
  </Step>

  <Step>
    Authorize Ideavo on GitHub — sign in, review the requested permissions, and
    grant repository access.
  </Step>
</Steps>

### 2. Create a Repository [#2-create-a-repository]

Once your GitHub account is connected, you'll see the disconnected state — the GitHub component with a **blue logo** indicating your account is linked but no repository has been created or attached yet.

Click **Create** to set one up. You'll be prompted to enter a name for the new GitHub repository.

<Callout type="warn">
  Always use a **unique repository name**. If the name already exists in your
  account or organization, the creation will fail with an error. When in doubt,
  add a project-specific suffix.
</Callout>

### 3. You're Connected [#3-youre-connected]

Once the repository is created and linked, the GitHub component updates to the connected state. You're ready to push and pull changes.

<DocImage src="features/github/repository-connected" alt="The GitHub panel showing the linked repository, remote, active branch and Push Changes" width="764" height="728" />

## Pushing & Pulling Changes [#pushing--pulling-changes]

### Pushing Changes [#pushing-changes]

When there are uncommitted changes in your project, the GitHub component will show a **Push Changes** option — visible in the connected state above. Click it to open the commit dialog.

<DocImage src="features/github/commit-message" alt="The Commit & Push form in the GitHub menu with a commit message entered and a Commit button" width="764" height="464" />

Enter a commit message describing your changes and confirm to push them to your GitHub repository.

### Pulling Changes [#pulling-changes]

When there are upstream changes on GitHub that aren't reflected in your project, a **Pull Changes** option will appear in the same component. Click it to bring in the latest commits from your repository.

<Callout type="info">
  If your project looks out of sync, use the **Pull Changes** button to manually
  fetch the latest state from GitHub.
</Callout>

### Conflict Handling [#conflict-handling]

If edits are made in both Ideavo and directly on GitHub at the same time, Ideavo prefers the local state over incoming GitHub changes. To avoid conflicts, pull before making significant changes when collaborating with others.

## Branch Management [#branch-management]

The active branch is displayed in the GitHub component. You can:

* **Switch branches** — click the branch name to see existing branches and switch to any of them
* **Create a new branch** — click the branch button to open the new branch dialog and name your branch

<Callout type="info">
  Branch operations can also be performed directly from inside the **IDE**
  without opening the GitHub component.
</Callout>

Ideavo tracks whichever branch is active. Changes pushed from Ideavo go to that branch, and incoming changes are pulled from it.

## Disconnecting [#disconnecting]

To unlink your repository, open the GitHub component in the connected state and click the **three vertical dots** in the top-right corner. Select **Disconnect** to remove the link between your Ideavo project and the GitHub repository.

Disconnecting does not delete your GitHub repository — it only removes the connection within Ideavo.

### FAQ [#faq]

<Accordions>
  <Accordion title="What permissions does Ideavo request on GitHub?">
    Ideavo requests repository read and write access to create repositories,
    push commits, and read branch information. You can review the exact
    permissions during the GitHub OAuth authorization step.
  </Accordion>

  <Accordion title="Can I connect to an organization repository?">
    Yes. During the authorization flow, you can grant Ideavo access to your
    personal account or one or more of your GitHub organizations. When creating
    a repository, you'll be able to choose which account or org it belongs to.
  </Accordion>

  <Accordion title="What happens to my existing code when I first connect?">
    When you create a new repository from Ideavo, your current project code is
    pushed to it as the initial commit. If you're linking to an existing
    repository, Ideavo will sync with the default branch.
  </Accordion>

  <Accordion title="Why can't I see the push, pull, or branch options?">
    These controls are only available to project owners and editors. If you're
    accessing a project as a **Viewer**, GitHub sync and branch management
    options will not be visible.
  </Accordion>

  <Accordion title="What happens if the GitHub repository is deleted?">
    If the linked repository is deleted on GitHub, the connection will break.
    You can reconnect by creating a new repository from the GitHub component
    inside Ideavo.
  </Accordion>

  <Accordion title="Can I reconnect after disconnecting?">
    Yes. Disconnecting only removes the link — your project and code in Ideavo
    remain intact. You can create a new repository or link to an existing one at
    any time from the GitHub component.
  </Accordion>
</Accordions>
