{"id":28829106,"url":"https://github.com/forcedotcom/git2gus","last_synced_at":"2025-10-08T13:52:53.991Z","repository":{"id":37869900,"uuid":"183079318","full_name":"forcedotcom/git2gus","owner":"forcedotcom","description":"A Github application to keep issues in sync with Agile Accelerator","archived":false,"fork":false,"pushed_at":"2024-04-22T18:45:40.000Z","size":2519,"stargazers_count":28,"open_issues_count":37,"forks_count":15,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-06-19T05:13:11.174Z","etag":null,"topics":["github","gus","issues","sync","tool","work"],"latest_commit_sha":null,"homepage":"https://lwc-gus-bot.herokuapp.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/forcedotcom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-04-23T19:05:57.000Z","updated_at":"2025-03-24T22:47:03.000Z","dependencies_parsed_at":"2024-04-22T20:02:05.050Z","dependency_job_id":null,"html_url":"https://github.com/forcedotcom/git2gus","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/forcedotcom/git2gus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forcedotcom%2Fgit2gus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forcedotcom%2Fgit2gus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forcedotcom%2Fgit2gus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forcedotcom%2Fgit2gus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/forcedotcom","download_url":"https://codeload.github.com/forcedotcom/git2gus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forcedotcom%2Fgit2gus/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269355573,"owners_count":24403452,"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","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["github","gus","issues","sync","tool","work"],"created_at":"2025-06-19T05:11:50.067Z","updated_at":"2025-10-08T13:52:48.957Z","avatar_url":"https://github.com/forcedotcom.png","language":"JavaScript","readme":"# Git2Gus Application\n\nA GitHub application to keep issues in sync with Salesforce's Agile Accelerator.\n\nThis is an experimental project that is not yet supported, so while we appreciate feedback and welcome new issues, we can't guarantee response times and aren't ready to accept contributions. Thank you for understanding!\n\n[![CircleCI](https://circleci.com/gh/forcedotcom/git2gus.svg?style=svg\u0026circle-token=702c52c9b89dfb5a3df392245cea76d05c0905db)](https://circleci.com/gh/forcedotcom/git2gus)\n\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)\n\n## Run Locally\n\nFirst, make sure your dev environment is setup by reading the [contributing section](#contributing).\n\n```bash\nyarn\nyarn dev\n```\n\nIn another terminal launch [smee](https://smee.io) to forward your github test app web hook events to your local dev machine.\n\n```bash\nsmee -u \u003cyour smee address here\u003e --path /webhook --port 1337\n```\n\nNow go and create issues in a test repo that has your test github app installed. Your GH app will forward web hook events to smee which will forward to your local node process. Since we can't connect to real GUS the best we can do is inspect the local database changes. Under development the database is a set of json files under `\u003crepo root\u003e/.tmp/localDiskDb`.\n\n## Contributing\n\nAn overall flow of the local development strategy:\n\n```\n+--------------------------+            +----------------------------+\n|                          |            |                            |\n|  Test Repo               |            |  Mock Github App           |\n|                          |            |                            |\n|                          |            |                            |\n|  Create Issue            +-----------\u003e+  Detects issue created     |\n|                          |            |                            |\n|                          |            |                            |\n|                          |            |                            |\n+--------------------------+            +--------------+-------------+\n                                                       |\n                                           POSTs webhook via smee\n                                                       |\n                                                       v\n+--------------------------+            +--------------+-------------+\n|                          |            |                            |\n|  local db file           |            |  Local git2gus node server |\n|                          |            |                            |\n|                          +\u003c-----------+                            |\n|  Manually verify         |            |  Creates GUS work entry    |\n|  DB change               |            |  in local db file          |\n|                          |            |                            |\n+--------------------------+            +----------------------------+\n\n```\n\ngit2gus a Github App, to contribute you'll need to follow Github's [guide to set up your developement environment](https://developer.github.com/apps/quickstart-guides/setting-up-your-development-environment/).\n\nSteps to set up development:\n\n1. Create SMEE hook forwarder\n\n```bash\nsmee -u \u003cyour smee address here\u003e --path /webhook --port 1337\n```\n\n2. Create a mock github app\n\n   - The app needs Read \u0026 Write access to Issues, Pull Requests, and Commit Statuses. It also needs read access to \"A single file\" with the path `.git2gus/config.json`. You will also need to subscribe to events: Issue comment, Issues, and Label.\n\n3. Create a test repo and install mock github app to that repo\n\n4. Download github app PEM file, rename to `private-key.pem`, and place it in the project's root folder\n\n   - If you want to set an env variable instead of copying the .pem file then you must use the name `PRIVATE_KEY` (instead of `GITHUB_PRIVATE_KEY` as the github instructions say) and you have to manually insert `\\n` line characters between each line.\n\n5. Create .env file with github variables\n\n   - NOTE: Some variable names are slightly different than the github guide, see example below.\n   - You will need to specify a test organization/user to develop with as well as approved organizaitons your app will work with, see example below.\n\n6. Add variables specific to your Salesforce instance\n\n   - Get your Record Type IDs from the Object Manager and copy the base URL from your Agile Accelerator, it should resemble the one included in the example.\n\n   - When you later set up Heroku Connect, your database table and fields related to Agile Accelerator may be in a specific Postgres schema, which you will set as the `SALESFORCE_PREFIX`. If you use the defaults in Heroku Connect, this will be `salesforce.`\n\n7. Add a link to your GitHub app (ex: the GitHub app for Salesforce's instance is https://github.com/apps/git2gus)\n\n    - This will show up on the app's homepage\n\n- For SSO-enabled organizations, you must authenticate with a personal access token with full repo access. Using a personal access token is not required for non-SSO-enabled orgs. To use, in `.env`, set `PERSONAL_ACCESS_TOKEN` to your personal access token and `TOKEN_ORGS` to a comma-seperated list of organizations to use your personal access token with.\n\nYou're .env should look something like:\n\n```\nGITHUB_APP_ID=28467\nGITHUB_WEBHOOK_SECRET=qqqq1111\nGITHUB_APPROVED_ORGS=salesforce,sfdc,forcedotcom,salesforce-ux,SalesforceLabs,SalesforceFoundation\nGITHUB_TEST_ORG=wes566\nUSER_STORY_RECORD_TYPE_ID=ABCDEFGHIJKLM\nBUG_RECORD_TYPE_ID=NOPQRSTUVWXYZ\nINVESTIGATION_RECORD_TYPE_ID=123456789012\nWORK_ITEM_BASE_URL=https://myproject.lightning.force.com/lightning/r/ADM_Work__c/\nGITHUB_APP_URL= https://github.com/apps/yourapplication\nSALESFORCE_PREFIX=salesforce.\nNAMESPACE_PREFIX=agf\n```\n\nFor use with SSO-enabled organizations, you would also have additional lines:\n\n```\nPERSONAL_ACCESS_TOKEN=abcdefghijklmnopqrstuvwxyz\nTOKEN_ORGS=asdf\n```\n\nThe GITHUB_TEST_ORG is the org where you have a repo with your test GH app installed to.\n\nSet the user credentials for your Salesforce org with these environment variables. Other forms of authentication with Salesforce are not yet supported.\n\n```\nGUS_USER=005xxxxxxxxxxxxAAA\nGUS_USERNAME=username@example.com\nGUS_PASSWORD=example_password\n```\n\nMake sure your test app has Read \u0026 Write access to Issues, Pull Requests, and Commit Statuses. Also make sure it has read access to \"A single file\" and the path should be `.git2gus/config.json`. You will also need to subscribe to events: Issue comment, Issues, and Label.\n\n### Seeding your dev db\n\nSails has a built-in development db, called sails-disk, which is just a set of json files under `\u003crepo root\u003e/.tmp/localDiskDb`. The git2gus app will validate that the \"build\" you specified in the config is in the database so you'll need to make sure you've got an entry for that \"build\" in the `adm_build__c.db` file. For example, add a line like `{\"name\":\"218\",\"sfid\":\"218\",\"_id\":1}` to that file if your config is set to build \"218\".\n\n## Using\n\nTo use git2gus, you will need to set it up locally as described in the Contributing section and deploy it to a Heroku App with Postgres and Heroku Connect add-ons. The Postgres database will act as the app's database, and can then set up Heroku Connect between the Postgres database and your Salesforce instance.\n\nTo set your environment variables on Heroku, go to your apps settings tab and modify your config vars to reflect your `.env` file. Instead of uploading your `private-key.pem`, file, you can just copy its contents to a `PRIVATE_KEY` config var on your Heroku app's settings page.\n\nTo use, install your GitHub app on desired repositories. Your app's homepage will have set up and usage instructions for the actual syncing process between your GitHub repositories and your Salesforce instance.\n\n### Heroku Setup\n\nTo set up on your own Lightning Experience, host this app on Heroku and change the webhook URL of your GitHub app to point to [YOUR HEROKU APP URL]/webhook instead of smee.\n\nTo set up Heroku Connect, you may view the steps [here](https://devcenter.heroku.com/articles/getting-started-with-heroku-and-connect-without-local-dev). \n\nIn Heroku Connect, you will sync the `ADM_Build_c`, `ADM_Change_List__c` and `ADM_Work__c` tables. The fields are defined in [herokuconnect.json](./heroku/herokuconnect.json). You can deploy that mapping with the [Heroku Connect CLI plugin](https://devcenter.heroku.com/articles/quick-start-heroku-connect-cli#import-mapping-configuration), but you'll have to change the connection settings before deploying.\n\nAs a reminder, if you see a prefix before the field name, set the `SALESFORCE_PREFIX` environment variable to that prefix.\n\nIt is recommended that you create a testing team. As a reminder, to create product tags, visit the app launcher and search \"product tags\". From here, you can create a product tag for your team, create assignment rules for bugs, user stories, and investigations, and then copy the product tag (you can generate a work URL for any assignment and copy the tag from the URL).\n\nFor a better logging experience, you may use the [LogDNA](https://elements.heroku.com/addons/logdna) add-on on Heroku. In your Heroku config vars, add your LogDNA API key as `LOGDNA_INGESTION_KEY`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforcedotcom%2Fgit2gus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fforcedotcom%2Fgit2gus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforcedotcom%2Fgit2gus/lists"}