{"id":24506169,"url":"https://github.com/pvdb/git-semaphore","last_synced_at":"2025-04-14T07:08:48.526Z","repository":{"id":5036985,"uuid":"6196409","full_name":"pvdb/git-semaphore","owner":"pvdb","description":"git integration with https://semaphoreci.com","archived":false,"fork":false,"pushed_at":"2019-07-10T09:49:43.000Z","size":139,"stargazers_count":11,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-14T07:08:43.859Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"CyanogenMod/android_device_htc_m7vzw","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pvdb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-10-12T21:12:02.000Z","updated_at":"2019-07-10T09:49:42.000Z","dependencies_parsed_at":"2022-08-20T22:30:25.651Z","dependency_job_id":null,"html_url":"https://github.com/pvdb/git-semaphore","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvdb%2Fgit-semaphore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvdb%2Fgit-semaphore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvdb%2Fgit-semaphore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvdb%2Fgit-semaphore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pvdb","download_url":"https://codeload.github.com/pvdb/git-semaphore/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248837281,"owners_count":21169374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-21T23:33:23.943Z","updated_at":"2025-04-14T07:08:48.501Z","avatar_url":"https://github.com/pvdb.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Git::Semaphore\n\n[![Build Status](https://semaphoreci.com/api/v1/pvdb/git-semaphore/branches/master/badge.svg)](https://semaphoreci.com/pvdb/git-semaphore)\n\n[![Travis CI](https://travis-ci.org/pvdb/git-semaphore.svg?branch=v0.0.6)](https://travis-ci.org/pvdb/git-semaphore)\n\nIntegrate git repositories with their corresponding project on [semaphoreci.com][] _(via the Semaphore API)_\n\n## Features\n\n* highly opiniated\n* integrated with `git`\n* caching of API results\n* pagination of API calls\n* enrichment of API data\n* extensive API feature support\n* support for multiple Semaphore accounts\n\n## Semaphore API support\n\nThe following sections of the [Semaphore API][] are fully or partially supported by `git semaphore`:\n\n| API section        |    | summary |\n|--------------------|----|---------|\n| [authentication][]      | ✅ | API authentication                    |\n| [projects][]            | ✅ | listing projects                      |\n| [branches and builds][] | ✅ | querying branches and managing builds |\n| [servers and deploys][] | ❌ | querying servers and managing deploys |\n| [webhooks][]            | ❌ | listing and managing webhooks         |\n\n[authentication]:      https://semaphoreci.com/docs/api_authentication.html\n[projects]:            https://semaphoreci.com/docs/projects-api.html\n[branches and builds]: https://semaphoreci.com/docs/branches-and-builds-api.html\n[servers and deploys]: https://semaphoreci.com/docs/servers-and-deploys-api.html\n[webhooks]:            https://semaphoreci.com/docs/webhooks-api.html\n\nThe following [Semaphore API][] features are supported by `git semaphore`:\n\n| API feature      |    | command |summary |\n|------------------|----|---------|--------|\n| [authentication][]    | ✅ |                               | provide user authentication via an authentication token            |\n| [projects][]          | ✅ | `git semaphore --projects`    | list all projects and their current status                         |\n| [project branches][]  | ✅ | `git semaphore --branches`    | list all branches for the current project                          |\n| [branch status][]     | ✅ | `git semaphore --status`      | list the build status for the current branch                       |\n| [branch history][]    | ✅ | `git semaphore --history`     | list the build history for the current branch                      |\n| [build information][] | ✅ | `git semaphore --information` | detailed information for a given build number _(ie. all commits)_  |\n| [build log][]         | ✅ | `git semaphore --log`         | execution logs for a given build number _(per thread and command)_ |\n| [rebuild][]           | ✅ | `git semaphore --rebuild`     | rebuild last revision for the current branch                       |\n| [launch build][]      | ❌ |                               | launch a build for the given commit SHA                            |\n| [stop][]              | ❌ |                               | stop an in-progress build                                          |\n| [deploy][]            | ❌ |                               | run a deploy from a given build                                    |\n\n[project branches]:  https://semaphoreci.com/docs/branches-and-builds-api.html#project_branches\n[branch status]:     https://semaphoreci.com/docs/branches-and-builds-api.html#branch_status\n[branch history]:    https://semaphoreci.com/docs/branches-and-builds-api.html#branch_history\n[build information]: https://semaphoreci.com/docs/branches-and-builds-api.html#build_information\n[build log]:         https://semaphoreci.com/docs/branches-and-builds-api.html#build_log\n[rebuild]:           https://semaphoreci.com/docs/branches-and-builds-api.html#rebuild\n[launch build]:      https://semaphoreci.com/docs/branches-and-builds-api.html#launch_build\n[stop]:              https://semaphoreci.com/docs/branches-and-builds-api.html#stop\n[deploy]:            https://semaphoreci.com/docs/branches-and-builds-api.html#deploy\n\n## Installation\n\nInstall the gem:\n\n    gem install git-semaphore\n\nAnd execute it as a `git` subcommand:\n\n    git semaphore \u003coptions\u003e\n\nTo get an overview of the available options, use:\n\n    git-semaphore --help\n\n## API authentication\n\nLog into [semaphoreci.com][] and find **your authentication token** at the bottom of your [account settings][] page... this is also explained in [the Semaphore API documentation][authentication].\n\nNext, choose one of the following mechanisms to make your API authentication token available to `git semaphore`...\n\n### via *local* git config _(in a git working dir)_\n\n    git config --local --replace-all semaphore.authtoken \"Yds3w6o26FLfJTnVK2y9\"\n\n### via *global* git config\n\n    git config --global --replace-all semaphore.authtoken \"Yds3w6o26FLfJTnVK2y9\"\n\n### via an environment variable\n\n    export SEMAPHORE_AUTH_TOKEN=\"Yds3w6o26FLfJTnVK2y9\"\n\nThis is also the order in which tokens are searched for - and hence their precedence - meaning that if you have different Semaphore accounts for different projects _(e.g. work and personal projects)_ then you can configure your respective git repos with the authentication token of the corresponding Semaphore account.\n\n## API result caching\n\nFor performance reasons _(especially for Semaphore API calls that are paginated)_, to enable offline use of the Semaphore API data, as well as to support interactive use of the data in e.g. `irb` or `pry` sessions, `git semaphore` transparently caches the results of all API calls in the `${HOME}/.git/semaphore/` directory.\n\nThis means that running `git semaphore` commands may return stale data, in cases where things have changed on `semaphoreci.com` since the last time `git semaphore` was run.\n\nTo update the cached results, the following commands support the `--refresh` flag:\n\n* `--projects`\n* `--branches`\n* `--status`\n* `--history`\n* `--information`\n* `--log`\n\nWithout the `-refresh` flag, these options will always return cached - and possibly stale - results _(if they were invoked previously, that is, in which case the cache was populated)_, but when the `--refresh` flag is used, they will all make a new API call and return the most up-to-date SemaphoreCI data _(and update the cached data as a side effect)_.\n\n## Integration with `git`\n\nWhen used inside a git repository, `git semaphore` uses [convention over configuration][coc] to figure out the relevant settings it needs in order to make valid Semaphore API requests:\n\n| setting      | inside git repo    | pseudo-code                     | override                        |\n|--------------|--------------------|---------------------------------|---------------------------------|\n| owner \u0026 name | based on `${PWD}`  | `Dir.pwd.split('/').last(2)`    | `ENV['SEMAPHORE_PROJECT_NAME']` |\n| branch name  | current git branch | `git symbolic-ref --short HEAD` | `ENV['SEMAPHORE_BRANCH_NAME']`  |\n| commit SHA   | current git head   | `git rev-parse HEAD`            | `ENV['SEMAPHORE_COMMIT_SHA']`   |\n| build number | last branch build  | `N/A`                           | `ENV['SEMAPHORE_BUILD_NUMBER']` |\n\nHowever, each of these defaults can be overridden by setting the corresponding environment variable, as documented in the above table.  The same `ENV`-based override mechanism can be leveraged to use `git semaphore` outside of a git repository.\n\n## Using the \"full name\" convention\n\nOn your local filesystem, git repositories need to use paths that follow the \"full name\" convention in use on `github.com` and `semaphoreci.com`, ie. the last two path components for the `pvdb/git-semaphore` repository should be `pvdb` and `git-semaphore` respectively, as illustrated on this table:\n\n|           | full name            | owner  | name            | URL / path                                   |\n|-----------|----------------------|--------|-----------------|----------------------------------------------|\n|           | `pvdb/git-semaphore` | `pvdb` | `git-semaphore` |                                              |\n| GitHub    |                      |        |                 | `https://github.com/pvdb/git-semaphore`      |\n| Semaphore |                      |        |                 | `https://semaphoreci.com/pvdb/git-semaphore` |\n| filesytem |                      |        |                 | `${HOME}/Projects/pvdb/git-semaphore`        |\n\nPut differently: if you typically create your git repositories in `${HOME}/Projects`, and you have the following three git repos...\n\n    pvdb/git-meta\n    pvdb/git-semaphore\n    pvdb/git-switcher\n\n... then the directory tree should be as follows:\n\n    ${HOME}/Projects\n    └── pvdb\n        ├── git-meta\n        │   └── .git\n        ├── git-semaphore\n        │   └── .git\n        └── git-switcher\n            └── .git\n\nSo first you have a directory corresponding to the repository owner (`pvdb`) and one level down you have a directory corresponding to the repository name (`git-meta`, `git-semaphore` and `git-switcher` respectively).\n\n## A look behind the scences\n\nThe `git semaphore --settings` command can be used to print out the values for the most relevant settings:\n\n    $ git semaphore --settings | jq '.'\n    {\n      \"auth_token\": \"Yds3w6o26FLfJTnVK2y9\",\n      \"project_name\": \"pvdb/git-semaphore\",\n      \"branch_name\": \"master\",\n      \"commit_sha\": \"4b59c3e41ca4592dfb01f77f2163154f3d3532fe\",\n      \"build_number\": \"35\"\n    }\n    $ _\n\nThe `git semaphore --internals` command adds all internal settings to the above settings hash.\n\n## Available commands\n\n\u003e ⚠️ all of the below examples need to be run from within a git repository that follows the \"full name\" convention documented above ⚠️\n\n### list the Semaphore settings\n\n    git semaphore --settings\n\n_(lists things like project name, branch name, commit SHA, etc.)_\n\n### open the Semaphore page for the project's current branch\n\n    git semaphore --browse\n\n_(the project and branch names are derived from the current git repository and the current git head)_\n\n### delete the local Semapore API cache\n\n    git semaphore --clean\n\n _(this ensures the Semaphore data is refreshed for the subsequent API calls)_\n\n### list all Semaphore projects\n\n    git semaphore --projects\n\n_(for the Semaphore user account corresponding to the authentication token)_\n\n### list all of the project's branches\n\n    git semaphore --branches\n\n_(the project name is derived from the current git directory)_\n\n### build status of the project's current branch\n\n    git semaphore --status\n\n_(the project and branch names are derived from the current git repository and the current git head)_\n\n### build history of a project's branch\n\n    git semaphore --history\n\n_(the project and branch names are derived from the current git repository and the current git head)_\n\n### commit information for the last build of a project's branch\n\n    git semaphore --information\n\n_(the project and branch names are derived from the current git repository and the current git head)_\n\n### build command and logs for the last build of a project's branch\n\n    git semaphore --log\n\n## Formatting the raw `git semaphore` JSON output\n\nAfter installing [the indispensable jq utility][jq] (`brew install jq`), the raw JSON output generated by the various `git semaphore` commands can be formatted and queried as follows:\n\n    # pretty-print the git semaphore settings\n    git semaphore --settings | jq '.'\n\n    # pretty-print the git semaphore internals\n    git semaphore --internals | jq '.'\n\n    # list the full name of all Semaphore projects\n    git semaphore --projects | jq -r '.[] | .full_name'\n\n    # get the status of the last build for the current branch\n    git semaphore --status | jq -r '.result'\n\n    # list the build duration (in minutes) for all \"passed\" builds of the current branch\n    git semaphore --history | jq -r '.builds | .[] | select(.result == \"passed\") | (.build_number|tostring) + \"\\t\" + (.duration.minutes|tostring)'\n\n    # list all commit SHAs that triggered the latest build\n    git semaphore --information | jq -r '.commits | .[] | .id'\n\n    # list the various thread commands for the latest build\n    git semaphore --log | jq '.threads | .[] | .commands | .[] | .name'\n\n[semaphoreci.com]:  https://semaphoreci.com/\n[account settings]: https://semaphoreci.com/users/edit\n[Semaphore API]:    https://semaphoreci.com/docs/api.html\n\n[jq]:  https://stedolan.github.io/jq/\n[coc]: https://en.wikipedia.org/wiki/Convention_over_configuration\n\n## Development\n\nAfter 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.\n\nTo 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](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/pvdb/git-semaphore. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpvdb%2Fgit-semaphore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpvdb%2Fgit-semaphore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpvdb%2Fgit-semaphore/lists"}