Skip to content
bar-chart-2

GitHub Action

Copilot Usage Action

v4.1 Latest version

Copilot Usage Action

bar-chart-2

Copilot Usage Action

Get reports on GitHub Copilot Usage

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: Copilot Usage Action

              
  uses: austenstone/copilot-usage@v4.1
Learn more about this action in austenstone/copilot-usage

Choose a version

Copilot Usage Action

Get Copilot usage data as:

  • Md Job Summary
  • CSV
  • XML
  • JSON

Powered by the REST API endpoints for GitHub Copilot usage metrics.

Tip

🚀 Get this running FAST by using the template

Usage

Create a workflow (eg: .github/workflows/copilot-usage.yml). See Creating a Workflow file.

PAT(Personal Access Token)

You will need to create a PAT(Personal Access Token) that has the copilot, manage_billing:copilot, admin:org, admin:enterprise, or manage_billing:enterprise scope to use this endpoint.

Add this PAT as a secret so we can use it as input github-token, see Creating encrypted secrets for a repository.

Basic Example

The default behavior is to get the usage for the repository owner which is likely the organization.

Important

You need to set the secret TOKEN in your repository settings.

name: Copilot Usage
on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:

jobs:
  run:
    name: Run Action
    runs-on: ubuntu-latest
    steps:
      - uses: austenstone/copilot-usage@v4.2
        with:
          github-token: ${{ secrets.TOKEN }}
          time-zone: 'EST'

Example get team usage

      - uses: austenstone/copilot-usage@v4.2
        with:
          github-token: ${{ secrets.TOKEN }}
          organization: 'org-slug'
          team: 'team-slug'

Example get enterprise usage

      - uses: austenstone/copilot-usage@v4.2
        with:
          github-token: ${{ secrets.TOKEN }}
          enterprise: 'enterprise-slug'

Example get CSV

      - uses: austenstone/copilot-usage@v4.2
        with:
          github-token: ${{ secrets.TOKEN }}
          csv: true

Example multiple teams

    strategy:
      matrix:
        team:
          - 'team-slug1'
          - 'team-slug2'
    steps:
      - uses: actions/checkout@v4
      - uses: austenstone/copilot-usage@v4.2
        with:
          github-token: ${{ secrets.TOKEN }}
          organization: 'org-slug'
          team: ${{ matrix.team }}

Example specific timezone

You probably want to specify the timezone to get the usage in your local time. The default is UTC. EX: EST, PST, CST, etc.

      - uses: austenstone/copilot-usage@v4.2
        with:
          github-token: ${{ secrets.TOKEN }}
          organization: 'org-slug'
          time-zone: 'EST'

Example sending email PDF report

Important

You must set secrets for EMAIL and PASSWORD to send the email. You must use an App Password for Gmail.

name: Email Copilot Report
on:
  workflow_dispatch:
  schedule:
    - cron: '0 0 * * *'

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: austenstone/copilot-usage@v4.2
        with:
          github-token: ${{ secrets.TOKEN }}
      - uses: austenstone/job-summary@v2.0
        id: pdf
        with:
          name: copilot-usage
      - uses: dawidd6/action-send-mail@v4
        with:
          server_address: smtp.gmail.com
          server_port: 465
          username: ${{ secrets.EMAIL }}
          password: ${{ secrets.PASSWORD }}
          from: ${{ secrets.EMAIL }}
          to: ${{ secrets.EMAIL }} # Recipient email
          subject: "Copilot Usage Report (${{ steps.usage.outputs.since }} - ${{ steps.usage.outputs.until }})"
          html_body: |
            <!DOCTYPE html>
            <html>
            
            <body>
              <h1>Copilot Usage Report</h1>
              <p>Attached is the Copilot Usage Report for ${{ steps.usage.outputs.since }} - ${{ steps.usage.outputs.until }}!</p>
              <p>
                <a href="https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}#:~:text=Copilot%20Usage%20summary">View the full report on
                  GitHub.com</a>
              </p>

              ${{ steps.pdf.outputs.job-summary-html }}
              
            </body>
            
            </html>
          attachments: ${{ steps.pdf.outputs.pdf-file }}

Tip

Try using other messaging systems such as slack, teams, discord, etc.

image

➡️ Inputs

We look first for enterprise input, then team, and finally organization. If none are provided, we default to the repository owner which is likely the organization.

Various inputs are defined in action.yml:

Name Description Default
github-token The GitHub token used to create an authenticated client
enterprise The GitHub enterprise slug
organization The organization slug ${{ github.repository_owner }}
job-summary Whether to generate a report true
csv Whether to generate a CSV as a workflow artifact false
csv-options The options for the CSV report
xml Whether to generate an XML as a workflow artifact false
xml-options The options for the XML report
team The team slug
days The number of days to show usage metrics for
since Show usage metrics since this date. This is a timestamp, in YYYY-MM-DD format. Maximum value is 28 days ago
until Show usage metrics until this date. This is a timestamp, in YYYY-MM-DD format. Maximum value is 28 days ago
time-zone The time zone to use for the report UTC

⬅️ Outputs

Name Description
result The copilot usage as a JSON string
since The date since which the usage metrics are shown
until The date until which the usage metrics are shown

Endpoints

The endpoints used by this action...

  • GET /enterprises/{enterprise}/copilot/usage
  • GET /orgs/{org}/team/{team}/copilot/usage
  • GET /orgs/{org}/copilot/usage
  • GET /orgs/{org}/copilot/billing
  • GET /orgs/{org}/copilot/billing/seats

Example Job Summary

View latest reports