Merge pull request #11 from dependabot/brrygrdn/output-single-dependency

Clarify action naming, add usage examples for actions + gh cli

.github/workflows/integration.yml

@@ -3,6 +3,7 @@ on: [ pull_request ]
 
 jobs:
   # test action works running from the graph
+  if: ${{ github.actor == 'dependabot[bot]' }}
   run-action:
     runs-on: ubuntu-latest
     steps:

README.md

@@ -2,12 +2,15 @@
   <img src="https://s3.eu-west-2.amazonaws.com/dependabot-images/logo-with-name-horizontal.svg?v5" alt="Dependabot" width="336">
 </p>
 
-# Dependabot Pull Request Action
+# Fetch Metadata Action
+
+**Name:** `dependabot/fetch-metadata`
+
+Extract information about the dependencies being updated by a Dependabot-generated PR.
 
-**Name:** `dependabot/pull-request-action`
 ## Usage instructions
 
-Create a workflow file that contains a step that uses: dependabot/pull-request-action@v1`, e.g.
+Create a workflow file that contains a step that uses: dependabot/fetch-metadata@v1`, e.g.
 
 ```yaml
 -- .github/workflows/dependabot-prs.yml
@@ -20,38 +23,96 @@ jobs:
     steps:
     - name: Fetch Dependabot metadata
       id: dependabot-metadata
-      uses: dependabot/pull-request-action
+      uses: dependabot/fetch-metadata
       with:
         github-token: "${{ secrets.GITHUB_TOKEN }}"
 ```
 
-Subsequent actions will have access to `steps.dependabot-metadata.outputs.updated-dependencies` which will contain a
-JSON object with information about the changes, e.g.
-
-```json
-[
-  {
-    "dependencyName": "dependabot-core",
-    "dependencyType": "direct:production",
-    "updateType": "version-update:semver-major"
-  }
-]
-```
+Subsequent actions will have access to the following outputs:
 
-**Note:** This output will only be populated if the target Pull Request was opened by Dependabot and contains **only** Dependabot-created commits.
+- `steps.dependabot-metadata.outputs.dependency-names`
+  - A comma-separated list of the package names updated by the PR.
+- `steps.dependabot-metadata.outputs.dependency-type`
+  - The type of dependency has determined this PR to be, e.g. `direct:production`. For all possible values, see [the `allow` documentation](https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#allow).
+- `steps.dependabot-metadata.outputs.update-type`
+  - The highest semver change being made by this PR, e.g. `version-update:semver-major`. For all possible values, see [the `ignore` documentation](https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#ignore).
+- `steps.dependabot-metadata.outputs.updated-dependencies-json`
+  - A JSON string containing the full information about each updated Dependency.
 
-### Auto-approving
+**Note:** These outputs will only be populated if the target Pull Request was opened by Dependabot and contains
+**only** Dependabot-created commits.
 
-NYI
+This metadata can be used along with Action's [expression syntax](https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#functions) and the [GitHub CLI](https://github.com/cli/cli) to create
+useful automation for your Dependabot PRs.
 
-### Enabling GitHub automerge
+### Auto-approving
 
-NYI
+Since the `dependabot/fetch-metadata` Action will set a failure code if it cannot find any metadata, you can
+have a permissive auto-approval on all Dependabot PRs like so:
 
-## Why?
+```yaml
+name: Dependabot auto-approve
+description: Auto-approve Dependabot PRs
+on: pull_request_target
+permissions:
+  pull-requests: write
+jobs:
+  dependabot:
+    # Checking the actor will prevent your Action run failing on non-Dependabot PRs
+    if: ${{ github.actor == 'dependabot[bot]' }}
+    steps:
+      - name: Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata
+      - name: Approve a PR
+        run: gh pr review --approve "$PR_URL"
+        env:
+          PR_URL: ${{github.event.pull_request.html_url}}
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+```
 
-NYI
+### Enabling GitHub automerge
 
-## Development and release process
+```yaml
+name: Dependabot auto-merge
+description: Enable GitHub Automerge for patch updates on `bar`
+on: pull_request_target
+permissions:
+  pull-requests: write
+jobs:
+  dependabot:
+    if: ${{ github.actor == 'dependabot[bot]' }}
+    steps:
+      - name: Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata
+      - name: Enable auto-merge for Dependabot PRs # respects branch protection rules
+        if: ${{contains(steps.metadata.outputs.dependency-names, "bar") && steps.metadata.outputs.update-type == "version-update:semver-patch"}}
+        run: gh pr merge --auto --merge "$PR_URL"
+        env:
+          PR_URL: ${{github.event.pull_request.html_url}}
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+```
+
+### Labelling
 
-NYI
+```yaml
+name: Dependabot auto-label
+description: Label all production dependencies with the "production" label
+on: pull_request_target
+permissions:
+  pull-requests: write
+jobs:
+  dependabot:
+    if: ${{ github.actor == 'dependabot[bot]' }}
+    steps:
+      - name: Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata
+      - name: Add a label for all production dependencies
+        if: ${{ steps.metadata.outputs.dependency-type == "direct:production" }}
+        run: gh pr edit "$PR_URL" --add-label "production"
+        env:
+          PR_URL: ${{github.event.pull_request.html_url}}
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+```

action.yml

@@ -1,12 +1,18 @@
-name: 'Dependabot PR Automation'
-description: 'Parse Dependabot commit metadata to automate PR handling'
+name: 'Fetch Metadata from Dependabot PRs'
+description: 'Extract information from about the dependency being updated by a Dependabot-generated PR'
 inputs:
   github-token:
     description: 'The GITHUB_TOKEN secret'
     required: true
 outputs:
-  updated-dependencies:
-    description: 'A JSON serialised hash of any metadata found in verified Dependabot commits in the PR.'
+  dependency-names:
+    description: 'A comma-separated list of all package names updated.'
+  dependency-type:
+    description: 'The type of dependency has determined this PR to be, e.g. "direct:production".'
+  update-type:
+    description: 'The highest semver change being made by this PR, e.g. "version-update:semver-major"'
+  updated-dependencies-json:
+    description: 'A JSON string containing the full information about each updated Dependency.'
 runs:
   using: 'node12'
   main: 'dist/index.js'