Manage GitHub releases and release assets.
Project description
Satsuki (pronounced SAHT-ski) is a Python package that helps manage GitHub releases and release assets. Satsuki is especially useful paired with Continuous Integration/ Continuous Deployment (CI/CD) tools such as Travis CI and AppVeyor.
Why not just use the Travis CI GitHub Releases provider? Good question. The simple answer is that the provider doesn’t work very well yet. In specific, you can’t update an existing release or add files (assets) to a release or provide a release message and a release asset at the same time.
Satsuki and Travis CI Example
This example shows setting up Travis CI with your GitHub OAUTH token for use by Satsuki, and then creating releases and uploading assets.
Step 1: Encrypt OAUTH Token
Using Travis’s command line tool, encrypt your OAUTH token with the environment variable name. NOTE: the encrypt is on a repo by repo basis so the encrypted value will only work on the repo under it was created.
$ cd myrepodir
$ travis encrypt SATS_TOKEN=YOUR_GITHUB_OATH_TOKEN
Please add the following to your .travis.yml file:
secure: "SBKfniOex/LRjHrN/IVQHyKquTxGRY6UxZhrPd1fMsFHu+1Jl8GGkMX8wZ8GL29S0GgIZwDVHBwu3kVcX0xJWmRrLf9kcUrN5RdbTn7KxAxqboJKLolJqXhbSE1pZBUm1IbY3BuL0hZ4oYg8KyuARnanF0PXjpJTFysYq9cYwolc4XzZ0EOXRNCSBLkcIUsULhunFHPKxaATEwUMgnOIYHkBMdfjVynuW1hqhgwAstpfhNvryir6vbZla7M3/EBTqJjuGhXTf1U6YWubGFBXNDwqIqRurMHRC0pyqc/NpEUhgFANTqs3ax/Ka0cnZAxoq99rPWe9ZtElN/GKrjJT6STPjfsaCC6ls3JFC0aorEuMMH+2pqEr7p3Llbs1OkBnZKD7aTNQxmMimZ78yq6snSM5zew9Nxjv0lytZOpHQXFtjXJtc8YcXcWylYSngMnRVnPzxFADn4udNdFZzP8+HZEkkKHJXaICu0Vx15ll4tEo1I2BJQ/ViV4sjo6KfAL3ZqC6RTjs2aqnMHu7i8DrQzYlmRXsKr2HyVudN3cgAgK5cZkJArCjxu8glY5OrFvSxjKOF1tno8Zrhne6xyBcQfVXP7gqQYQ/sUx1dqTc7XPqkB4r4OkmXH+Af7jRQahQxk04+vahtrKJX4WEYeA4teOAYN2xWsbvdrCcIvgUXNx="
Step 2: Add Token to Travis YAML
Now, we’ll add this secure value to the .travis.yml file in our repo. Only Travis CI can decrypt this value now. (Although this shows Python as the language, Satsuki will work with projects in other languages as long as you install Python 3 and pip.)
language: python
sudo: false
env:
global:
- secure: SBKfniOex/LRjHrN/IVQHyKquTxGRY6UxZhrPd1fMsFHu+1Jl8GGkMX8wZ8GL29S0GgIZwDVHBwu3kVcX0xJWmRrLf9kcUrN5RdbTn7KxAxqboJKLolJqXhbSE1pZBUm1IbY3BuL0hZ4oYg8KyuARnanF0PXjpJTFysYq9cYwolc4XzZ0EOXRNCSBLkcIUsULhunFHPKxaATEwUMgnOIYHkBMdfjVynuW1hqhgwAstpfhNvryir6vbZla7M3/EBTqJjuGhXTf1U6YWubGFBXNDwqIqRurMHRC0pyqc/NpEUhgFANTqs3ax/Ka0cnZAxoq99rPWe9ZtElN/GKrjJT6STPjfsaCC6ls3JFC0aorEuMMH+2pqEr7p3Llbs1OkBnZKD7aTNQxmMimZ78yq6snSM5zew9Nxjv0lytZOpHQXFtjXJtc8YcXcWylYSngMnRVnPzxFADn4udNdFZzP8+HZEkkKHJXaICu0Vx15ll4tEo1I2BJQ/ViV4sjo6KfAL3ZqC6RTjs2aqnMHu7i8DrQzYlmRXsKr2HyVudN3cgAgK5cZkJArCjxu8glY5OrFvSxjKOF1tno8Zrhne6xyBcQfVXP7gqQYQ/sUx1dqTc7XPqkB4r4OkmXH+Af7jRQahQxk04+vahtrKJX4WEYeA4teOAYN2xWsbvdrCcIvgUXNx=
Step 3: Setup the Travis YAML Script Step
We’ll use the script step to build an application into a OS- machine specific binary using GravityBee.
install:
- pip install gravitybee satsuki
script:
- gravitybee --src-dir src --verbose --clean
Step 4: Setup the Travis YAML Before Deploy Step
Here assign values to environment variables so that Satsuki can use them to create the release and we’ll tag the release.
before_deploy:
- export SATS_TAG=$(grep "version = " $TRAVIS_BUILD_DIR/setup.cfg | sed "s/version = //")
- export SATS_BODY="* Here is the message for the release"
- export SATS_FILE="mysuperapp-1.2.3-standalone-linux-x86_64"
- git tag -a $SATS_TAG -m "This is the v$SATS_TAG message"
Step 5: Setup the Travis YAML Deploy Step
Everything should be set now to deploy.
deploy:
- provider: script
script: satsuki
skip_cleanup: true
on:
branch: master
repo: YakDriver/mysuperapp
python: "3.6"
Now if you’ve enabled your repo on Travis CI, when you commit to the master branch, if all goes well, you’ll get a release with your binary file associated with it.
Reference
Satsuki can be used with command line (CL) options or environment variables, or a mix of both. If both are provided, command line options take precedence.
Options
Using Satsuki, you can create releases. A release is a GitHub feature. However, a release is related to a tag, which is a pure Git feature. (If the tag doesn’t exist, Satsuki will create it along with the release.) You can also create assets (e.g., binary files) that are associated with releases. Thus Satsuki has options that relate to each: Asset ==> Release ==> Tag.
Options from each, tag, release, and asset, can be provided at once, and Satsuki will attempt to act appropriately on each. For example, in one command you can create a tag, release, and asset.
If an environment variable is used as a flag, the existence of the environment variable is sufficient to trigger the flag. It can be set to any value.
The Files File
Satsuki also accepts a JSON-formatted file containing information about assets to be uploaded (see the --file-file option above). The file can contain information about multiple files and should contain information about files accessible to Satsuki, with paths relative to the directory in which Satsuki is run. A file in the correct format is generated by GravityBee.
This is an example of the format.
[{'filename': 'gbtestapp-4.2.6-standalone-osx-x86_64',
'label': 'gbtestapp Standalone Executable (gbtestapp-4.2.6-standalone-osx-x86_64) [GravityBee Build]',
'mime-type': 'application/x-executable',
'path': '/path/to/file/gbtestapp-4.2.6-standalone-osx-x86_64'}]
Examples
This command will delete all tags not connected to a release that match the pattern Test-*.
$ satsuki -s "<OWNER>/<REPO>" --token <YOUR_GITHUB_OATH_TOKEN> \
--tag Test-* -c delete -v
Delete the release asset with the filename release-asset.exe from the release tagged with Test-ve8226c.
$ satsuki -s "<OWNER>/<REPO>" --token <YOUR_GITHUB_OATH_TOKEN> \
--tag Test-ve8226c -c delete -v --file release-asset.exe
Create a new release and tag called testtag based on the given commit SHA, and upload the file release-asset.exe as an asset of the new release.
$ satsuki -s "<OWNER>/<REPO>" --token <YOUR_GITHUB_OATH_TOKEN> \
--tag testtag --commitish 42b8b9f3f44e0a11071cd3c56eaed29a305c3339 \
-v --file release-asset.exe
Delete the release called 1.2.3.
$ satsuki -s "<OWNER>/<REPO>" --token <YOUR_GITHUB_OATH_TOKEN> \
--tag 1.2.3 -c delete -v
Delete the release and local and/or remote tags called 1.2.3.
$ satsuki -s "<OWNER>/<REPO>" --token <YOUR_GITHUB_OATH_TOKEN> \
--tag 1.2.3 -c delete -v --include-tag
Delete ALL releases and local and/or remote tags matching Test-*. USE CAUTION!
$ satsuki -s "<OWNER>/<REPO>" --token <YOUR_GITHUB_OATH_TOKEN> \
--tag Test-* -v -c delete --include-tag --force
The First Confirmed Upload SHA
25c2f15b0c332bf58d5e625f54525873bcddc2083578b335fdc4a1be8d79edda
CHANGE LOG
0.1.6 - 2018.05.10
[BUG FIX] Wasn’t deleting release asset if file given that didn’t exist locally.
[ENHANCEMENT] Added –force option to delete tags and releases using pattern matching.
0.1.5 - 2018.05.10
[BUG FIX] Implemented file (release asset) delete
[ENHANCEMENT] Generally improved asset handling including SHA256 sums for files and better error handling
0.1.4 - 2018.05.08
[BUG FIX] Looked like an error was occuring because returning True instead of os.EX_OK.
0.1.3 - 2018.05.07
[ENHANCEMENT] Added POSIX-style filename pattern matching for cleaning up tags.
0.1.2 - 2018.05.07
Initial release!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for satsuki-0.1.6-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5c121d570fdc44c3b15b95d099c0e78e1954280603ae71782821130993ca4d7c |
|
MD5 | 9a2b8f7ac4303ae9a2ad4798d7befa8c |
|
BLAKE2b-256 | 052ce38f5efc41e8b3b3aecad8a3dd1e5e1ae12a499eb8ede8fe55ecd251459a |