How to create a GitHub Action that creates a release in GitHub

Step 1: Set Up the GitHub Workflows Directory

GitHub Actions are defined in YAML files stored in a specific directory within your repository.

  1. Create the .github/workflows directory:
    • In your repository’s root directory, create a folder named .github.
    • Inside .github, create a subfolder named workflows. The full path is .github/workflows/.
    • This is where GitHub looks for workflow configuration files.
  2. Create a YAML file:
    • Inside .github/workflows/, create a new file with a .yml extension, e.g., create-release.yml.
    • The file name can be anything, but it should be descriptive (e.g., release.yml, build-and-release.yml).

Step 2: Add the Workflow Configuration

Copy the following YAML content into your create-release.yml file. This workflow creates a zipped release of your project files and attaches it to a GitHub release when triggered.

name: Create Release for YouTube Pro

on:
  workflow_dispatch:
    inputs:
      tag:
        description: 'Release Tag'
        required: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Create temporary directory
      run: mkdir temp_dir

    - name: Copy files to temporary directory
      run: |
        find . -maxdepth 1 -not -name 'temp_dir' -not -name '.' -not -name '.git' -not -name '.github' -exec cp -r {} temp_dir/ \;

    - name: Rename directory
      run: mv temp_dir youtube-for-wordpress-pro

    - name: Zip the folder
      run: |
        zip -r youtube-for-wordpress-pro-${{ github.event.inputs.tag }}.zip youtube-for-wordpress-pro \
        -x "*.git/*" "*.github/*" \
        "youtube-for-wordpress-pro/package.json" \
        "youtube-for-wordpress-pro/package-lock.json" \
        "youtube-for-wordpress-pro/src/*" \
        "youtube-for-wordpress-pro/node_modules/*" \
        "youtube-for-wordpress-pro/.gitignore"

    - name: Create Release
      uses: softprops/action-gh-release@v1
      with:
        files: youtube-for-wordpress-pro-${{ github.event.inputs.tag }}.zip
        tag_name: ${{ github.event.inputs.tag }}
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

permissions:
  contents: write

Step 3: Understand the Workflow

Here’s a breakdown of what the workflow does:

  • Name: The workflow in this example is named Create Release for YouTube Pro. This appears in the GitHub Actions UI.
  • Trigger: The workflow runs manually (workflow_dispatch) and requires a tag input (e.g., v1.0.0) provided by the user.
  • Job (build): Runs on an ubuntu-latest runner with the following steps:
    1. Checkout code: Uses actions/checkout@v4 to clone the repository.
    2. Create temporary directory: Creates a folder named temp_dir.
    3. Copy files: Copies all files from the repository root (excluding .git, .github, and temp_dir) to temp_dir.
    4. Rename directory: Renames temp_dir to youtube-for-wordpress-pro.
    5. Zip the folder: Creates a ZIP file named youtube-for-wordpress-pro-<tag>.zip, excluding specified files/folders (e.g., .git, node_modules).
    6. Create release: Uses softprops/action-gh-release@v1 to create a GitHub release with the provided tag and attaches the ZIP file.
  • Permissions: Grants contents: write to allow the workflow to create releases.
  • Environment: Uses the GITHUB_TOKEN secret (automatically provided by GitHub) for authentication.

Step 4: Customize the YAML for Your Project

To use this workflow for your project, you need to modify specific parts of the YAML file. Below are the fields you should change:

  1. Workflow Name:
    • Field: name: Create Release for YouTube Pro
    • What to change: Replace Create Release for YouTube Pro with a name relevant to your project, e.g., Create Release for MyProject.
    • Example:
    • name: Create Release for MyProject
  2. Directory Name:
    • Field: youtube-for-wordpress-pro (appears in mv temp_dir youtube-for-wordpress-pro and ZIP step).
    • What to change: Replace youtube-for-wordpress-pro with the desired name for your zipped folder. This is the name of the directory that will be zipped and included in the release.
    • Example: If your project is called my-plugin, update:
    • - name: Rename directory run: mv temp_dir my-plugin
    • And in the ZIP step:
    • zip -r my-plugin-${{ github.event.inputs.tag }}.zip my-plugin \
  3. ZIP File Name:
    • Field: youtube-for-wordpress-pro-${{ github.event.inputs.tag }}.zip (in the ZIP and release steps).
    • What to change: Replace youtube-for-wordpress-pro with your project’s name to name the ZIP file appropriately.
    • Example:
    • zip -r my-plugin-${{ github.event.inputs.tag }}.zip my-plugin \
    • And in the release step:
    • files: my-plugin-${{ github.event.inputs.tag }}.zip
  4. Excluded Files/Folders:
    • Field: The -x exclusions in the ZIP step, e.g., “youtube-for-wordpress-pro/package.json”, “youtube-for-wordpress-pro/node_modules/*”.
    • What to change: Update the paths to match your project’s directory structure and the files/folders you want to exclude from the ZIP. Anything that exists in your GitHub repository that you DON’T want included in the release, such as node_modules, package.json etc should be excluded here.
    • Example: If you want to exclude a folder named tests and a file named config.yml:
    • -x "*.git/*" "*.github/*" \
    • "my-plugin/tests/*" \
    • "my-plugin/config.yml"

Step 5: Commit and Push the Workflow

  1. Save the modified create-release.yml file in .github/workflows/.
  2. Commit the file to your repository and push it to GitHub:

Step 6: Trigger the Workflow

  1. Go to your repository on GitHub.
  2. Click the Actions tab.
  3. Select the workflow named Create Release for <Your Project> (or whatever you named it).
  4. Click Run workflow (on the right side).
  5. Select the branch you want to create a release for.
  6. Enter a release tag (e.g., v1.0.0) in the input field.
  7. Click Run workflow.

The workflow will:

  • Check out your code.
  • Create a temporary directory and copy files.
  • Zip the specified folder (excluding unwanted files).
  • Create a GitHub release with the provided tag and attach the ZIP file.

You can monitor the progress in the Actions tab. Once completed, check the Releases section of your repository to verify the new release and attached ZIP file.

Step 7: Test and Debug

  • Check the output: If the workflow fails, click the failed run in the Actions tab to view logs and identify errors (e.g., missing files, permission issues).
  • Verify exclusions: Ensure the ZIP file contains only the intended files by downloading and inspecting it.
  • Adjust permissions: The permissions: contents: write setting is required for creating releases. If you encounter permission errors, ensure your repository settings allow GitHub Actions to write to the repository.

Customization Tips

  • Automate triggering: Instead of workflow_dispatch, you can trigger the workflow on events like pushing a tag:
  • on: push: tags: - 'v*'
  • Then, use ${{ github.ref_name }} instead of ${{ github.event.inputs.tag }} for the tag name.
  • Add more steps: If your project requires building or compiling (e.g., running npm build), add those steps before zipping.
  • Multiple files: To include additional files in the release, modify the files field in the softprops/action-gh-release step:
  • files: | my-plugin-${{ github.event.inputs.tag }}.zip another-file.txt

Example: Customized YAML for a Project Named my-plugin

Here’s what the YAML might look like after customizing for a project named my-plugin:

name: Create Release for MyPlugin

on:
  workflow_dispatch:
    inputs:
      tag:
        description: 'Release Tag'
        required: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Create temporary directory
      run: mkdir temp_dir

    - name: Copy files to temporary directory
      run: |
        find . -maxdepth 1 -not -name 'temp_dir' -not -name '.' -not -name '.git' -not -name '.github' -exec cp -r {} temp_dir/ \;

    - name: Rename directory
      run: mv temp_dir my-plugin

    - name: Zip the folder
      run: |
        zip -r my-plugin-${{ github.event.inputs.tag }}.zip my-plugin \
        -x "*.git/*" "*.github/*" \
        "my-plugin/tests/*" \
        "my-plugin/config.yml"

    - name: Create Release
      uses: softprops/action-gh-release@v1
      with:
        files: my-plugin-${{ github.event.inputs.tag }}.zip
        tag_name: ${{ github.event.inputs.tag }}
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

permissions:
  contents: write

Additional Notes

  • Security: The GITHUB_TOKEN secret is automatically provided by GitHub and doesn’t require manual setup. Ensure your workflow has the necessary permissions (contents: write).
  • Versioning: Use semantic versioning (e.g., v1.0.0) for tags to maintain clarity.

This workflow is a solid foundation for automating releases. Customize it further based on your project’s needs, such as adding build steps or supporting multiple artifacts.If you have questions or need help debugging, let me know!