{"id":13826657,"url":"https://github.com/getgort/gort","last_synced_at":"2025-04-05T22:09:15.311Z","repository":{"id":38389353,"uuid":"163297934","full_name":"getgort/gort","owner":"getgort","description":"Gort is a chatbot framework designed from the ground up for chatops.","archived":false,"fork":false,"pushed_at":"2023-04-04T21:15:22.000Z","size":8336,"stargazers_count":403,"open_issues_count":24,"forks_count":23,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-29T21:06:59.966Z","etag":null,"topics":["bot-framework","chat-bot","chatbot","chatbot-framework","chatops","cog","cog-slack-bot","devops","devops-tools","go","golang","reimplement","slack"],"latest_commit_sha":null,"homepage":"https://guide.getgort.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getgort.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-12-27T13:29:36.000Z","updated_at":"2024-12-11T17:51:01.000Z","dependencies_parsed_at":"2024-01-15T15:47:48.006Z","dependency_job_id":"19d261ac-df4c-4c04-bb0b-6590e1e60487","html_url":"https://github.com/getgort/gort","commit_stats":null,"previous_names":["clockworksoul/cog2"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgort%2Fgort","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgort%2Fgort/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgort%2Fgort/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getgort%2Fgort/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getgort","download_url":"https://codeload.github.com/getgort/gort/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247406091,"owners_count":20933803,"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":["bot-framework","chat-bot","chatbot","chatbot-framework","chatops","cog","cog-slack-bot","devops","devops-tools","go","golang","reimplement","slack"],"created_at":"2024-08-04T09:01:42.005Z","updated_at":"2025-04-05T22:09:15.276Z","avatar_url":"https://github.com/getgort.png","language":"Go","readme":"# Gort\n\n[![GoDoc](https://godoc.org/github.com/getgort/gort?status.svg)](https://godoc.org/github.com/getgort/gort)\n[![Tests](https://github.com/getgort/gort/actions/workflows/test.yaml/badge.svg)](https://github.com/getgort/gort/actions/workflows/test.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/getgort/gort)](https://goreportcard.com/report/github.com/getgort/gort)\n\nGort is a chatbot framework designed from the ground up for chatops.\n\nGort brings the power of the command line to the place you collaborate with your team: your chat window. Its open-ended command bundle support allows developers to implement functionality in the language of their choice, while powerful access control means you can collaborate around even the most sensitive tasks with confidence. A focus on extensibility and adaptability means that you can respond quickly to the unexpected, without your team losing visibility.\n\nThe official documentation can be found here: [The Gort Guide](https://guide.getgort.io/).\n\n## History\n\nGort was initially conceived of as a Go re-implementation of Operable's [Cog](https://github.com/operable/cog), and while it remains heavily inspired by Cog, Gort has largely gone its own way.\n\nDuring our initial [design discussion](https://docs.google.com/document/d/1u7LzEzPjT1L8_xkHL577cKeuQdCiCQAww8M0rx1QXEM/edit), we found that many of Cog’s features, however innovative, went largely unused, and the codebase had become difficult to extend and maintain. Additionally, its implementation language -- Elixir -- had relatively few proficient developers. The solution, which was discussed for many months on the Cog Slack workspace, was to rewrite Cog from scratch in Go, removing some of less-used functionality and reducing complexity in the process.\n\nThis gave us the opportunity to consider and possibly redefine what Cog was meant to be. To choose the features that make sense, and to discard those that don't. In this way, Gort can be described more as a “spiritual successor” to Cog than a faithful re-implementation.\n\n## Features\n\nGort's design philosophy emphasizes flexibility and security by allowing you to build commands in any language you want, using tooling you're already comfortable with, and can tightly control who can use them and how.\n\nMore specifically:\n\n- Commands can be implemented in any programming language\n- Users may trigger commands through Slack (or another chat provider)\n- Commands are packaged into bundles that can be installed in Gort\n- Users can be assigned to groups, roles can be assigned to groups, and permissions can be attached to roles\n- Supports a sophisticated identity and permission system to determine who can use commands\n- System and command output is highly customizable at the application, bundle, and even command level\n- Supports Slack and Discord as first class chat providers (with more on the way!)\n- All command and API activities are stored in a dedicated audit log for review\n\nEach of these is described in more detail below.\n\n### Users may trigger commands through Slack (or another chat provider)\n\nUsers primarily interact with Gort through _commands_, which are triggered by a command character (`!` by default) but are otherwise conceptually identical to commands entered on the command line.\n\nFor example, using an `echo` command might look like the following:\n\n![Hello, Gort!](images/hello-gort.png \"Hello, Gort!\")\n\nAs shown, the output from successful commands is relayed back by Gort.\n\nMore information about commands can be found in the Gort Guide:\n\n* [Gort Guide: Commands and Bundles](https://guide.getgort.io/en/latest/sections/commands-and-bundles.html)\n### Commands can be implemented in any programming language\n\nGort [commands](https://guide.getgort.io/en/latest/sections/commands-and-bundles.html) are built as container images, which means you can build them in any language you're comfortable with.\n\nWhat's more, because your executable receives all chat inputs exactly as if it was being typed on the command line, you can use any command line interpreter you want. Commands can even be implemented as Bash scripts, or using existing commands, like `curl`!\n\nMore information about writing commands can be found in the Gort Guide:\n\n* [Gort Guide: Writing a Command Bundle](https://guide.getgort.io/en/latest/sections/writing-a-command-bundle.html)\n\n### Commands are packaged into bundles that can be installed in Gort\n\nIn Gort, a set of one or more related commands can be installed as a \"command bundle\".\n\nA bundle is [represented in YAML](https://guide.getgort.io/en/latest/sections/bundle-configurations.html), specifying which executable to use for each command and who is allowed to execute each commands.\n\nA very simple bundle file is shown below.\n\n```yaml\n---\ngort_bundle_version: 1\n\nname: echo\nversion: 0.0.1\nimage: ubuntu:20.04\n\nauthor: Matt Titmus \u003cmatthew.titmus@gmail.com\u003e\nhomepage: https://guide.getgort.io\ndescription: A test bundle.\nlong_description: |-\n  This is an example bundle. It lets you echo text using the \"echo\"\n  command that's built into Ubuntu 20.04.\n\npermissions:\n  - can_echo\n\ncommands:\n  echo:\n    description: \"Echos back anything sent to it.\"\n    executable: [ \"/bin/echo\" ]\n    rules:\n      - must have echo:can_echo\n```\n\nThis shows a bundle called `echo`, which defines a command (also called `echo`) and a permission called `can_echo`. Once [installed](https://guide.getgort.io/en/latest/sections/managing-bundles.html), any user with the `echo:can_echo` permission can execute it in Slack.\n\nMore information about bundles can be found in the Gort Guide:\n\n* [Gort Guide: Bundle Configurations](https://guide.getgort.io/en/latest/sections/bundle-configurations.html)\n* [Gort Guide: Managing Bundles](https://guide.getgort.io/en/latest/sections/managing-bundles.html)\n\n### Organize users into groups, and permissions into roles\n\nIn Gort, _users_ can be uniquely mapped to users in one or more chat providers. Gort users can be members of one or more _groups_, which in turn can have any number of _roles_ that can be thought of as collections of granted permissions. For example, the user `dave` might be in a group called `developers`. This group may have a role attached named `deployers` that contains a number of permissions, including one called `production_deploy`.\n\nMore information about permissions and rules can be found in the Gort Guide:\n\n* [Gort Guide: Managing Users](https://guide.getgort.io/en/latest/sections/managing-users.html)\n\n### Use a sophisticated identity and permission system to determine who can use commands\n\nA sophisticated rule system can be applied for each command defining who can use it. These can be quite granular, and are even capable of making permissions decisions based on the values of specific flags or parameters.\n\nRules are assigned at the bundle level, and can be quite sophisticated. Below we have a subset of a bundle called `deploy`.\n\n```yaml\nname: deploy\nversion: 0.0.1\n\npermissions:\n  - production_deploy\n\ncommands:\n  deploy:\n    description: \"Deploys to the chosen environment.\"\n    executable: [ \"/bin/deploy\" ]\n    rules:\n      - with arg[0] == \"production\" must have deploy:production_deploy\n```\n\nAs you can see, the above example includes one command, also called `deploy`. Its one rule asserts that any user passing \"production\" as the parameter must have the `production_deploy` permission (from the `deploy` bundle).\n\nMore information about permissions and rules can be found in the Gort Guide:\n\n* [Gort Guide: Permissions and Rules](https://guide.getgort.io/en/latest/sections/permissions-and-rules.html)\n* [Gort Guide: Command Execution Rules](https://guide.getgort.io/en/latest/sections/command-execution-rules.html)\n\n### System and command output is highly customizable\n\nGort provides a sophisticated templating system that allows you to control the presentation of any information sent to users, including system messages, as well as command output and error messages.\n\nWhat's more, templates can be defined at the application level in the [configuration](https://guide.getgort.io/en/latest/sections/configuration.html), or at the bundle or even the command level in individual [bundle configurations](https://guide.getgort.io/en/latest/sections/bundle-configurations.html).\n\nGort templates use Go's [template syntax](https://pkg.go.dev/text/template) to format output in a chat-agnostic way. For example, a very simple _command template_ might look something like the following:\n\n```\n{{ text | monospace true }}{{ .Response.Out }}{{ endtext }}\n```\n\nThis template emits the command's response (`.Response.Out`) as monospaced text, which may look something like the following:\n\n![Monospaced command output](images/command-mono.png \"Monospaced command output\")\n\nA slightly more complicated template, this one a _command error template_ (actually the default), is shown below.\n\n```\n{{ header | color \"#FF0000\" | title .Response.Title }}\n{{ text }}The pipeline failed planning the invocation:{{ endtext }}\n{{ text | monospace true }}{{ .Request.Bundle.Name }}:{{ .Request.Command.Name }} {{ .Request.Parameters }}{{ endtext }}\n{{ text }}The specific error was:{{ endtext }}\n{{ text | monospace true }}{{ .Response.Out }}{{ endtext }}\n```\n\nThis one includes a header with a color and title, as well as some alternating monospaced and standard text. In this case, this will format a command error something like the following:\n\n![Pretty command error message](images/command-formatted.png \"Pretty command error message\")\n\nYou'll notice some references to `.Response`: those are references to the [_response envelope_](https://guide.getgort.io/templates-response-envelope.html), a data structure that's accessible from any template that makes available all of the data and metadata around one command request, execution, and response.\n\nMore information about audit logging can be found in the Gort Guide:\n\n* [Gort Guide: Output Format Templates](https://guide.getgort.io/en/latest/sections/templates.html)\n* [Gort Guide: The Response Envelope](https://guide.getgort.io/en/latest/sections/templates-response-envelope.html)\n* [Gort Guide: Template Functions](https://guide.getgort.io/en/latest/sections/templates-functions.html)\n\n### Supports Slack and Discord as first class chat providers\n\nGort supports both [Slack](https://slack.com/) and [Discord](https://discord.com/) as first class chat providers.\n\nEach supported chat provider has a dedicated section [in the configuration](https://guide.getgort.io/en/latest/sections/configuration.html). Note that each of these is a list, so not only can you interact with both Slack and Discord from the same Gort controller, but you can interact with multiple instances of each if you want to!\n\nOnce you've created a bot user according to the instructions provided in [Gort Quick Start](https://guide.getgort.io/en/latest/sections/quickstart.html), an administrators need only to create a Gort user (if you haven't already), and map that Gort user to a chat provider user ID, as shown below:\n\n```bash\n$ gort user create mtitmus --email matthew.titmus@gmail.com --name \"Matt Titmus\" --password REDACTED\nUser \"mtitmus\" created.\n\n$ gort user list\nUSER NAME   FULL NAME            EMAIL\nadmin       Gort Administrator   gort@localhost\nmtitmus     Matt Titmus          matthew.titmus@gmail.com\n\n$ gort user map mtitmus Slack U012P123456\nUser \"mtitmus\" mapped to \"Slack:U012P123456\".\n\n$ gort user info mtitmus\nName       mtitmus\nFull Name  Matt Titmus\nEmail      matthew.titmus@gmail.com\nGroups     \u003cundefined\u003e\n\nADAPTER   ID MAPPING\nSlack     U012P123456\n```\n\nFrom then on any commands entered by the mapped chat user are associated with that Gort user!\n\n* [Gort Guide: Quick Start](https://guide.getgort.io/en/latest/sections/quickstart.html)\n\n### Records all command and API activities in an audit log\n\nAll command activities are both emitted as high-cardinality log events (shown below) and recorded in [an audit log](https://guide.getgort.io/en/latest/sections/audit-log-events.html) that's maintained in Gort's database.\n\nTake, for example, a user executing the `!bundle list` command from Slack:\n\n![bundle list](images/bundle-list.png \"bundle list\")\n\nThis will generate log output similar to the following:\n\n```\nINFO   [49594] Triggering command   adapter.name=Gort bundle.default=false bundle.name=gort bundle.version=0.0.1\n                                    command.executable=\"[/bin/gort bundle]\" command.name=bundle\n                                    command.params=list gort.user.name=admin provider.channel.id=C1238A01234\n                                    provider.channel.name=gort-dev provider.user.email=matthew.titmus@gmail.com\n                                    provider.user.id=U012P123456 trace.id=476b3089c8ce0d38a2915a3b58fde032\n```\n\nAs you can see, this rich event includes:\n\n* The chat provider (\"Gort\", as named in the configuration), and channel within it\n* The triggered bundle (and its version) and command (and executable), and the parameters passed to it\n* The name of the user (both the Gort user ID and Slack user ID)\n* A unique trace ID that's used by all log events associated with this invocation.\n\nNote that this example uses \"human readable\" format for readability. In production mode Gort generates JSON-encoded log events.\n\nMore information about audit logging can be found in the Gort Guide:\n\n* [Gort Guide: Audit Log Events](https://guide.getgort.io/en/latest/sections/audit-log-events.html)\n\n\u003c!-- - execute triggered commands anywhere a relay is installed using a tag-based targeting system, --\u003e\n\n\u003c!-- ## Gort Design\n\nA WIP design doc, including rough milestones (but not dates) [can be seen here](https://docs.google.com/document/d/1u7LzEzPjT1L8_xkHL577cKeuQdCiCQAww8M0rx1QXEM/edit?usp=sharing). Feel free to add questions or comments. --\u003e\n\n## How to Run the Gort Controller\n\nFor more information, take a look at the [Quick Start Guide](https://guide.getgort.io/en/latest/sections/quickstart.html) in [The Gort Guide](https://guide.getgort.io).\n\n## The Gort Client\n\nThe `gort` binary also serves as the controller administration CLI.\n\n### Configuring Client Profiles\n\nThe `gort` client uses a YAML-formatted configuration file, conventionally\nlocated in the `profile` file in a `.gort` directory in your home directory.\nThis is where you can store connection credentials to allow `gort` to interact\nwith the Gort's Controller's REST API.\n\nAn example `.gort/profile` file might look like this:\n\n```yaml\ndefaults:\n    profile: gort\n\ngort:\n    url: https://gort.mycompany.com:4000\n    password: \"seekrit#password\"\n    user: me\n\npreprod:\n    url: https://gort.preprod.mycompany.com:4000\n    password: \"anotherseekrit#password\"\n    user: me\n```\n\nComments begin with a `#` character; if your password contains a `#`,\nsurround the entire password in quotes, as illustrated above.\n\nYou can store multiple \"profiles\" in this file, with a different name\nfor each (here, we have `gort` and `preprod`). Whichever one is noted\nas the default (in the `defaults` section) will be used by\n`gort`. However, you can pass the `--profile=$PROFILE` option to\n`gort` to use a different set of credentials.\n\nWhile you can add profiles to this file manually, you can also use the\n`gort profile create` command to help.\n\n### Getting Help\n\nThe `gort` executable contains a number of commands and sub-commands.\nHelp is available for all of them by passing the `--help` option.\nStart with `gort --help`, and go from there.\n\n## Status of This Project\n\nGort is in a state of active heavy development. The date that various milestones have been achieved are listed below. The number and focus of present and future milestones are subject to change.\n\n- Project created: 27 December 2018\n- Milestone 1: [7 January 2019](https://github.com/getgort/gort/tree/v0.1.0-dev.0)\n- Milestone 2: [21 January 2019](https://github.com/getgort/gort/tree/v0.2.1-dev.0)\n- Milestone 3: [24 January 2019](https://github.com/getgort/gort/tree/v0.3.0-dev.0)\n- Milestone 4: [17 March 2019](https://github.com/getgort/gort/releases/tag/v0.4.6-dev.7)\n- Milestone 5: [7 June 2021](https://github.com/getgort/gort/releases/tag/v0.5.6-dev.0)\n- Milestone 6: [10 June 2021](https://github.com/getgort/gort/releases/tag/v0.6.0-dev.0)\n- Milestone 7: [15 June 2021](https://github.com/getgort/gort/releases/tag/v0.7.0-dev.0)\n- Milestone 8: [26 July 2021](https://github.com/getgort/gort/releases/tag/v0.8.0) (alpha: [2 July 2021](https://github.com/getgort/gort/releases/tag/v0.8.0-alpha.0); beta: [15 July 2021](https://github.com/getgort/gort/releases/tag/v0.8.0-beta.0))\n- Milestone 9: [19 November 2021](https://github.com/getgort/gort/releases/tag/v0.9.0)\n\n## More Links\n\n* [Gort Slack Community](https://join.slack.com/t/getgort/shared_invite/zt-z1elsl5i-XvkiBPHqUOTDUUH1j9dSbg)\n* [GitHub Issues](https://github.com/getgort/gort/issues)\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetgort%2Fgort","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetgort%2Fgort","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetgort%2Fgort/lists"}