Improve docs for GitHub Actions

source/ci_source/providers/GitHubActions.ts

@@ -7,45 +7,128 @@ import { readFileSync, existsSync } from "fs"
 /**
  * ### CI Setup
  *
- * To use Danger JS with GitHub Actions, you'll need want to set up
- * Danger to run on a `pull_request` webhook. To do this, you'll need
- * to add/amend your repo's workflow file with something like:
+ *  * <!-- JS --!>
+ * There are two ways to use Danger with GitHub Actions. If you include Danger as a dev-dependency, then
+ * you can call danger directly as another build-step after your tests:
  *
+ * ```ruby
+ * name: Node CI
+ * on: [pull_request]
+ *
+ * jobs:
+ *   test:
+ *     runs-on: ubuntu-latest
+ *
+ *     steps:
+ *     - uses: actions/checkout@master
+ *     - name: Use Node.js 10.x
+ *       uses: actions/setup-node@v1
+ *       with:
+ *         version: 10.x
+ *     - name: install yarn
+ *       run: npm install -g yarn
+ *     - name: yarn install, build, and test
+ *       run: |
+ *         yarn install  --frozen-lockfile
+ *         yarn build
+ *         yarn test
+ *     - name: Danger
+ *       run: yarn danger ci
+ *       env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ *  ```
+ *
+ * If you are not running in a JavaScript ecosystem, or don't want to include the dependency then
+ * you can use Danger JS as an action.
+ *
+ * ```yml
+ * name: "Danger JS"
+ * on: [pull_request]
+ *
+ * jobs:
+ *   build:
+ *     name: Danger JS
+ *     runs-on: ubuntu-latest
+ *     steps:
+ *     - uses: actions/checkout@v1
+ *     - name: Danger
+ *       uses: danger/danger-js@9.1.6
+ *       env:
+ *         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  * ```
- * workflow "Dangerfile JS Eval" {
- *   on = "pull_request"
- *   resolves = "Danger JS"
- * }
- *
- * action "Danger JS" {
- *   uses = "danger/danger-js@master"
- *   secrets = ["GITHUB_TOKEN"]
- * }
+ *
+ * Note it's likely the version number should change, but you get the point. This will run Danger
+ * self-encapsulated inside a GitHub action.
+ *
+ * <!-- !JS --!>
+ * <!-- Swift --!>
+ *
+ * There are two ways to use Danger with GitHub Actions. If you include Danger as a dependency, then
+ * you can call danger directly as another build-step after your tests:
+ *
+ * ```ruby
+ * name: CI
+ * on: [pull_request]
+ * jobs:
+ *   build:
+ *     runs-on: macos-latest
+ *
+ *     steps:
+ *     - uses: actions/checkout@master
+ *     - name: Build
+ *       run: swift build
+ *
+ *     - name: Test
+ *       run: swift test
+ *
+ *     - name: Danger
+ *       run: danger-swift ci
+ *       env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ *  ```
+ *
+ * If don't want to include the dependency then you can use Danger Swift via an action.
+ *
+ * ```yml
+ * name: "Danger Swift"
+ * on: [pull_request]
+ *
+ * jobs:
+ *   build:
+ *     name: Danger JS
+ *     runs-on: ubuntu-latest
+ *     steps:
+ *     - uses: actions/checkout@v1
+ *     - name: Danger
+ *       uses: danger/swift@2.0.1
+ *       env:
+ *         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  * ```
  *
- * You can pass additional CLI to Danger JS in an action via:
+ * Note it's likely the version number should change, but you get the point. This will run Danger
+ * self-encapsulated inside a GitHub action.
+ *
+ * <!-- !Swift --!>
+ *
+ * You can pass additional CLI to Danger via an action via the args:
  *
  * ```
- * action "Danger JS" {
- *   [...]
- *   args = "--dangerfile artsy/peril-settings/org/allPRs.ts"
- * }
+ *  - uses: danger/...
+ *    args: "--dangerfile artsy/peril-settings/org/allPRs.ts"
  * ```
  *
  * This runs the file [`org/allPRs.ts`](https://github.com/artsy/peril-settings/blob/master/org/allPRs.ts)
- * from the repo [artsy/peril-settings](https://github.com/artsy/peril-settings).
+ * from the repo [artsy/peril-settings](https://github.com/artsy/peril-settings). This gives you the ability
+ * to have Danger acting on non-pull-requests via GitHub Actions.
  *
  * ### Token Setup
  *
  * You need to make sure that the secret `"GITHUB_TOKEN"` is
  * enabled in your workspace. This is so that Danger can connect
  * to GitHub.
  *
- * ```
- * action "Danger JS" {
- *   uses = "danger/danger-js@master"
- *   secrets = ["GITHUB_TOKEN"]
- * }
+ * ```yml
+ *   - name: Danger JS
+ *     uses: danger/danger-js@9.1.6
+ *     env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  * ```
  *
  */

source/platforms/platform.ts

@@ -141,10 +141,12 @@ export function getPlatformForEnv(env: Env, source: CISource): Platform {
   // They need to set the token up for GitHub actions to work
   if (env["GITHUB_EVENT_NAME"] && !env["GITHUB_TOKEN"]) {
     console.error(`You need to add GITHUB_TOKEN to your Danger action in the workflow:
-
-    action "${env["GITHUB_ACTION"]}" {
-    ${chalk.green('+  secrets = ["GITHUB_TOKEN"]"')}
-    }`)
+  
+    - name: Danger JS
+      uses: danger/danger-js@X.Y.Z
+      ${chalk.green(`env:
+        GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}`)}
+    `)
   }
 
   // GitHub Platform