Merge pull request #66 from github/feelepxyz/update-readme

.github/workflows/integration-test.yml

@@ -1,6 +1,7 @@
 name: 'ci'
-on: pull_request
-
+on: pull_request_target
+permissions:
+  contents: read
 jobs:
   integration:
     runs-on: ubuntu-latest
@@ -13,7 +14,6 @@ jobs:
         run: docker login docker.pkg.github.com -u x -p ${{ secrets.GPR_TOKEN }}
       - name: GRP pull
         run: docker pull docker.pkg.github.com/dependabot/dependabot-updater:latest
-      - run: |
-          npm ci
+      - run: npm ci
       - name: Run integration test files
-        run: npm test "integration"
+        run: npm run test-integration

.github/workflows/test.yml

@@ -11,10 +11,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - run: |
-          npm ci
-      - run: |
-          SKIP_INTEGRATION_TESTS=true npm run all
+      - run: npm ci
+      - run: npm run all
   test: # make sure the action works on a clean machine without building
     runs-on: ubuntu-latest
     steps:

README.md

@@ -1,20 +1,20 @@
 ## Setup
 
-> First, you'll need to have a reasonably modern version of `node` handy. This won't work with versions older than 9, for instance.
+### Prerequisites
 
-Install the dependencies
+**node**: e.g. `brew install node` on Mac
 
-```bash
-$ npm install
-```
+**docker**: e.g. `brew install docker` on Mac
 
-Build the typescript and package it for distribution
+### Project dependencies
 
 ```bash
-$ npm run package
+$ npm install
 ```
 
-Run the tests :heavy_check_mark:
+## Tests
+
+Run the tests (excluding integration tests) :heavy_check_mark:
 
 ```bash
 $ npm test
@@ -27,67 +27,73 @@ $ npm test
 ...
 ```
 
-## Change action.yml
+### Running integration tests
 
-The action.yml contains defines the inputs and output for your action.
-
-Update the action.yml with your name, description, inputs and outputs for your action.
+```bash
+$ npm run test-integration
+```
 
-See the [documentation](https://help.github.com/en/articles/metadata-syntax-for-github-actions)
+The integration test will time out if you don't already have the docker image on
+your local machine.
 
-## Change the Code
+You'll need to create a [GitHub PAT](https://github.com/settings/tokens/new)
+(Personal Access Token) to access the updater image hosted on [dependabot/dependabot-updater](https://github.com/dependabot/dependabot-updater/pkgs/container/dependabot-updater%2Fdependabot-updater).
 
-Most toolkit and CI/CD operations involve async operations so the action is run in an async function.
+Create the PAT with `read:packages` permissions checked and export it:
 
-```javascript
-import * as core from '@actions/core';
-...
+```bash
+export GPR_TOKEN=_pat_with_read_packages_
+```
 
-async function run() {
-  try {
-      ...
-  }
-  catch (error) {
-    core.setFailed(error.message);
-  }
-}
+Pull the updater image:
 
-run()
+```bash
+docker login docker.pkg.github.com -u x -p $GPR_TOKEN
+docker pull docker.pkg.github.com/dependabot/dependabot-updater:latest
 ```
 
-See the [toolkit documentation](https://github.com/actions/toolkit/blob/master/README.md#packages) for the various packages.
+#### Debugging the fake dependabot-api json-server
 
-## Publish to a distribution branch
+Integration tests run against a fake dependabot-api server using
+[json-server](https://github.com/typicode/json-server).
 
-Actions are run from GitHub repos so we will checkin the packed dist folder.
+Initial responses are defined in `__tess__/server/db.json` and the server itself
+configured in `__tests__server/server.js`.
 
-Then run [ncc](https://github.com/zeit/ncc) and push the results:
+Run the api server outside of tests:
 
 ```bash
-$ npm run package
-$ git add dist
-$ git commit -a -m "prod dependencies"
-$ git push origin releases/v1
+node __tests__/server/server.js
+```
+
+Inspect resources:
+
+```bash
+curl http://localhost:9000/update_jobs/1/details
 ```
 
-Note: We recommend using the `--license` option for ncc, which will create a license file for all of the production node modules used in your project.
+### Running against a local dependabot-api instance
 
-Your action is now published! :rocket:
+TBD
 
-See the [versioning documentation](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
+## Releasing a new version of the action
 
-## Validate
+Actions executes the `dist/index.js` file when run, defined in `action.yml`. This is packaged using [ncc](https://github.com/zeit/ncc).
 
-You can now validate the action by referencing `./` in a workflow in your repo (see [test.yml](.github/workflows/test.yml))
+To update the `dist/index.js` run:
 
-```yaml
-uses: ./
-with:
-  milliseconds: 1000
+```bash
+$ npm run package
 ```
 
-See the [actions tab](https://github.com/actions/typescript-action/actions) for runs of this action! :rocket:
+### Tagging releases
+
+When tagging a release, use semver e.g. `v1.0.0`.
+
+Also update the major version tag to point to the latest major release, e.g. `git tag v1`.
+
+### Major versions
 
-## Usage:
+Create a new `releases/v1` branch before merging a `v2` branch to main to allow releasing patch releases of previous major versions.
 
-After testing you can [create a v1 tag](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) to reference the stable and latest V1 action
+![versioning](https://github.com/actions/toolkit/blob/master/docs/assets/action-releases.png)

action.yml

@@ -1,6 +1,6 @@
 name: 'Updater Action'
-description: 'Provide a description here'
-author: 'Your name or organization here'
+description: 'Runs dependabot-updater in Actions'
+author: 'GitHub'
 runs:
   using: 'node12'
   main: 'dist/index.js'

package.json

@@ -8,7 +8,8 @@
     "format": "prettier --write **/*.ts",
     "lint": "eslint --fix **/*.ts",
     "package": "rm -f ./output/output.json && ncc build --source-map --license licenses.txt",
-    "test": "jest --detectOpenHandles",
+    "test": "SKIP_INTEGRATION_TESTS=true jest --detectOpenHandles",
+    "test-integration": "jest --detectOpenHandles 'integration'",
     "prepare": "husky install",
     "all": "npm run format && npm run lint && npm run package && npm test"
   },