getReleaseVersion - GitHub Documentation

Code

const axios = require('axios');
const path = require('path');
const { readPropertiesFile, replacePlaceholders } = require('../essential');

/**
 * Fetches a specific release version from a repository.
 *
 * @param {string} org - The organization or user that owns the repository.
 * @param {string} repo - The name of the repository.
 * @param {string} version - The release tag to fetch.
 * @param {string} token - The GitHub personal access token for authentication.
 * @returns {Promise<{ success: boolean, releaseName?: string, releaseTag?: string, releaseURL?: string, message?: string }>} 
 * An object indicating success or failure, with release details if found.
 * * @throws {Error} If the release URL is missing in the configuration.
 */
async function getReleaseVersion(org, repo, version, token) {
    const filePath = path.join(__dirname, 'properties', 'api.properties');
    const config = readPropertiesFile(filePath);

    if (!config.reporeleaseurl) {
        throw new Error("Release URL is missing in the configuration.");
    }

    const replacements = { organization: org, repository: repo };

    try {
        const response = await axios.get(replacePlaceholders(config.reporeleaseurl, replacements), {
            headers: {
                Authorization: `Bearer ${token}`,
                Accept: 'application/vnd.github.v3+json'
            }
        });
        const release = response.data.find(r => r.tag_name === version);

        if (release) {
            return {
                success: true,
                releaseName: release.name,
                releaseTag: release.tag_name,
                releaseURL: release.html_url
            };
        } else {
            return {
                success: false,
                message: `Release ${version} not found.`
            };
        }
    } catch (error) {
        console.error('Error fetching GitHub release:', error.message);
        return {
            success: false,
            message: error.message
        };
    }
}

module.exports = getReleaseVersion;

Usage

/*
    @param org = String
    @param repo = String
    @param version = String
    @param token = String
*/
const { getReleaseVersion } = require('jwz/github');

const org = 'your-org-name';
const repo = 'your-repo-name';
const version = 'v1.0.0';
const token = 'your-github-token';

const res = await getReleaseVersion(org, repo, version, token);
console.log(res);

Explanation

The getReleaseVersion function is a utility for fetching specific release details from a GitHub repository. It uses Axios for making API requests and supports dynamic URL construction. Here's a breakdown:

• Parameters:
  • org: The name of the GitHub organization or user that owns the repository.
  • repo: The name of the repository from which the release details are fetched.
  • version: The tag name of the release to retrieve (e.g., 'v1.0.0').
  • token: A GitHub Personal Access Token (PAT) required for authentication and accessing private repositories.
• Logic:
  • Reads the API endpoint URL from a properties file.
  • Replaces placeholders in the URL with the organization and repository names.
  • Sets the Authorization header with the provided token.
  • Fetches the list of releases from the GitHub API.
  • Finds and returns the release matching the specified version.
• Output:
  • If the release is found:
    • success: true
    • releaseName: Name of the release
    • releaseTag: Tag name of the release
    • releaseURL: URL of the release
  • If the release is not found:
    • success: false
    • message: An error message indicating the release is not found.
• Error Handling:
  • Logs an error message if the API request fails.
  • Returns a failure response with the error message.