Awesome
Ballerina GitHub Connector
GitHub is a widely used platform for version control and collaboration, allowing developers to work together on projects from anywhere. It hosts a vast array of both open-source and private projects, providing a suite of development tools for collaborative software development.
This Ballerina connector is designed to interface with GitHub's REST API (version 2022-11-28), facilitating programmatic access to GitHub's services. It enables developers to automate tasks, manage repositories, issues, pull requests, and more, directly from Ballerina applications.
Setup guide
To use the GitHub Connector in Ballerina, you must have a GitHub account and a Personal Access Token (PAT) for authentication. If you already have a GitHub account, you can integrate the connector with your existing account. If not, you can create a new GitHub account by visiting GitHub's Sign Up page and following the registration process. Once you have a GitHub account, you can proceed to create a PAT.
Step 1: Access GitHub Settings
- Once logged in, click on the profile picture in the top-right corner of the page.
- Select Settings from the dropdown menu.
Step 2: Navigate to Developer Settings
- Scroll down in the sidebar on the left side of the settings page.
- click on Developer settings located near the bottom.
Step 3: Go to Personal Access Tokens
-
Inside Developer Settings find and click on Personal access tokens.
<img src=https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-github/master/docs/setup/resources/1-developer-settings.png alt="GitHub Developer Settings" width="50%">
Step 4: Generate a New Token
- Click on the Generate new token button (you might be asked to enter you password again for security purposes).
Step 5: Configure & Generate the Token
-
Note: Give your token a descriptive name so you can remember it's purpose
-
Expiration: Select the duration before the token expires (e.g., 30 days, 60 days, 90 days, custom, or no expiration).
-
Select Scopes: Scopes control access for the token. Choose what you need the token for (e.g., repo access, user data access). For typical repository operations, selecting
repo
is often sufficient.<img src=https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-github/master/docs/setup/resources/2-generate-token.png alt="Generate new PAT" width="50%">
Quickstart
To use the GitHub
connector in your Ballerina application, modify the .bal
file as follows:
Step 1: Import the connector
Import the ballerinax/github
package into your Ballerina project.
import ballerinax/github;
Step 2: Instantiate a new connector
Create a github:ConnectionConfig
with the obtained PAT and initialize the connector with it.
github:ConnectionConfig gitHubConfig = {
auth: {
token: authToken
}
};
github:Client github = check new (gitHubConfig);
Step 3: Invoke the connector operation
Now, utilize the available connector operations.
Get Private Repositories of Authenticated User
github:Repository[] userRepos = check github->/user/repos(visibility = "private", 'type = ());
Create a Private Repository
github:User_repos_body body = {
name: "New Test Repo Name",
'private: true,
description: "New Test Repo Description"
};
github:Repository createdRepo = check github->/user/repos.post(body);
Examples
The GitHub
connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering use cases like initializing a new project, creating issues, and managing pull requests.
-
Initialize a New GitHub Project - Create a new repository on GitHub, initialize it with a README file, and add collaborators to the repository.
-
Create and Assign an Issue in GitHub - Create a new issue on GitHub, assign it to a specific user, and add labels.
-
Create and Manage a PullRequest in GitHub - Create a pull request on GitHub, and request changes as necessary.
-
Star Ballerina-Platform Repositories - Fetch all repositories under the
ballerina-platform
organization on GitHub and star each of them
Issues and projects
The Issues and Projects tabs are disabled for this repository as this is part of the Ballerina library. To report bugs, request new features, start new discussions, view project boards, etc., visit the Ballerina library parent repository.
This repository only contains the source code for the package.
Build from the source
Prerequisites
-
Download and install Java SE Development Kit (JDK) version 17. You can download it from either of the following sources:
Note: After installation, remember to set the
JAVA_HOME
environment variable to the directory where JDK was installed. -
Download and install Ballerina Swan Lake.
-
Download and install Docker.
Note: Ensure that the Docker daemon is running before executing any tests.
Build options
Execute the commands below to build from the source.
-
To build the package:
./gradlew clean build
-
To run the tests:
./gradlew clean test
-
To build the without the tests:
./gradlew clean build -x test
-
To run tests against different environment:
./gradlew clean test -Pgroups=<Comma separated groups/test cases>
-
To debug package with a remote debugger:
./gradlew clean build -Pdebug=<port>
-
To debug with the Ballerina language:
./gradlew clean build -PbalJavaDebug=<port>
-
Publish the generated artifacts to the local Ballerina Central repository:
./gradlew clean build -PpublishToLocalCentral=true
-
Publish the generated artifacts to the Ballerina Central repository:
./gradlew clean build -PpublishToCentral=true
Contribute to Ballerina
As an open-source project, Ballerina welcomes contributions from the community.
For more information, go to the contribution guidelines.
Code of conduct
All the contributors are encouraged to read the Ballerina Code of Conduct.
Useful links
- For more information go to the
github
package. - For example demonstrations of the usage, go to Ballerina By Examples.
- Chat live with us via our Discord server.
- Post all technical questions on Stack Overflow with the #ballerina tag.