GitHub Releases & Notifications
Relevant source files
The following files were used as context for generating this wiki page:
The GitHub Releases & Notifications system in pubm automates the final stages of the software release lifecycle. It manages the creation of GitHub Releases, the uploading of distribution assets, and the generation of Pull Requests for version updates in protected branch environments. By integrating directly with the GitHub REST API, pubm ensures that version bumps are documented with accurate changelogs and that release artifacts are made publicly available.
This system operates within the broader task runner architecture, specifically triggering during the push and release phases of a deployment. It supports various versioning strategies, including single-package, fixed-monorepo, and independent-monorepo modes.
Sources: packages/core/src/tasks/phases/push-release.ts, packages/core/src/tasks/github-release.ts
Release Creation Workflow
The creation of a GitHub Release involves resolving authentication, gathering repository metadata, and interacting with GitHub's API. The system distinguishes between interactive local environments and automated CI environments when handling tokens.
Token Resolution & Interactive Selection
Before a release can be created, a GITHUB_TOKEN must be available. If missing in local mode, the user is prompted with three choices:
- Enter Token: Manually input a personal access token which is then saved for future use.
- Open Draft: Fall back to opening a browser window with a pre-populated release draft URL.
- Skip: Bypasses release creation for the current task.
In CI mode, the system requires the token to be present in the environment variables.
Sources: packages/core/src/tasks/phases/push-release.ts:85-132, packages/core/src/tasks/github-release.ts:47-50
The Release Logic Flow
The following diagram illustrates the internal logic for determining how a release is created based on the environment and available credentials.
The system uses the GitHub REST API to perform these actions, targeting https://api.github.com/repos/{owner}/{repo}/releases.
Sources: packages/core/src/tasks/github-release.ts:74-106, packages/core/src/tasks/phases/push-release.ts:241-260
GitHub Release API Integration
The core logic for API interaction resides in createGitHubRelease. It handles the transition from Git-level tags to GitHub-level release objects.
Content Generation
The system generates the release body using two primary methods:
- Changelog Parsing: If a
CHANGELOG.mdexists, the system parses the specific section corresponding to the new version. - Commit History: If no changelog is provided, it calculates the delta between the new tag and the
previousTag(orfirstCommit), formatting the commit messages into a list with links to issues and specific SHAs.
Sources: packages/core/src/tasks/github-release.ts:23-45, packages/core/src/tasks/phases/push-release.ts:153-171
Data Structures
The following table summarizes the parameters used when creating a release.
| Parameter | Type | Description |
|---|---|---|
tag_name | string | The Git tag (e.g., v1.0.0 or pkg@1.0.0) |
name | string | The display name of the release |
body | string | The markdown content for the release notes |
draft | boolean | If true, the release is created as a draft |
prerelease | boolean | Automatically determined via semver.prerelease() |
Sources: packages/core/src/tasks/github-release.ts:52-106, packages/core/src/tasks/phases/push-release.ts:241-265
Asset Management & Upload Pipeline
pubm supports uploading prepared assets (binaries, archives, etc.) to a GitHub Release once it is created. This is a multi-step process involving file reading and sequential API uploads.
Asset Upload Sequence
Once a release is successfully created, the API returns an upload_url. The system iterates through all PreparedAsset objects, reading the file buffer and posting it to GitHub.
Version Pull Requests (Protected Branches)
In environments where direct pushing to the main branch is restricted (Protected Branches), pubm falls back to creating a "Version PR".
PR Fallback Logic
The pushViaPr utility (triggered in push-release.ts) handles the transition from a failed push to a PR workflow. It creates a new local branch, pushes the version changes to that branch, and then opens a Pull Request back to the target release branch.
- Trigger: Triggered when
ctx.options.createPris true or when a standardgit push --follow-tagsfails. - Rollback: The system registers a rollback task to close the PR and delete the remote branch if subsequent steps fail.
Sources: packages/core/src/tasks/phases/push-release.ts:40-66, packages/core/src/tasks/runner-utils/version-pr.ts
Version Summary Formatting
The PR body and release summaries are formatted according to the monorepo mode:
- Single/Fixed: Shows a unified version bump (e.g.,
v1.2.0). - Independent: Lists every package and its specific version increment in a bulleted list.
Sources: packages/core/src/tasks/phases/version.ts:109-115, packages/core/src/tasks/phases/push-release.ts:285-300
Error Handling & Deletion
The system includes a dedicated deleteGitHubRelease function to facilitate rollbacks. If a release phase fails after the GitHub Release has been created, pubm attempts to delete the remote release using the releaseId stored in the context.
- Class:
GitHubReleaseErrorprovides specific error messages for token requirements, creation failures, and upload timeouts. - API: Uses
DELETEonhttps://api.github.com/repos/{owner}/{repo}/releases/{releaseId}.
Sources: packages/core/src/tasks/github-release.ts:14-16, packages/core/src/tasks/github-release.ts:175-207, packages/core/src/tasks/phases/push-release.ts:199-204
Summary
The GitHub Releases & Notifications module provides a robust bridge between local Git state and the GitHub ecosystem. By handling changelog generation, asset distribution, and PR fallbacks, it ensures that every pubm release is professional, documented, and recoverable. Its ability to fall back to browser-based drafts ensures that releases can proceed even in environments with strict credential management.