The GitHub Integration feature allows you to create branches and utilize workflows like GitHub Flow for managing your API design process.
In case you prefer pictures rather than words check our video tutorial.
After syncing your API with GitHub, you will see a new button on the editor labeled “New Branch”. When clicked, this button will do the following:
- Ask you what you would like to name your branch
- Create that branch on GitHub
- Create a local branch API on Apiary
After this is complete, Apiary will now be pushing to and pulling from that specific branch in your synced repository.
Additionally, you may branch from other branches, not just the default branch. This allows you to set up a branch hierarchy of your choice that suits your team’s workflow. Simply click the “New Branch” button on any branch to use this.
Switching Between Branches
You will see a branch API selector on the editor screen that allows you to quickly switch between existing branches in Apiary.
Apiary will only push commits to GitHub when you are ready to do so. Until you are, you can click the “Save” button on the editor, which will save your API Project on Apiary only. The “Save” button stores your changes for the branch only, leaving all other branches in Apiary unchanged.
Pushing to GitHub
Once you are ready to make changes on GitHub, you can click the “Push” button on the editor. This will do the following:
- It will save your API Project if you have not done so already
- It will prompt you to enter a commit message
- Once entered and submitted, it will push that change to the branch
You can change your email Apiary uses for commits on the user settings page.
We have a dedicated section on troubleshooting GitHub Sync.
Pulling from GitHub
Apiary will listen to only the branches that you have set up in Apiary, and not all branches in a repo. When a change is made on a branch API that is in Apiary, that change will be pulled down.
It is important to note that if a change is made on GitHub that results in an invalid API Description file, those changes will not be pulled down to Apiary.
Apiary listens for any change to a branch, including a merge from another branch.
Opening Pull Request
Once you are ready to merge your changes to another branch, you can click the “Pull Request” button. This will take you directly to GitHub, where you will use their normal pull request form for opening a new request.
Deleting a branch
We are not synchronizing the state of branches in GitHub, so if you delete a branch in your GitHub repository, we don’t delete your branch in Apiary. If you want to delete a branch in Apiary, switch to the branch from the editor, go to the API Project settings for that branch and delete your branch from there.
If you delete branch in GitHub, and then try to push to it from Apiary, it will be recreated in GitHub.
If you add a viewer or an editor to the API Project using branches, they will get access to all branches. In a same way, if you remove user from one branch, user is losing access to all current and future branches.