Skip to content
This repository has been archived by the owner on Jan 22, 2024. It is now read-only.

Latest commit

 

History

History
309 lines (235 loc) · 10.6 KB

README.md

File metadata and controls

309 lines (235 loc) · 10.6 KB

Automate Your Workflows with GitHub Actions and GitHub Packages

🔖 The following instructions will take on the assumption that you will be completing the steps on the GitHub UI. Feel free to use the terminal or any other GUIs you are comfortable with.

workflow

Workflow 1: Steps to set up CI workflow

  1. This repository comes with npm project files, namely package.json (contains your node project meta data) and index.js (your source code).

  2. Fork this repository and edit the package.json file by replacing the placeholders OWNER with your GitHub handle or organization name (if you created the repository in an organization), and REPOSITORY_NAME.

  3. Create the following file to the default branch:

    • .github/workflows/ci.yml
      • This will be the workflow file taking care of building and testing your source code
      • The file content will be empty for now
  4. After the above steps are finished, you should have the following files in your repository;

    • package.json
    • index.js
    • .github/workflows/ci.yml
  5. 🎉 If everything looks fine so far, it's time to start creating our CI workflow!

  6. Go to .github/workflows/ci.yml and enter edit mode by clicking the pencil 📝 icon

    Click here to view file contents to copy:

    #####################################
    #      Automate your workflow       #
    #####################################
    
    # This workflow will run CI on your codebase, label your PR, and comment on the result
    
    name: MYWORKFLOW
    
    on:
      pull_request: # the workflow will trigger on every pull request event
    
    jobs:
      build:
        runs-on: ubuntu-latest
    
        strategy:
          matrix:
            node-version: [12.x, 14.x] # matrix for building and testing your code across multiple node versions
    
        steps:
          - name: Checkout
            uses: actions/checkout@v2
          - name: Build node version ${{ matrix.node-version }}
            uses: actions/setup-node@v1
            with:
                node-version: ${{ matrix.node-version }}
          - run: npm install
          - run: npm run build --if-present
          - run: npm test
    
      label:
        runs-on: ubuntu-latest
    
        needs: build #this ensures that we only trigger the label job if ci is successful
    
        steps:
          - name: Checkout
            uses: actions/checkout@v2
          - uses: actions/github-script@v3
            with:
              github-token: ${{ secrets.GITHUB_TOKEN }}
              script: |
                github.issues.addLabels({
                  issue_number: context.issue.number,
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  labels: ['release']
                })
    
      comment:
        runs-on: ubuntu-latest
    
        needs: [build, label]
    
        steps:
          - name: Checkout
            uses: actions/checkout@v2
          - name: Comment on the result
            uses: actions/github-script@v3
            with:
              github-token: ${{ secrets.GITHUB_TOKEN }}
              script: |
                github.issues.createComment({
                  issue_number: context.issue.number,
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  body: `
                  Great job **@${context.payload.sender.login}**! Your CI passed, and the PR has been automatically labelled.
    
                  Once ready, we will merge this PR to trigger the next part of the automation :rocket:
                  `
                })
  • Update the name of your workflow

  • Within the comment job, you can edit the body of the comment as you see fit

  • Commit the changes to your default branch

  • Knowledge Check

    • How many jobs are there in the workflow?

      Answer The workflow contains three jobs:
      • a build-job,
      • a label-job,
      • a comment-job
    • What is the event that will trigger this workflow?

      Answer The workflow is triggered by any pull request events.
    • Does this workflow use a build matrix?

      Answer Yes, this workflow will build and test across multiple node versions.

🎉 Awesome, now our CI workflow should be complete!

Test the CI Workflow

  1. To test our CI workflow, we need to trigger it. And the event that triggers it is pull_request. So let's create a pull request to get this workflow running

  2. Go to index.js file and enter edit mode.

  3. Make some changes/add some text.

  4. Commit your changes to a new branch e.g. add-ci-workflow and click Commit changes

  5. In the pull request, leave the title and the body to default and click Create pull request

  6. In your PR, click on the Checks tab

    • You should now see your workflow kicking off, and executing all the steps defined in .github/workflows/ci.yml
  7. After the workflow has completed, check that the following is true in your PR;

    • A label release has been added
    • A comment is added to the PR with the text corresponding to what you defined in the comment job inside .github/workflows/ci.yml
  8. If your workflow fails, inspect the log output:

    • Which job failed?
    • Did you update your package.json file correctly?
    • Does the log indicate any syntax errors with your CI workflow file?

⚠️ Do not merge your pull request just yet! There's more to do.

Workflow 2: Steps to set up release and publish package workflow

Add a workflow that publishes an NPM package and creates a draft release

  1. We are going to be using the release-drafter Action.

    • Add a workflow file at this directory .github/workflows/release.yml:

      Click here to view file contents to copy:
      #####################################
      #      Automate your workflow       #
      #####################################
      
      # This workflow will create a NPM package and a new release
      
      name: Publish and release
      
      on:
        push:
          # branches to consider in the event; optional, defaults to all
          branches:
            - main
      
      jobs:
      
        update_release_draft:
          runs-on: ubuntu-latest
      
          steps:
            # Drafts your next Release notes as Pull Requests are merged into "master"
            - uses: release-drafter/release-drafter@v5
              with:
                config-name: release-drafter-config.yml
              env:
                GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      
        publish-gpr:
          runs-on: ubuntu-latest
      
          needs: update_release_draft
      
          steps:
            - uses: actions/checkout@v2
      
            - uses: actions/setup-node@v1
              with:
                node-version: 12
                registry-url: https://npm.pkg.github.com/
      
            - run: npm publish
              env:
                NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    • Notice how this workflow calls for a special config file called release-drafter-config.yml. This is a config file that allows you to add more customization. So let's go ahead and add a config file for this action at github/release-drafter-config.yml:

      Click here to view file contents to copy:
      name-template: 'v$RESOLVED_VERSION 🌈'
      tag-template: 'v$RESOLVED_VERSION'
      categories:
        - title: '🚀 You did it!'
          labels:
            - 'release'
      change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
      change-title-escapes: '\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks.
      version-resolver:
        major:
          labels:
            - 'major'
        minor:
          labels:
            - 'minor'
        patch:
          labels:
            - 'patch'
        default: patch
      template: |
        ## Changes
      
        $CHANGES
    • You can read more about the configuration options for this Action here.

    • This action will create a release with release notes when the pull request is merged into the main branch.

Watch your actions come to life!

  1. Merge the pull request

  2. Click on the Code tab and click on Packages on the right sidebar to find your package

  3. Click on Releases on the right sidebar to find your new draft Release

Additional Exercise

Customize your release-drafter Action such that it is able to categorize release notes based on labels that were added to pull requests. For example, if the label bugfix is added to a pull request, then when the pull request is merged, the Action would add the pull request to the release notes and show it as a Bugfix. Here's an example:

  • You can find out how to add more customizations from the configuration options for this Action here.

    Click here to see the example
    name-template: 'v$RESOLVED_VERSION 🌈'
    tag-template: 'v$RESOLVED_VERSION'
    categories:
      - title: '🚢 Features'
        labels:
          - 'feature'
          - 'enhancement'
      - title: '🐛 Bug Fixes'
        labels:
          - 'fix'
          - 'bugfix'
          - 'bug'
      - title: '🧰 Maintenance'
        label: 'chore'
    change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
    change-title-escapes: '\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks.
    version-resolver:
      major:
        labels:
          - 'major'
      minor:
        labels:
          - 'minor'
      patch:
        labels:
          - 'patch'
      default: patch
    template: |
      ## Changes
    
      $CHANGES

    The config file above allows you to add more labels like 'feature' and 'bug'.