Add release/build CLI tool

kinbiko commented 2 years ago

What problem are you trying to solve?

Reporting new versions of an(y) application, incl. source control data so that stackframes in the Bugsnag dashboard are clickable with permalinks to GitHub, and all the other goodies that only work when you report release info to Bugsnag.

Describe how you wish this package would help you solve the problem

Provide both a library and a command line tool that lets users send this data to Bugsnag's build API.

Library

Public types allowing other tools or applications written in Go to take advantage of the API types, validation, and HTTP reporting logic of this package. Should be a separate package to the notifier to avoid confusion among users of the notifier. Consider whether it should be another module as well.

Command line tool

It's not unlikely that other APIs provided by Bugsnag could be useful in the future, so let's consider creating a bugsnag binary that lets you (for now) send release data to the Build API using the following syntax:

$ bugsnag release \
    --api-key=$SOME_API_KEY           # required. Reads $BUGSNAG_API_KEY by default \
    --app-version=$SOME_SEMVER        # required. Reads $BUGSNAG_APP_VERSION, then $APP_VERSION by default \
    --release-stage=$SOME_STRING      # optional. "production" by default. Explicitly set to "" to report a build instead of a release \
    --provider=$SOME_STRING           # optional. Value "github" if $GITHUB_ACTIONS is "true" \
    --repository=$SOME_STRING         # optional. URL based off of $GITHUB_REPOSITORY if $GITHUB_ACTIONS is "true" \
    --revision=$SOME_STRING           # optional. $GITHUB_SHA if $GITHUB_ACTIONS is "true" \
    --builder-name=$SOME_STRING       # optional. Value of $GITHUB_ACTOR if $GITHUB_ACTIONS is "true", otherwise value of `whoami` \
    --metadata=$KEY_VALUE_PAIRS       # optional. Format is "KEY1=VALUE1,KEY2=VALUE2" \
    --auto-assign-release=$SOME_BOOL  # optional. "false" by default \
    --endpoint=$SOME_URL              # optional. Set to the on-prem installation of Bugsnag if applicable \
    --app-version-code=$SOME_NUMBER   # optional. Applies to Android only \
    --app-bundle-version=$SOME_SEMVER # optional. Applies to Apple platforms only

Sub-tasks

[x] Create JSON* types in github.com/kinbiko/bugsnag/builds
[x] Add validation logic to a JSONBuildRequest, plus tests.
[x] Add a HTTP request maker type, plus tests.
[x] Add and integrate a CLI binary in github.com/kinbiko/bugsnag/cmd/bugsnag that:
- Reads the flags and builds a JSONBuildRequest ignoring any defaults for now.
- Validates the request
- Calls the Bugsnag Build API
- Logs any errors or success messages, and returns an appropriate status code
- Add integration testing
[x] Support defaults for flags, incl. documentation and test updates.
- [x] api-key
- [x] app-version
- [x] release-stage
- [x] ~~provider~~
- [x] ~~repository~~
- [x] ~~revision~~
- [x] ~~builder-name~~
[x] Verify only the bare minimum is exposed in the builds package.
[x] Update README to mention this tool

kinbiko commented 2 years ago

We could do some additional inferences for the case when the tool is being used locally:

app-version can be the latest tag, assuming it's semver, and that the latest commit is the commit tagged.
provider can be identified as github by git config --get remote.origin.url (and others other than github too, but we can make that scope a "PRs welcome" feature).
revision can easily be found by git rev-parse HEAD
builder can still be found with whoami

kinbiko commented 2 years ago

`AppVersion` validation

Design decision:

The notifier asserts that the app version should follow semantic versioning because Go highly encourages its use, but seeing as the command line application could be used for non-Go projects (e.g. it supports the notion of version codes and bundle versions) I'm making the conscious decision to not be consistent with the validation requirements for the notifier, and only checking for presence (and not valid semver) for this tool.

kinbiko commented 2 years ago

GitHub actions related defaults

Initially I planned on populating defaults in case this application was used in a GitHub action, but in hindsight, this poses a question around how to disable this logic, since these environment variables aren't usually something the user controls. Of course, we could have a "disable" env var or flag, but that doesn't seem right to me. Also, this functionality would tie this program to GitHub actions unnecessarily, so instead I'm choosing to not include GitHub actions related defaults at all.

kinbiko / bugsnag