DEV Community

Jonah Lawrence
Jonah Lawrence

Posted on

GitHub Action for Updating Your Readme with a Download Button

My Workflow

Readme Download Button Action is a new workflow that allows you to keep a direct download link of the latest version of your repo in your README file.

Example download button generated by the workflow:

Download zip

The steps for setting up the workflow are explained in detail on the GitHub repository.

Getting started

name: "Download Button Action"
on:
  release:
    types:
      - published
  workflow_dispatch:
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Get latest release
        id: get-latest-release
        uses: InsonusK/get-latest-release@v1.0.1
        with:
          myToken: ${{ github.token }}
          view_top: 1
      - name: Readme Download Button Action
        env:
          GITHUB_USER: "DenverCoder1"
          REPO: "readme-download-button-action"
          FORMAT: "zip"
          VERSION: "${{ steps.get-latest-release.outputs.tag_name }}"
          COLOR: "blue"
          BEGIN_TAG: "<!-- BEGIN LATEST DOWNLOAD BUTTON -->"
          END_TAG: "<!-- END LATEST DOWNLOAD BUTTON -->"
        run: |
          UPDATE=$(cat README.md | perl -0777 -pe 's#(${{ env.BEGIN_TAG }})(?:.|\n)*?(${{ env.END_TAG }})#${1}\n[![Download ${{ env.FORMAT }}](https://custom-icon-badges.herokuapp.com/badge/-Download-${{ env.COLOR }}?style=for-the-badge&logo=download&logoColor=white "Download ${{ env.FORMAT }}")](https://github.com/${{ env.GITHUB_USER }}/${{ env.REPO }}/archive/${{ env.VERSION }}.${{ env.FORMAT }})\n${2}#g')
          echo "${UPDATE}" > README.md
      - uses: EndBug/add-and-commit@v7
        with:
          message: "docs(readme): Bump download button version to ${{ steps.get-latest-release.outputs.tag_name }}"
          default_author: github_actions
          branch: main
Enter fullscreen mode Exit fullscreen mode

Submission Category:

Maintainer Must-Haves

Yaml File or Link to Code

GitHub logo DenverCoder1 / readme-download-button-action

GitHub Action workflow configuration for keeping a direct download link to the latest version on your repo's readme

Readme Download Button Action

GitHub Action workflow configuration for keeping a direct download link of the latest version in your README.md file.

Example

With a single click of the button below, a zip of this repository will start downloading.

Download zip

The URL this button leads to is automatically updated on each release by this workflow.

Basic Usage

This workflow consists mainly of four parts:

Step 1

Add the following snippet within your README.md file anywhere you want the button to appear:

<!-- BEGIN LATEST DOWNLOAD BUTTON -->
<!-- END LATEST DOWNLOAD BUTTON -->
Enter fullscreen mode Exit fullscreen mode

Step 2

Create a workflow by placing the following in a .yml file in your .github/workflows/ directory:

name: "Download
Enter fullscreen mode Exit fullscreen mode

Background

This project was created due to the fact that many users may come to a repository to download a project but are not familiar enough with the site to navigate the repository and find a proper download link.

This workflow aims to simplify the process, by putting a download button front and center in the Readme so it can't be missed.

Having a download button on the Readme allows visiting users to quickly download your source code with just a single click!

Why does this require a workflow?

In order to make the process a single click away, a direct download link must be included.

For example, a link to download the source code of version 1.0.1 of readme-download-button-action will look like this: https://github.com/DenverCoder1/readme-download-button-action/archive/1.0.1.zip.

Notice that the url contains 1.0.1, the version. This number changes with every new version released, so in order to keep the download button up-to-date, we will have to update the readme to change the link.

That's where this workflow comes in. With just a few seconds of one-time configuration, your button will be generated and automatically kept up to date whenever you make a new release.

Making of this workflow

First, we need to set the trigger event. A good choice here is when we publish a release. Additionally workflow_dispatch: is added so that it can be manually triggered from the Actions tab in case you want to re-run it without creating a new release.

on:
  release:
    types:
      - published
  workflow_dispatch:
Enter fullscreen mode Exit fullscreen mode

Next, we create some steps:

Checkout

In order to be able to read and overwrite the files in the repo such as the readme, we will need to first checkout the repository.

- uses: actions/checkout@v2
Enter fullscreen mode Exit fullscreen mode

Get Latest Release

The following workflow by InsonusK allows us to get info on the latest release. We can access the tag name later using ${{ steps.get-latest-release.outputs.tag_name }}

- name: Get latest release
  id: get-latest-release
  uses: InsonusK/get-latest-release@v1.0.1
  with:
    myToken: ${{ github.token }}
    view_top: 1
Enter fullscreen mode Exit fullscreen mode

The custom shell script

The actual replacement of the button is done with a shell step:

- name: Readme Download Button Action
  env:
    GITHUB_USER: "DenverCoder1"
    REPO: "readme-download-button-action"
    FORMAT: "zip"
    VERSION: "${{ steps.get-latest-release.outputs.tag_name }}"
    COLOR: "blue"
    BEGIN_TAG: "<!-- BEGIN LATEST DOWNLOAD BUTTON -->"
    END_TAG: "<!-- END LATEST DOWNLOAD BUTTON -->"
  run: |
    UPDATE=$(cat README.md | perl -0777 -pe 's#(${{ env.BEGIN_TAG }})(?:.|\n)*?(${{ env.END_TAG }})#${1}\n[![Download ${{ env.FORMAT }}](https://custom-icon-badges.herokuapp.com/badge/-Download-${{ env.COLOR }}?style=for-the-badge&logo=download&logoColor=white "Download ${{ env.FORMAT }}")](https://github.com/${{ env.GITHUB_USER }}/${{ env.REPO }}/archive/${{ env.VERSION }}.${{ env.FORMAT }})\n${2}#g')
    echo "${UPDATE}" > README.md
Enter fullscreen mode Exit fullscreen mode

perl is used here to make a multiline replacement using regular expressions. At first I was going to try sed but it deals with lines one at a time, so it's much more complicated when dealing with multiline matches.

An env section also appears to make configuring the download button as simple as possible.

Add and commit

Finally we can use EndBug's add-and-commit to make the change persist!

- uses: EndBug/add-and-commit@v7
  with:
    message: "docs(readme): Bump download button version to ${{ steps.get-latest-release.outputs.tag_name }}"
    default_author: github_actions
    branch: main
Enter fullscreen mode Exit fullscreen mode

Additional Resources / Info

This action works great in combination with several open-source workflows:

Discussion (2)

Collapse
michaelcurrin profile image
Michael Currin

To clarify on the token.

You are using the built in token, to avoid manually creating a token. As an extra benefit, the built in token only has accept to the current repo and the manually generated one has access to all of a user's repos.

These two are equivalent

env:
  token: ${{ secrets.GITHUB_TOKEN }}
Enter fullscreen mode Exit fullscreen mode
env:
  token: ${{ github.token }}
Enter fullscreen mode Exit fullscreen mode
Collapse
michaelcurrin profile image
Michael Currin

I've added Add and Commit to my notes. I just knew about Publish to GitHub

michaelcurrin.github.io/code-cookb...