Git2Gus Application
A GitHub application to keep issues in sync with Salesforce's Agile Accelerator.
This 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!
Run Locally
First, make sure your dev environment is setup by reading the contributing section.
yarn
yarn devIn another terminal launch smee to forward your github test app web hook events to your local dev machine.
smee -u <your smee address here> --path /webhook --port 1337Now 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 <repo root>/.tmp/localDiskDb.
Contributing
An overall flow of the local development strategy:
+--------------------------+ +----------------------------+
| | | |
| Test Repo | | Mock Github App |
| | | |
| | | |
| Create Issue +----------->+ Detects issue created |
| | | |
| | | |
| | | |
+--------------------------+ +--------------+-------------+
|
POSTs webhook via smee
|
v
+--------------------------+ +--------------+-------------+
| | | |
| local db file | | Local git2gus node server |
| | | |
| +<-----------+ |
| Manually verify | | Creates GUS work entry |
| DB change | | in local db file |
| | | |
+--------------------------+ +----------------------------+
git2gus a Github App, to contribute you'll need to follow Github's guide to set up your developement environment.
Steps to set up development:
- Create SMEE hook forwarder
smee -u <your smee address here> --path /webhook --port 1337-
Create a mock github app
- The app needs Read & 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.
- The app needs Read & Write access to Issues, Pull Requests, and Commit Statuses. It also needs read access to "A single file" with the path
-
Create a test repo and install mock github app to that repo
-
Download github app PEM file, rename to
private-key.pem, and place it in the project's root folder- If you want to set an env variable instead of copying the .pem file then you must use the name
PRIVATE_KEY(instead ofGITHUB_PRIVATE_KEYas the github instructions say) and you have to manually insert\nline characters between each line.
- If you want to set an env variable instead of copying the .pem file then you must use the name
-
Create .env file with github variables
- NOTE: Some variable names are slightly different than the github guide, see example below.
- 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.
-
Add variables specific to your Salesforce instance
-
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.
-
When you later set up Heroku Connect, your database table and fields related to Agile Accelerator may have a prefix, which you will set as the
SALESFORCE_PREFIX
-
-
Add a link to your GitHub app (ex: the GitHub app for Salesforce's instance is https://github.com/apps/git2gus)
- This will show up on the app's homepage
- 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, setPERSONAL_ACCESS_TOKENto your personal access token andTOKEN_ORGSto a comma-seperated list of organizations to use your personal access token with.
You're .env should look something like:
GITHUB_APP_ID=28467
GITHUB_WEBHOOK_SECRET=qqqq1111
GITHUB_APPROVED_ORGS=salesforce,sfdc,forcedotcom,salesforce-ux,SalesforceLabs,SalesforceFoundation
GITHUB_TEST_ORG=wes566
USER_STORY_RECORD_TYPE_ID=ABCDEFGHIJKLM
BUG_RECORD_TYPE_ID=NOPQRSTUVWXYZ
INVESTIGATION_RECORD_TYPE_ID=123456789012
WORK_ITEM_BASE_URL=https://myproject.lightning.force.com/lightning/r/ADM_Work__c/
GITHUB_APP_URL= https://github.com/apps/yourapplication
SALESFORCE_PREFIX=agf__
For use with SSO-enabled organizations, you would also have additional lines:
PERSONAL_ACCESS_TOKEN=abcdefghijklmnopqrstuvwxyz
TOKEN_ORGS=asdf
The GITHUB_TEST_ORG is the org where you have a repo with your test GH app installed to.
Set the user credentials for your Salesforce org with these environment variables. Other forms of authentication with Salesforce are not yet supported.
GUS_USER=005xxxxxxxxxxxxAAA
[email protected]
GUS_PASSWORD=example_password
Make sure your test app has Read & 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.
Seeding your dev db
Sails has a built-in development db, called sails-disk, which is just a set of json files under <repo root>/.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".
Using
To 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.
To 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.
To 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.
Heroku Setup
To 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.
To set up Heroku Connect, you may view the steps here.
In 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. You can deploy that mapping with the Heroku Connect CLI plugin, but you'll have to change the connection settings before deploying.
As a reminder, if you see a prefix before the field name, set the SALESFORCE_PREFIX environment variable to that prefix.
It 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).
For a better logging experience, you may use the LogDNA add-on on Heroku. In your Heroku config vars, add your LogDNA API key as LOGDNA_INGESTION_KEY.