Merge pull request #92 from steve-norman-rft/license-usage

Read license type from an exported enterprise license csv

README.md

@@ -13,16 +13,18 @@ This action generates a report for an enterprise with the following elements:
 
 This actions has the following inputs:
 
-| Parameter  | Description                                                                                           | Default | Is Required |
-|------------|-------------------------------------------------------------------------------------------------------|---------|-------------|
-| token      | A personal access token with permissions on all the orgs of the enterprise                            | None    | ✅           |
-| enterprise | The enterprise where we want to generate the report                                                   | None    | ✅           |
-| format     | Determines how the output parameter will be formatted. Supports: `json`, `markdown`, `csv` and `html` | None    | ✅           |
+| Parameter           | Description                                                                                           | Default | Is Required |
+|---------------------|-------------------------------------------------------------------------------------------------------|---------|-------------|
+| token               | A personal access token with permissions on all the orgs of the enterprise                            | None    | ✅           |
+| enterprise          | The enterprise where we want to generate the report                                                   | None    | ✅           |
+| format              | Determines how the output parameter will be formatted. Supports: `json`, `markdown`, `csv` and `html` | None    | ✅           |
+| licenseUsage        | Enterprise License consumption CSV contents                                                           | None    | ❎           |
+| licenseUsageChanged | Enterprise License consumption CSV last changed date/time                                             | None    | ❎           |
 
 This action has the following outputs:
 
-| Parameter | Description                                                                                                   |
-|-----------|---------------------------------------------------------------------------------------------------------------|
+| Parameter | Description                                                                                                    |
+|-----------|----------------------------------------------------------------------------------------------------------------|
 | data      | The data extracted from the license API calls in the format specified. The type of the output is always string |
 
 Here you can see a workflow example using this action:
@@ -51,6 +53,50 @@ jobs:
     - run: echo '${{ steps.report.outputs.data }}'
 ```
 
+## License Consumption Merging
+
+At present it is not possible to use the GitHub API to obtain the type of license a user is consuming. 
+You can download the `consumed_licenses.csv` file from the enterprise portal, https://docs.github.com/en/billing/managing-your-license-for-github-enterprise/viewing-license-usage-for-github-enterprise, 
+and the action can merge this information into the report. You will need to commit the `consumed_licenses.csv` to your repository, and update it when you need an up to date report.  
+
+You will also need to ensure that the action has the content available for it, add the following step before you generate any reports:
+
+```yml
+      - name: Export license usage data
+        run: | 
+          if [[ -f consumed_licenses.csv ]]; then
+            echo "LICENSEUSAGE_CSV<<EOF" >> $GITHUB_ENV
+            cat consumed_licenses.csv >> $GITHUB_ENV
+            echo "EOF" >> $GITHUB_ENV
+            echo "LICENSEUSAGE_CSV_CHANGED=$(stat -c'%Y' consumed_licenses.csv | date -Iseconds)" >> $GITHUB_ENV
+          fi
+```
+
+Then you can update the report generator with the extra settings:
+
+```yml
+      - name: Generate CSV report
+        id: report_csv
+        uses: ActionsDesk/enterprise-members-report-action@latest
+        env:
+          GITHUB_TOKEN: ${{ secrets.YOUR_SECRET_TOKEN }}
+        with:
+          enterprise: avocado-corp
+          format: 'csv'
+          licenseUsage: ${{ env.LICENSEUSAGE_CSV }}
+          licenseUsageChanged: ${{ env.LICENSEUSAGE_CSV_CHANGED }}
+```
+
+A new column will be added to the generated report with type of licensed consumed by the user:
+
+| Login         | Emails             | Orgs                         | Membership           | Created At           | License (2021-09-10T16:54:27+01:00) |
+| ------------- | ------------------ | ---------------------------- | -------------------- | -------------------- | ----------------------------------- |
+| gwenavocado   | [email protected]   | avocado-haas                 | member               | 2020-09-29T14:07:38Z | Visual Studio subscription          |
+| fuerteavocado | [email protected] | avocado-haas,avocado-zutano  | member               | 2020-10-14T21:25:58Z | Enterprise                          |
+| toast         | [email protected]    | avocado-zutano               | outside collaborator | 2020-10-14T21:25:58Z | Enterprise                          |
+
+The variable `licenseUsageChanged` is optional and if supplied with be included in the `License` column header as a reference for when the `consumed_licenses.csv` file was last modified.
+
 ## Token permissions
 
 The required scopes for this action to run are:

action.yml

@@ -8,6 +8,12 @@ inputs:
   format:
     required: true
     description: 'Determines how the output parameter will be formatted. Supports: json, markdown, csv and html'
+  licenseUsage:
+    required: false
+    description: 'Will merge in the output from an enterprise license usage csv available from https://github.com/enterprises/{{enterprise}}/enterprise_licensing/download_consumed_licenses'
+  licenseUsageChanged:
+    required: false
+    description: 'When the license usage data was generated so that it can be included in the reports'
 outputs:
   data: 
     description: 'The data extracted from the license API calls in the format specified. The type of the output is always string'