ObsGithubDeployments
CLI tool and wrapper to interact with GitHub deployments, used by the Ansible setup for the deployments of the Open Build Service reference instance.
With ObsGithubDeploymnets you can:
- Get information about the last deployments (history).
- Get the status of the last deployment.
- Lock a deployment.
- Unlock a deployment.
Installation
Add this line to your application's Gemfile:
gem 'obs_github_deployments'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install obs_github_deployments
Usage
Require the gem whenever you need it:
require 'obs_github_deployments'
Most of the commands require the credentials to access the GitHub repository where you are going to track the deployments.
You can obtain the token in GitHub: Settings > Developer Settings > Personal access tokens
.
It is enough to enable repo:status
and repo_deployment
scopes.
You can pass them using the corresponding options/flags as we do in this example:
ogd unlock --repository $GITHUB_REPOSITORY --token $GITHUB_TOKEN
But you could also set them as environment variables in the .env
file taking .env.example
as an example. Doing so you don't need to specify them in the command:
ogd unlock
To know the version of this gem:
ogd -v
You might need to prevent someone to deploy in some conditions: when there is a problem in the reference server, when you need to wait until the maintenace window, to avoid two deployments at the same time, etc. You can lock deployments with:
ogd lock --repository $GITHUB_REPOSITORY --token $GITHUB_TOKEN --reason "Trust me, I have a good reason."
You can unlock a locked deployment at any time with:
ogd unlock --repository $GITHUB_REPOSITORY --token $GITHUB_TOKEN
You can always check whether the deployments are locked or not using:
ogd check-lock --repository $GITHUB_REPOSITORY --token $GITHUB_TOKEN
The commands return a json-formatted outputs that can look like the following examples:
=> {"status":"ok","reason":"Some reason"} # Output of a successful lock
=> {"status":"ok","reason":""} # Output of a successful unlock
=> {"status":"error","reason":"Current deployment is not locked, nothing to do here"} # Output of a failed unlock
=> {"status":"locked","reason":"Some reason"} # Output of check-lock when the deployments are locked
=> {"status":"unlocked","reason":""} # Output of check-lock when the deployments are unlocked
After a deployment, you can mark it as success or failure, using the commands:
ogd succeed --repository $GITHUB_REPOSITORY --token $GITHUB_TOKEN --reason "Everything is up and running"
and
ogd fail --repository $GITHUB_REPOSITORY --token $GITHUB_TOKEN --reason "There were some issues"
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and the created tag, and push the .gem
file to rubygems.org.
With Docker
Run make docker-dev
and you'll be dropped inside a shell with all needed dependencies to build and hack the gem.
Testing
We are using Rspec
in combination with the VCR
gem to test our code. The VCR
gem will mock the GitHub API responses, in order
to have consistent, fast and stable test results.
First time you run spec's that require a "real" API response from GitHub, VCR will record the response and create
a cassette (a .yml
file with the response content) in the spec/cassettes
folder, which is going to mock
the API in future runs of the test. Therefore you need to work with real credentials and GitHub API communication
on the initial test execution.
Important: Since we are working with real credentials and auth tokens, we need to filter them out of the cassettes
before commiting anything to a public repository. You can do so, by using the filter_sensitive_data
option
which replaces the real value with a given string when the cassette is recorded. This is set in the VCR
configuration in the spec/test_helper.rb
file. Please double check the cassettes for any sensible data before commiting them!
Recording the cassettes:
The test_helper.rb
file contains the configuration of VCR
and some helper methods to
use your credentials for the GitHub API by loading them from enviroment variables.
- Rename the
.env.test.example
to.env.test
and fill the enviroment variables in the file accordingly. - Load the enviroment variables by sourcing the the env file
source .env.test
To use VCR
in your tests, simply require the test_helper.rb
file in your specs. There are
different ways to enable mocking through the VCR cassettes in your tests, one of them is just
to enable it in the describe
block:
Example:
RSpec.describe ObsGithubDeployments::Deployment, :vcr do
end
First time you run your test case, it will do a real API call and record the response. Incase
your test case/code changed, you might need to re-record them. Simply delete the corresponding cassette
and VCR
will record a new one for you on the next execution of the test case.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/openSUSE/obs_github_deployments.