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

1. Once logged in, click on the profile picture in the top-right corner of the page.
2. Select Settings from the dropdown menu.

Step 2: Navigate to Developer Settings

1. Scroll down in the sidebar on the left side of the settings page.
2. click on Developer settings located near the bottom.

Step 3: Go to Personal Access Tokens

1. Inside Developer Settings find and click on Personal access tokens.

   

Step 4: Generate a New Token

1. 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.

  

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.

1. Initialize a New GitHub Project - Create a new repository on GitHub, initialize it with a README file, and add collaborators to the repository.

2. Create and Assign an Issue in GitHub - Create a new issue on GitHub, assign it to a specific user, and add labels.

3. Create and Manage a PullRequest in GitHub - Create a pull request on GitHub, and request changes as necessary.

4. 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

1. Download and install Java SE Development Kit (JDK) version 17. You can download it from either of the following sources:

   • Oracle JDK
   • OpenJDK

   Note: After installation, remember to set the JAVA_HOME environment variable to the directory where JDK was installed.

2. Download and install Ballerina Swan Lake.

3. 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.

1. To build the package:

   ./gradlew clean build

2. To run the tests:

   ./gradlew clean test

3. To build the without the tests:

   ./gradlew clean build -x test

4. To run tests against different environment:

   ./gradlew clean test -Pgroups=<Comma separated groups/test cases>

5. To debug package with a remote debugger:

   ./gradlew clean build -Pdebug=<port>

6. To debug with the Ballerina language:

   ./gradlew clean build -PbalJavaDebug=<port>

7. Publish the generated artifacts to the local Ballerina Central repository:

   ./gradlew clean build -PpublishToLocalCentral=true

8. 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.