/ 
Dist-Zilla-Plugin-GitHub-CreateRelease-0.0011
⭐ Starred 0 / createrelease.pl

NAME

createrelease.pl - Helper script to create a GitHub Release

VERSION

version 0.0011

SYNOPSIS

This script can be run from the root directory of your distribution, after dzil release has tagged and pushed the release:

It will allow you to create a "GitHub Release" for a version you specify which is helpful if the Dist::Zilla plugin failed for some reason.

createrelease.pl [options]

Options:
  --no-draft             publish the release immediately (default: draft)
  --trial                mark the release as a trial (pre-)release
  --configfile FILE      configuration file to read (default: dist.ini)
  --version VERSION      version of the release

Examples:

# Create a draft release for the most recent git tag
createrelease.pl

# Create a published release for a trial upload
createrelease.pl --no-draft --trial

# Create the release using a standalone configuration file
createrelease.pl --configfile .githubcreaterelease --no-draft

# Create the release for a specific version rather than the latest tag
createrelease.pl --version 2.08

# The same, for a trial release: --trial adds the -TRIAL suffix itself
createrelease.pl --trial --version 2.08

DESCRIPTION

createrelease.pl performs the same task as Dist::Zilla::Plugin::GitHub::CreateRelease, but as a standalone script rather than as part of a dzil release run.

It is intended to be run from the root directory of a distribution after the release has been built, tagged and pushed to GitHub. It:

  1. Reads the [GitHub::CreateRelease] section of the configuration file (dist.ini by default) to obtain its settings.

  2. Determines the version of the release from the most recent git tag, unless a version is given with --version.

  3. Determines the GitHub repository from the URL of the git remote associated with the current branch. If the remote cannot be determined a menu of the configured remotes is presented.

  4. Creates the GitHub Release using the GitHub API, with release notes obtained according to the notes_from setting.

  5. Attaches the CPAN release archive to the GitHub Release. If the archive is not present in the current directory it is downloaded from MetaCPAN.

This is useful when the release was uploaded to CPAN but the GitHub Release was not created - for example when the plugin was not yet configured, or when the plugin failed after the distribution was uploaded.

OPTIONS

--no-draft

Publish the release immediately rather than creating it as a draft.

The release is created as a draft unless this option is given. A draft release is not visible until it is published via the GitHub web page. Note that the draft state is decided entirely by this option: the draft setting in the configuration file has no effect on this script.

In effect --draft is the default option but it is not an option.

--trial

Mark the release as a trial release. The release is created as a GitHub pre-release, TRIAL in the title_template is replaced with "Trial" rather than "Official", and the archive that is attached to the release is the -TRIAL variant, for example Some-Dist-0.0010-TRIAL.tar.gz.

--configfile FILE

The configuration file to read the [GitHub::CreateRelease] settings from. It defaults to dist.ini. Note that dist.ini is always read as well, in order to obtain the name of the distribution.

--version VERSION

The version of the release. If it is not specified the most recently created git tag is used instead.

The value is used everywhere the version of the release is needed: as the tag the release points at, in the title of the release, in the name of the notes file, and in the name of the CPAN archive that is attached. It must therefore match an existing tag in the repository.

Give the version on its own even for a trial release - --trial appends the -TRIAL suffix to the name of the archive itself.

CONFIGURATION

The script reads its settings from the [GitHub::CreateRelease] section of the configuration file, in the same format used by the plugin:

name    = This-Distribution

[GitHub::CreateRelease]
branch = main                   ; default = main
notes_as_code = 1               ; default = 1 (true)
notes_from = ChangeLog          ; default = SignReleaseNotes
notes_file = Changes            ; default = Release-VERSION
github_notes = 0                ; default = 0 (false)
hash_alg = sha256               ; default = sha256
add_checksum = 1                ; default = 1 (true)
org_id = some_id_identifier     ; default = github
title_template = Version RELEASE - TRIAL CPAN release      ; this is the default

The settings have the same meaning as the attributes of the same name documented in Dist::Zilla::Plugin::GitHub::CreateRelease. Only the settings listed above, plus repo, remote_name, draft, trial and sign, are recognised by this script; any other setting in the section causes it to fail on startup.

The draft and trial settings are always overridden by the command line - use --no-draft and --trial to control them.

If a file named .githubcreaterelease exists in the current directory it is used as the configuration file in preference to the file given by --configfile. This allows the settings to be kept separate from dist.ini - for example for a distribution that is not built with Dist::Zilla.

RELEASE NOTES

The notes_from setting determines where the body of the GitHub Release comes from:

SignReleaseNotes

Read from the file named by notes_file, with VERSION in the name replaced by the version of the release. The file is used as-is, since the notes generated by Dist::Zilla::Plugin::SignReleaseNotes already contain the checksum of the archive.

FromFile

As above, but the checksum of the CPAN archive is appended when add_checksum is true.

ChangeLog

Read the entry for the release from the change log named by notes_file using CPAN::Changes. The checksum of the CPAN archive is appended when add_checksum is true.

GitHub::CreateRelease

Use only the checksum of the CPAN archive as the notes.

When notes_as_code is true the notes are wrapped in a GitHub markdown code fence.

GITHUB API AUTHENTICATION

The script uses Config::Identity::GitHub to obtain the GitHub API credentials, and requires a file in your home directory named .github-identity containing:

login github_username OR github_organization
token github_....

The token must be a Personal Access Token with at least "Write" access to "Contents" for the repository. The org_id setting selects a different identity file, so that org_id = project reads ~/.project-identity or ~/.project instead.

An encrypted (.github-identity.asc) identity file is supported and recommended. See "GITHUB API AUTHENTICATION" in Dist::Zilla::Plugin::GitHub::CreateRelease for the full details.

CAVEATS

Unless --version is given, the version is taken from the git tag sorted by tag date, so the tag for the release being published must be the most recently created tag in the repository. Use --version to publish a release for any older tag.

The owner of the repository is taken from the login of the identity file, so a repository owned by another user or organization needs an org_id identity whose login is that owner.

SEE ALSO

Dist::Zilla::Plugin::GitHub::CreateRelease

Dist::Zilla::Plugin::SignReleaseNotes

Config::Identity::GitHub

AUTHOR

Timothy Legge

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Timothy Legge.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.