Semaph

This is command line shell for interacting with semaphoreci 2.0.

It complements the sem tool with some overlap in responsibilities.

Installation

gem install semaph

Usage

To set up authentication to semaphoreci, you can just follow the instructions to install and setup sem. This will result in your authentication details being written to ~/.sem.yaml.

You should see something like the following in this file:

active-context: foo_semaphoreci_com
contexts:
  foo_semaphoreci_com:
    auth:
      token: qwerty
    host: foo.semaphoreci.com

Now you can run semaph and will be presented with a prompt like one of the following:

 🏗  >

or

 🏗  foo.semaphoreci.com >

This is the first of a series of nested shells. Each shell represents a different context and has different commands available. To see the commands available, execute help and to see the details of a particular command, execute help <command name>. Once you are familar with the commands for each context, you can type the first couple of characters and then hit tab to complete the rest. For some commands you can also tab complete the parameters. Once you enter a shell, return to the previous shell or exit semaph, you can press ctrl-d.

organisations shell

 🏗  >

You will only see this shell if you have multiple sets of credentials in your ~/.sem.yml file.

From this shell, you can list-organisations you are authenticated to and select-organisation to enter a shell for that organisation.

organisation shell

 🏗  foo.semaphoreci.com >

If you have only one set of credentials in ~/.sem.yml then this will be the initial shell.

From here you can list-projects and then select-project to enter a shell for that project.

project shell

 🏗  foo.semaphoreci.com my-app >

From this shell, you will mostly be interested in list-workflows <branch> (where 'branch' is any substring of the git branch you want to see workflows for) and then select-workflow <index> (where 'index' is the number displayed for each workflow list-workflows - tab completion on uuids seemed a bad idea) to enter a shell for that specific workflow.

You can also open-github (opens a web browser for the github project associated with the project) and open-project (opens the semaphoreci project in a browser).

workflow shell

🏗  foo.semaphoreci.com my-app workflowuuid >

From this shell, you can list-pipelines for the selected workflow. These are the builds usually starting from semaphore.yml plus any promotion pipelines that might be executed. You can select-pipeline to monitor what's happening with the pipeline.

You can also open-github-branch, open-github-commit to see the branch/commit in a browser and open-workflow, open-branch to see the semaphore branch/workflow in a browser.

pipeline shell

🏗  foo.semaphoreci.com my-app workflowuuid semaphore.yml >

From this shell, you can list-jobs, poll-jobs, job-log and grep-logs.

Job polling will stop as soon as any one job has failed and send a system notification (as long as terminal-notifier is installed).

You can look at the log for a specific job (by the index presented in list-jobs) using less.

You can grep across all jobs (using ag) with grep-logs which will download the logs for all completed jobs.

You can also open the same browser views in semaphoreci and github from this shell.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test 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 tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/markryall/semaph. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Semaph project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.