Table of contents
Introduction
In a previous blog post we discussed how to use the Vaunt API to retrieve data such as contributors for private repositories. For public repositories or user contributions, it is easy to embed as you can simply use the Vaunt API link without an authorization header to retrieve public information. See the introduction to developer cards for an example of how the public cards can already be used in your GitHub profile or public repositories. The process for private repositories, however, required quite a bit of manual work to get a Vaunt Token and then use that token in future requests. There was also not really a good way to use the API routes that returned SVGs with your repository as you cannot embed your token for API requests. For these reasons, we decided to create a public action to make it much easier to embed and update Vaunt cards in private repositories.
GitHub Actions
GitHub Actions provide a way to automate and customize workflows within a GitHub repository. Refer to the GitHub documentation for more information about how to create and use your actions. Here we will discuss how we created the Vaunt action and what it does as well as how you can add it to your repositories.
The Vaunt action is published on the GitHub Marketplace here and you may find the action source code in the repository here. Once you have added the workflow you will also need to make sure that your repository gives Workflows Read and Write permissions as it uses these to check in the contributors file. To do this in your repository go to settings->Actions->General and scroll down to the Workflow permissions section:
The last thing to know, if you are installing this on a private repository you will need to generate a GitHub Personal Access Token and provide it as a secret to the action as input. The authentication process is described in more detail in another blog, but for this action, you just need to know that you will use a GitHub token for input to validate that you are the owner or admin of the repository.
Once you have created a token as described here you can add the token as a repository secret to be provided as a parameter in the workflow. You can do this by going to settings in your repository and selecting Secrets and variables->actions:
Click the button that says New repository secret, give it a name that you will use in the workflow such as “PAT” for Personal Access Token, and paste the token string as the secret. Then in your workflow file, make sure that you have the token provided as input using the with field like this:
with:
# Github Personal Access Token for private repositories
token: ${{ secrets.PAT }}
Workflow Explanation
To use an action in your repository you must first set up a workflow. To get started you can click on the Actions button on your repository in GitHub and configure a workflow that includes the Vaunt Cards Action.
To make things a bit easier, if you have never set up a workflow before we have provided an example workflow on our readme here.
See the example workflow below:
name: Vaunt Cards Update
on:
workflow_dispatch:
schedule:
- cron: 30 * * * *
jobs:
my_job:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Update Vaunt Cards
uses: VauntDev/vaunt-cards-action@main
with:
# GitHub Personal Access Token for private repositories
token: ${{ secrets.PAT }}
limit: 10
The workflow_dispatch status event is a way to have a workflow manually triggered. In our case we want the workflow to start on a cron schedule and attempt to pull down the Vaunt status cards if they have updated. In this example it is using cron: 30 * * * * which means it will run every hour at 30 minutes after the hour. Feel free to adjust this to a time that you prefer. One thing to note about this workflow_dispatch method is that the action will only run when this is added to the default branch of your repository.
This particular job checks out the current default branch, then calls the Vaunt Cards Action, which will update the contributors card at .vaunt/cards/contributors.svg and then check in the updated file.
Additionally, if you would prefer to keep your files in a separate branch you can modify the Checkout step to pick a specific branch of your repository to checkout. For example, if you use an assets branch your Checkout step would look like this:
- name: Checkout
uses: actions/checkout@v3
with: { ref: assets }
There are also two optional input values you can set on the vaunt-cards-action. The first value is token which sets the GitHub Personal Access Token to use for authentication if you want to run this action on a private repository. This should be the name of the repository secret that was explained earlier. The other input value is limit, and this sets the maximum number of contributors to include in the response. By default, it uses 10, but this value can be set to up to 100 to return the maximum number of contributors.
Using the Card
Once you have the workflow up and running you will now have a location where the contributors.svg file is being updated and you can reference this file in your repository readme. The process for this is very similar to using the public Vaunt API as described in an earlier blog. The only difference is instead of using an API link you will be referencing a local SVG image that has been checked into your repository with the GitHub Action. One way to do this is with a simple markdown image link. Assuming you have the card on your main branch you would do that by adding the following to your readme:
If you set up your workflow to checkout and place the image in a separate branch then you can still use a markdown link, but you must use the full URL path:
Summary
In this post, we have explained how to use the new Vaunt GitHub Action to generate Vaunt cards for your repositories. You can find the action on the GitHub Marketplace or see the Vaunt Cards Action repository for more information.
Also, check out the Vaunt docs for information on how to get started with Vaunt.
Vaunt is still in the early stages of release and new installations will have access to use Vaunt on both public and private repositories for free.
Join our community on Discord or follow us on Twitter for more information or to reach out if you have any questions.
Get started with Vaunt by installing it today!