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.
Being that today I used it to get the same insights from a Github Org where I currently work, which contains 1.4k of repositories.
— lbrealdeveloper (@lbrealdeveloper) June 15, 2023
And this was running for a considerable time. I am only related to only a few repositories within this organization.
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
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.dev)" >> 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?