Connect Your Own GitHub Repository to Choreo¶
Choreo allows you to either proceed with a Choreo-managed repository or connect your own GitHub repository to maintain the source code of a component when you create any of the following Choreo components:
- REST API
- Manual Trigger
- Scheduled Task
The Choreo-managed repository is in a Choreo-owned GitHub organization that is not accessible to external users. Therefore, it is not ideal for scenarios where multiple developers need to develop a component in collaboration. To overcome this limitation, Choreo provides the capability to connect your own GitHub repository to maintain the source code of a Choreo component you create. This enables multiple developers to work on a particular Choreo component by collaborating via pull requests on a shared repository. Furthermore, this lets developers keep the source repository within their control and adhere to enterprise-specific best practices and development guidelines such as PR checks, code analysis, styling preferences, etc.
This tutorial walks you through the steps to connect your own GitHub repository when creating a component. In this tutorial, you will,
- Create a REST API component and connect it to your own GitHub repository.
- Design the REST API and try it out via the Web Editor.
- Commit the source code of the REST API component to the GitHub repository you connected.
Step 1: Create a project to add the REST API component¶
- Sign in to the Choreo Console at https://console.choreo.dev.
- Expand the Default Project drop-down list and click + Create New.
Enter a unique name and description for your project. In this tutorial, let's use the following values:
Field Value Name COVID-19 Statistics Description Maintain COVID-19 Statistics
Click Create. This takes you to the Components page.
Step 2: Add a REST API component and connect it to your own GitHub repository¶
- On the Components page, click +Create.
- Click the REST API card.
Click Create an API from scratch and enter a unique name and a description for the API. In this tutorial, let's enter the following values:
Field Value Name COVID-19 Statistics Description Retrieve COVID-19 Statistics
- Select Connect your own GitHub repository.
To authorize Choreo to access your GitHub account, click Continue, enter your GitHub credentials, and select one or more repositories to install the Choreo GitHub App.
- The Choreo GitHub App requires the following permission:
- Read and write access to code and pull requests.
- Read access to issues and metadata.
- You can revoke access if you do not want Choreo to have access to your GitHub account. However, write access is only used to send pull requests to a user repository. Choreo will not directly push any changes to a repository.
- The Choreo GitHub App requires the following permission:
Select a GitHub account and a GitHub repository that includes a Choreo GitHub App installation.
Choreo does not allow you to connect GitHub repositories that include existing Ballerina projects.
If a selected repository is already integrated with Choreo to create a component, you cannot reuse it to create another Choreo component.
Click Create to proceed with component initialization. This displays a pull request similar to the following:
Click View Pull Request.
- Review and click Merge pull request, and then click Confirm Merge. When you merge the pull request, it adds the necessary metadata files to connect your GitHub repository to Choreo so that you can proceed to create the component.
- Navigate to the Choreo Console tab to develop the component depending on your requirement.
Step 3: Design the REST API¶
Follow the step-by-step instructions under step 1.3 in the Create Your First REST API tutorial.
Step 4: Run and try out the REST API¶
Follow the step-by-step instructions under step 1.4 in the Create Your First REST API tutorial.
Step 5: Commit the source code of the REST API component to your GitHub repository¶
The REST API component you designed is currently available only in the Web Editor. To allow multiple developers to develop it in collaboration, you must commit the source code of the REST API component to the GitHub repository you connected. Follow these steps:
- Click Sync with Choreo Upstream in the bottom pane of the page.
- In the displayed message, click Sync my changes with Choreo.
In the left pane, enter a commit message (for example,
Implement REST API) and click the tick to commit.
This displays a message requesting you to confirm that you want to stage all your changes and commit them directly.
If you are connecting your own repository to Choreo for the first time, you will see a message requesting you to configure your user name and email address in GitHub. Click Open Git Log, go to the Terminal tab, and run the following commands to configure your username and email address for GitHub commits:
git config --global user.email "<[email protected]>"
git config --global user.name "<Your User Name>"
To push changes to your GitHub repository, click 0↓ 1↑ in the bottom pane.
This icon is displayed only when you complete the commit process.
Once the changes get pushed to the GitHub repository, the bottom pane of the page displays In sync with Choreo upstream.
You have now successfully synced your component source code to your own GitHub repository to allow multiple developers to develop the component in collaboration via pull requests.
Developers can collaborate via any of the following approaches:
- Use the same upstream repository to create a shared component in the same organization, develop, push changes to the respective tracking branch, and eventually send a PR to the main branch.
- Create their forks from the shared upstream repository, connect to individual components, commit, and send PRs to the upstream repository.
Once you collaborate and complete developing the REST API component, you can deploy it and test it. For step-by-step instructions, see steps 2 and 3 in the Create Your First REST API tutorial.Top