Understand your usage of GitHub Actions

Learn how you or your team is using GitHub Actions across your personal account or organisation.

Whenever GitHub Actions users get in touch with us to ask about actuated, we ask them a number of questions. What do you build? What pain points have you been running into? What are you currently spending? And then - how many minutes are you using?

That final question is a hard one for many to answer because the GitHub UI and API will only show billable minutes. Why is that a problem? Some teams only use open-source repositories with free runners. Others may have a large free allowance of credit for one reason or another and so also don't really know what they're using. Then you have people who already use some form of self-hosted runners - they are also excluded from what GitHub shows you.

So we built an Open Source CLI tool called actions-usage to generate a report of your total minutes by querying GitHub's REST API.

And over time, we had requests to break-down per day - so for our customers in the Middle East like Kubiya, it's common to see a very busy day on Sunday, and not a lot of action on Friday. Given that some teams use mono-repos, we also added the ability to break-down per repository - so you can see which ones are the most active. And finally, we added the ability to see hot-spots of usage like the longest running repo or the most active day.

You can run the tool in three ways:

  • Against an organisation
  • Against a personal user account
  • Or in a GitHub Action

I'll show you each briefly, but the one I like the most is the third option because it's kind of recursive.

Before we get started, download arkade, and use it to install the tool:

# Move the binary yourself into $PATH
curl -sLS https://get.arkade.dev | sh

# Have sudo move it for you
curl -sLS https://get.arkade.dev | sudo sh
arkade install actions-usage

Or if you prefer - you can add my brew tap, or head over to the arkade releases page.

Later on, I'll also show you how to use the alexellis/arkade-get action to install the tool for CI.

Finding out about your organisation

If you want to find out about your organisation, you can run the tool like this:

actions-usage \
    -org $GITHUB_REPOSITORY_OWNER \
    -days 28 \
    -by-repo \
    -punch-card \
    -token-file ~/PAT.txt

You'll need a Personal Access Token, there are instructions on how to create this in the actions-usage README file

There are many log lines printed to stderr during the scan of repositories and the workflows. You can omit all of this by adding 2> /dev/null to the command.

First off we show the totals:

Fetching last 28 days of data (created>=2023-05-19)

Generated by: https://github.com/self-actuated/actions-usage
Report for actuated-samples - last: 28 days.

Total repos: 24
Total private repos: 0
Total public repos: 24

Total workflow runs: 107
Total workflow jobs: 488

Total users: 1

Then break down on success/failure and cancelled jobs overall, plus the biggest and average build time:

Success: 369/488
Failure: 45/488
Cancelled: 73/488

Longest build: 29m32s
Average build time: 1m26s

Next we have the day by day breakdown. You can see that we try to focus on our families on Sunday at OpenFaaS Ltd, instead of working:

Day            Builds
Monday         61
Tuesday        50
Wednesday      103
Thursday       110
Friday         153
Saturday       10
Sunday         0
Total          488

Our customers in the Middle East work to a different week, and so you'd see Saturday with no builds or nothing, and Sunday like a normal working day.

Then we have the repo-by-repo breakdown with some much more granular data:

Repo                                      Builds         Success        Failure        Cancelled      Skipped        Total          Average        Longest
actuated-samples/k3sup-matrix-test        355            273            20             62             0              2h59m1s        30s            1m29s
actuated-samples/discourse                49             38             7              4              0              6h37m21s       8m7s           20m1s
actuated-samples/specs                    35             31             1              3              0              10m20s         18s            32s
actuated-samples/cypress-test             17             4              13             0              0              6m23s          23s            49s
actuated-samples/cilium-test              9              4              2              3              0              1h10m41s       7m51s          29m32s
actuated-samples/kernel-builder-linux-6.0 9              9              0              0              0              11m28s         1m16s          1m27s
actuated-samples/actions-usage-job        8              4              2              1              0              46s            6s             11s
actuated-samples/faasd-nix                6              6              0              0              0              24m20s         4m3s           10m49s

Finally, we have the original value that the tool set out to display:

Total usage: 11h40m20s (700 mins)

We display the value in a Go duration for readability and in minutes because that's the number that GitHub uses to talk about usage.

One customer told us that they were running into rate limits when querying for 28 days of data, so they dropped down to 14 days and then multiplied the result by two to get a rough estimate.

-days 14 

The team at Todoist got in touch with us to see if actuated could reduce their bill on GitHub Actions. When he tried to run the tool the rate-limit was exhausted even when he changed the flag to -days 1. Why? They were using 550,000 minutes!

So we can see one of the limitations already of this approach. Fortunately, actuated customers have their job stats recorded in a database and can generate reports from the dashboard very quickly.

Finding out about your personal account

Actuated isn't built for personal users, but for teams, so we didn't add this feature initially. Then we saw a few people reach out via Twitter and GitHub and decided to add it for them.

For your personal account, you only have to change one of the input parameters:

actions-usage \
    -user alexellis \
    -days 28 \
    -by-repo \
    -punch-card \
    -token-file ~/ae-pat.txt 2> /dev/null 

Now I actually have > 250 repositories and most of them don't even have Actions enabled, so this makes the tool less useful for me personally. So it was great when a community member suggested offering a way to filter repos when you have so many that the tool takes a long time to run or can't complete due to rate-limits.

I've already created an issue and have found someone who'd like to contribute the change: Offer a way to filter repos for large organisations / users #8

This is the beauty of open source and community. We all get to benefit from each other's ideas and contributions.

Running actions-usage with a GitHub Action

Now this is my favourite way to run the tool. I can run it on a schedule and get a report sent to me via email or Slack.

Example output from running the tool as a GitHub Action

Example output from running the tool as a GitHub Action

Create actions-usage.yaml in your .github/workflows folder:

name: actions-usage

on:
  push:
    branches:
      - master
      - main
  workflow_dispatch:

permissions:
  actions: read

jobs:
  actions-usage:
    name: daily-stats
    runs-on: actuated-any-1cpu-2gb
    steps:
    - uses: alexellis/arkade-get@master
      with:
        actions-usage: latest
        print-summary: false
    - name: Generate actions-usage report
      run: |
       echo "### Actions Usage report by [actuated.dev](https://actuated.com)" >> SUMMARY
       echo "\`\`\`" >> SUMMARY
       actions-usage \
        -org $GITHUB_REPOSITORY_OWNER \
        -days 1 \
        -by-repo \
        -punch-card \
        -token ${{ secrets.GITHUB_TOKEN }}  2> /dev/null  >> SUMMARY
       echo "\`\`\`" >> SUMMARY
       cat SUMMARY >> $GITHUB_STEP_SUMMARY

Ths is designed to run within an organisation, but you can change the -org flag to -user and then use your own username.

The days are for the past day of activity, but you can change this to any number like 7, 14 or 28 days.

You can learn about the other flags by running actions-usage --help on your own machine.

Wrapping up

actions-usage is a practical tool that we use with customers to get an idea of their usage and how we can help with actuated. That said, it's also a completely free and open source tool for which the community is finding their own set of use-cases.

And there are no worries about privacy, we've gone very low tech here. The output is only printed to the console, and we never receive any of your data unless you specifically copy and paste the output into an email.

Feel free to create an issue if you have a feature request or a question.

Check out self-actuated/actions-usage on GitHub

I wrote an eBook writing CLIs like this in Go and keep it up to date on a regular basis - adding new examples and features of Go.

Why not check out what people are saying about it on Gumroad?

Everyday Go - The Fast Track