{"id":13783580,"url":"https://github.com/matrix-org/matrix-appservice-gitter","last_synced_at":"2025-05-11T19:31:10.789Z","repository":{"id":52881934,"uuid":"51444654","full_name":"matrix-org/matrix-appservice-gitter","owner":"matrix-org","description":"Matrix \u003c-\u003e Gitter bridge","archived":true,"fork":false,"pushed_at":"2021-04-15T08:40:20.000Z","size":554,"stargazers_count":41,"open_issues_count":48,"forks_count":12,"subscribers_count":27,"default_branch":"develop","last_synced_at":"2024-08-03T19:07:58.558Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/matrix-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-10T14:05:19.000Z","updated_at":"2024-06-08T17:31:56.000Z","dependencies_parsed_at":"2022-08-23T12:41:55.440Z","dependency_job_id":null,"html_url":"https://github.com/matrix-org/matrix-appservice-gitter","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-appservice-gitter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-appservice-gitter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-appservice-gitter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-appservice-gitter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matrix-org","download_url":"https://codeload.github.com/matrix-org/matrix-appservice-gitter/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225086514,"owners_count":17418740,"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":"2024-08-03T19:00:25.227Z","updated_at":"2024-11-17T20:30:49.500Z","avatar_url":"https://github.com/matrix-org.png","language":"JavaScript","funding_links":[],"categories":["Bridges"],"sub_categories":["Gitter"],"readme":"## Deprecation Notice\nThis bridge has been deprecated in favor of the [Native Glitter Bridge](https://www.matrix.org/docs/projects/bridge/native-gitter-bridge) that is automatically deployed for you.\n\nInstallation\n------------\n\n```sh\n$ git clone ...\n$ cd matrix-appservice-gitter\n$ npm install\n```\n\n\nSetup\n-----\n\n1. Create a github user to act as the relay bot itself in gitter chanels.\n   Obtain the user's gitter API key by visiting\n     https://developer.gitter.im/apps\n\n1. Create a new Matrix room to act as the administration control room. Note\n   its internal room ID.\n\n1. Create a `gitter-config.yaml` file for global configuration. There is a\n   sample one to begin with in `config/gitter-config-sample.yaml` you may wish\n   to copy and edit as appropriate. This needs the following keys:\n\n   ```yaml\n   gitter_api_key: \"the API key obtained in step 1\"\n\n   matrix_homeserver: \"http URL pointing at the homeserver\"\n\n   matrix_user_domain: \"domain part of the homeserver's name. Used for\n                        ghost username generation\"\n\n   username_template: \"template for virtual users, e.g. gitter_${USER}\"\n\n   matrix_admin_room: \"the ID of the room created in step 2\"\n   ```\n\n1. Pick/decide on a spare local TCP port number to run the application service\n   on. This needs to be visible to the homeserver - take care to configure\n   firewalls correctly if that is on another machine to the bridge. The port\n   number will be noted as `$PORT` in the remaining instructions.\n\n1. Generate the appservice registration file (if the application service runs\n   on the same server you can use localhost as `$URL`):\n\n   ```sh\n   $ node index.js --generate-registration -f gitter-registration.yaml  -u $URL:$PORT\n   ```\n\n1. Start the actual application service. You can use forever\n\n   ```sh\n   $ forever start index.js --config gitter-config.yaml --port $PORT\n   ```\n\n   or node\n\n   ```sh\n   $ node index.js --config gitter-config.yaml --port $PORT\n   ```\n\n1. Copy the newly-generated `gitter-registration.yaml` file to the homeserver.\n   Add the registration file to your homeserver config (default `homeserver.yaml`):\n\n   ```yaml\n   app_service_config_files:\n      - ...\n      - \"/path/to/gitter-registration.yaml\"\n   ```\n\n   Don't forget - it has to be a YAML list of strings, not just a single string.\n\n   Restart your homeserver to have it reread the config file and establish a\n   connection to the bridge.\n\n1. Invite the newly-created `@gitterbot:DOMAIN` user into the admin control\n   room created at step 2.\n\nThe bridge should now be running.\n\n\nProvisioning\n------------\n\nThe bridge is controlled by commands in the admin control room.\n\n\u003e link [matrix room ID] [gitter room name]\n\nCreates a new link between the given matrix room ID\n(example: `!abcdef:example.org`) and the gitter room name\n(example: `gitterHQ/sandbox`) and joins the associated gitter room. The relay\nuser must be invited to the matrix room for this to become functional.\n\n\u003e unlink [matrix room ID or gitter room name]\n\nDisconnects the link associated with the given room and leaves the\nassociated gitter room\n\n\nDynamic Portals\n---------------\n\nAs well as the linked rooms created by administrator users on the console, it\nis also possible to enable \"dynamic portals\", a feature in which the bridge\nitself will lazily create linked rooms in response to alias lookup requests\nwithin a given namespace.\n\n1. Set the following extra configuration values in the main\n   `gitter-config.yaml` file:\n\n   ```yaml\n   enable_portals: true\n\n   alias_template: \"template for room aliases, e.g. gitter_${ROOM}\"\n   ```\n\n1. Ensure that the appservice registration file requests an alias regexp\n   pattern that will match the alias template form, e.g.:\n\n   ```yaml\n   ...\n   namespaces:\n     aliases:\n       - exclusive: true\n         regex: '#gitter_.*'\n   ```\n\n   If you've edited the registration file, don't forget to restart the\n   homeserver to have the new values applied.\n\nYou should now be able to dynamically create new portal rooms by directly\nattempting to join room aliases matching this template. These rooms will\nbehave similarly to administrator-provisioned link rooms, except that because\nthe application service itself created the Matrix-side room, it retains full\noperator control of the room.\n\nFor top-level gitter rooms like organisations, repositories and user rooms,\nyou can simply embed the name in the alias. For example, the top-level gitter\nchat room relating to ``my-org-here`` would be found at:\n\n\u003e /join #gitter_my-org-here:localhost\n\nTo join a channel nested withn an organisation, repository or user account,\nyou'll need to encode the ``/`` character as ``=2F``. For example, the\n``my-org-here/chat`` room would be found at:\n\n\u003e /join #gitter_my-org-here=2Fchat:localhost\n\nAlternatively, if you wish to be able to create these portals only from the\nadmin console without letting all your users dynamically create their own, you\ncan leave the ``aliases`` list empty in the registration file, so that the\nhomeserver won't ask the application service to dynamically create them.\nInstead, you can provision them directly by using the admin control room.\n\n\u003e mkportal [gitter room name]\n\nWill create a new portal room for the given gitter room name and print its\nalias. Once created, these rooms act the same as other dynamic portals.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-appservice-gitter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrix-org%2Fmatrix-appservice-gitter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-appservice-gitter/lists"}