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!
First, make sure your dev environment is setup by reading the contributing section.
yarn
yarn dev
In 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 1337
Now 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
.
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:
smee -u <your smee address here> --path /webhook --port 1337
Create a mock github app
.git2gus/config.json
. You will also need to subscribe to events: Issue comment, Issues, and Label.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
PRIVATE_KEY
(instead of GITHUB_PRIVATE_KEY
as the github instructions say) and you have to manually insert \n
line characters between each line.Create .env file with github variables
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 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.
Add a link to your GitHub app (ex: the GitHub app for Salesforce's instance is https://github.com/apps/git2gus)
.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.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=salesforce.
NAMESPACE_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
GUS_USERNAME=username@example.com
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.
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".
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.
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
.