Package: release-bot
Release botAutomate releases on Github and PyPi.DescriptionThis is a bot that helps maintainers deliver their software to users. It is meant to watch github repositories for
release pull requests. The PR must be named in one of the following formats:0.1.0 releaseif you want to create the "0.1.0" upstream releasenew major release, release-bot would then initiate a release from e.g. "1.2.3" to "2.0.0"new minor releasee.g. "1.2.3" to "1.3.0"new patch releasee.g. "1.2.3" to "1.2.4"Release-bot now works withSemVeronly.
Once the PR is merged, bot will create a new Github release and a PyPi release respectively.
Changelog will be pulled from root of the
repository and must be namedCHANGELOG.md. Changelog for the new
version must begin with version heading, i.e# 0.1.0.
Everything between this heading and the heading for previous version will be pulled into the changelog.Alternatively, you can let the bot do the boring work, update__version__variable and fill changelog with commit messages from git log.
You can trigger this action by creating an issue and name it the same as you would do for a release PR, e.g.0.1.0 release,new major release,new minor release,new patch release.
All you have to do after that is merge the PR that the bot will make.The bot works withpypa/setuptools_scmplugin. If
you're using it, you don't need to care about__version__at all. You can be
also sure that the bot will make the PyPI release correctly — before it
releases the software, it checks out the tag in the git repo.Arelease-conf.yamlfile is required. SeeConfigurationsection for details.Once a Github release is complete, bot will upload this release to PyPI.
Note that you have to setup your login details (seeRequirements).Try it locally$ pip install release-botOther possible installations are throughDocker,OpenShift,Arch User Repository.First interaction with release bot may be automated releases on Github. Let's do it.1. Create upstream repository or use existing oneThis is meant to be upstream repository where new releases will be published.Within upstream repository createrelease-conf.yamlfile which contains info on how to release the specific project.
Copy and editrelease-conf.yaml.At the end ofrelease-conf.yamladd this line of code:# whether to allow bot to make PRs based on issuestrigger_on_issue:trueFor possible advanced setup checkthe documentation for an upstream repository.2. Createconf.yamlCreate configuration fileconf.yaml. You can useonefrom this repository. You will need to generate aGithub personal access token.
Recommended permissions for access token are:repo,delete_repo,user.At the end ofconf.yamladd this line of code:# Name of the account that the github_token belongs to# Only needed for triggering the bot on an issue.github_username:<your_github_username>Note: This fileshould notbe stored in upstream repository as it contains sensitive data.For possible advanced setup checkthe documentation for a private repository.
Also, seerequirementsin case you want include PyPi releases.3. Run release-botAt this point, release-bot is installed. At least two configuration files are setrelease-conf.yamlandconf.yaml(optionally.pypirc).Launch bot by a command:$ release-bot -c <path_to_conf.yaml> --debugYou can scroll down and see debug information of running bot.4. Make a new releaseCreate an issue having0.0.1 releaseas a title in your upstream repository. You can select your own version numbers.Wait for the bot to make a new PR based on this issue (refresh interval is set inconf.yaml).Once the PR is merged bot will make a new release.Check release page of your upstream repository at GitHub and you should see new release0.0.1.Since now, feel free to create releases automatically just by creating issues.DocumentationConfigurationThere are two yaml configuration files:conf.yaml-- a config for the bot itself with some sensitive data (recommended to store in private repo)release-conf.yaml-- stored in upstream repository and contains info on how to release the specific project.Private repositoryYou need to setup a git repository, where you'll store  theconf.yamland.pypircfiles.
If this is not a local repository, make sure it's private so you prevent any private info leaking out.
If the path toconf.yamlis not passed to bot with-c/--configuration,
bot will try to find it in current working directory.Here are theconf.yamlconfiguration options:OptionDescriptionRequiredrepository_nameName of your Github repositoryYesrepository_ownerOwner of the repositoryYesgithub_tokenGithub personal access tokenYesgithub_usernameName of the account that thegithub_tokenbelongs to. Only needed for triggering the bot on an issue.Nogithub_app_installation_idInstallation ID (a number) of the Github app.Nogithub_app_idID (a number) of the Github app.Nogithub_app_cert_pathPath to a certificate which Github provides as an auth mechanism for Github apps.Norefresh_intervalTime in seconds between checks on repository. Default is 180Noclone_urlURL used to clone your Github repository. By default,httpsvariant is used.NoSample config namedconf.yamlcan be found in this repository.Regardinggithub_token, it's usually a good idea to create a Github account for the bot
(and use its Github API token)
so you can keep track of what changes were made by bot and what are your own.You can also create a Github app and use it as an authentication mechanism for
the bot. For that you need to specify the three config values prefixed withgithub_app.Note:If the Upstream repository is aPrivate Github repository, it is required to specify the SSH URL
of the repository as theclone_urloption inconf.yaml. This will allow the bot to authenticate using SSH, when fetching from the Upstream repository.Upstream repositoryYou also have to have arelease-conf.yamlfile in the root of your upstream project repository.
Here are possible options:OptionMeaningRequiredchangelogList of changelog entries. If empty, changelog defaults to$version releaseNoauthor_nameAuthor name for changelog. If not set, author of the merge commit is usedNoauthor_emailAuthor email for changelog. If not set, author of the merge commit is usedNopypiWhether to release on pypi. True by defaultNopypi_projectName of your PyPI repositoryNotrigger_on_issueWhether to allow bot to make PRs based on issues. False by default.NolabelsList of labels that bot will put on issues and PRsNoSample config namedrelease-conf-example.yamlcan be found in this repository.RequirementsAre specified inrequirements.txt.
You have to setup your PyPI login details in$HOME/.pypircas described inPyPI documentation.Docker imageTo make it easier to run this, release-bot is available as ansource-to-imagebuilder image.You can then create the final image like this:$ s2i build $CONFIGURATION_REPOSITORY_URL usercont/release-bot app-namewhere $CONFIGURATION_REPOSITORY_URL is link to repository with conf.yaml and .pypirc files.To test it locally, you can the run the final image like this:$ docker run <app-name>once all changes, configuration files exist in GitHub and git repository contains needed files,
you can try to create an issue  in your GitHub repository with string like "X.Y.Z release"
and you can see log like this:$ docker run meta-test-family-bot
---> Setting up ssh key...
Agent pid 12
Identity added: ./.ssh/id_rsa (./.ssh/id_rsa)
11:47:36.212 configuration.py  DEBUG  Loaded configuration for fedora-modularity/meta-test-family
11:47:36.212 releasebot.py     INFO   release-bot v0.4.1 reporting for duty!
11:47:36.212 github.py         DEBUG  Fetching release-conf.yaml
11:47:51.636 releasebot.py     DEBUG  No merged release PR found
11:47:52.196 releasebot.py     INFO   Found new release issue with version: 0.8.4
11:47:55.578 releasebot.py     DEBUG  No more open issues found
11:47:56.098 releasebot.py     INFO   Making a new PR for release of version 0.8.5 based on an issue.
11:47:57.608 utils.py          DEBUG  ['git', 'clone', 'https://github.com/fedora-modularity/meta-test-family.git', '.']
...OpenShift templateYou can also run this bot in OpenShift usingopenshift-template.ymlin this repository.
You must set two environment variables, the$APP_NAMEis the name of your release-bot deployment,
and$CONFIGURATION_REPOSITORYwhich contains configuration for the release-bot.
The contents of the repository are describedabove.
Note that if you use private repository (which youabsolutelyshould),
you will need to set up a newOpenShift secretnamedrelease-bot-secretto authenticate. It can be a ssh private key that you can use to access the repository
(for GitHub seedeploy keys).
Here's anguideon
how to do that in OpenShift GUI, or anotherguidethat usesoccommandline tool.By default, the release-bot builder image won't update itself when a
new version of this image is pushed to docker hub.
You can change it by uncommenting lines with#importPolicy:and#scheduled: trueinopenshift-template.yml.
Then the image will be pulled on a new release.Arch User RepositoryFor Arch or Arch based Linux distributions, you can install the bot from theAUR Package.
You can use your favourite AUR Helper to install the package. For instance:$ aurman -S release-botYou can also install it by using thePKGBUILDfrom the AUR repository.
To build the package, download the PKGBUILD and exectute:$ makepkg -cs #c flag cleans the extra remaining source and compiled files. s flag installs the dependencies if you don't have it.To install the package execute,$ sudo pacman -U release-bot-...tar.xzContributingIf you are interested in making contribution to release-bot project, please readContribution guidefor more information.