/master-camel-connect

Workshop Master Project - FORK me to your account.

Primary LanguageJavaScript

Workshop Guide:

GitHub Actions is an advanced feature of GitHub that enables automation and CI/CD natively. This workshop aims to educate you on how to implement these use cases across your repositories on GitHub. We encourage you to complete Phase 2 in its entirety. Understanding actions concepts is one of the most important goals of this workshop and will enable you to implement actions that conform to modern best practices. Your moderator will likely be vastly out numbered during your workshop - therefore please rely heavily on the documentation provided and available on help.github.com. The final state of this workshop is available here for your convenience and reference. When you are complete, feel free to ask for feedback from your moderator and remember the best way to learn is to teach!

Phase 1: Repo Creation

The goal of Phase 1 is to create your own branch off the forked master-camel-connect repo where you can build out your own GitHub Actions. You will also be introduced to the GitHub Flow and Git if you haven't seen it in the past.

  1. Star this repo at the top of the page.
  2. Fork this repository to your user account.
  3. Using your terminal, command prompt, or the GitHub client.
  4. Clone your new repository to your local machine using git clone https://github.com/your_username/master-camel-connect.git - If clone is failing, check that you have replaced the variable in that url.
  5. Now that you have the repo locally, cd into the application.
  6. Run npm install in the root of your directory to install dependencies.
  7. Understand GitHub flow. This is how you will make contributions in practice.
  8. Checkout to a new feature branch. $: git checkout -b your-name-actions;
  9. Add your name and the date to the top of your README above the workshop directions.
  10. Use the following git commands:
  $: git add .;  
  $: git commit -m'initial repo push;  
  $: git push origin master;  
  this updates your remote repository on GitHub.

  1. Checkout to a new feature branch. $: git checkout -b your-name-actions;

  2. If npm or node have not been installed, install them.

  3. Create a Personal Access token in your user/settings/developersettings. The scope of this PAT must include write to Repo and don't forget to delete it after the workshop :). Token Creation

  4. You should now have:
    a) Your own version of the application in GitHub and on your local machine.
    b) Have your name and the date at the top of your README.
    c) Be working off your-name-actions branch of your repository.
    d) Be ready to create an action!

Phase 2: IMPORTANT Read the Docs

The goal of Phase 2 is to understand the major concepts that will be implemented throughout the workshop. Documentation should be read carefully and referred to often.

  1. Understanding git, the distributed version control system.
  2. Understanding Actions.
  3. Creating a workflow.
  4. Integrating a 3rd party service with the repository dispatch event.
  5. GitHub API - Creating an Issue.
  6. How to use Postman to send an API request. Postman

Phase 3: Implement your first CI Action

The goal of this phase is to implement your first GitHub Action. This Action will run CI - with your tests on push to your feature branch.

  1. Ensure your application runs locally when you run npm test in the root of your repository. Validate tests pass locally.
  2. Review your workflow.yml file named unit-test-ci.yml in .github/workflows.
  3. Set the workflow to run on:
  yaml
    on:
      pull_request:
        branches:
          - master
    push:
      branches:
        - <your-name-actions> (this is the branch you created)
  1. In your workflow file ./.github/workflows/unit-test-ci.yml , ensure that the action runs on - run: npm test. Workflow Definition
  2. Uncomment the workflow file. Follow GitHub Flow to push your uncommented workflow file to your remote repo.
  3. Pass/Fail your workflow by modifying the ./spec/unit-tests/factServiceSpec.js file.
  4. Review the Actions Tab for LIVE LOGS! Actions Tab
  5. Congratulations! Your Action just ran your tests when you pushed to your feature branch! Well done!

Phase 4: Implement your first automation Action

The goal of this phase is to implement an action that creates an issue when you send the 'repository_dispatch' event to it. In this case using Postman, in reality it would be a custom webhook from your 3rd party service.

  1. Validate that the .github directory exists in your root.
  2. Review the workflow file created in ./.github/workflows/update-issues.yml:
    • Understand the event ingest mechanism defined under on and which branches it is targeting. (no action required)
    • Understand how your API request is going to trigger this workflow by sending a custom event named repository_dispatch (no action required)
  3. An action that creates an issue in your repository when invoked has been created for you. The action is located in .github/actions. It is called updates-issues-action.
    • You can see how this action is invoked from within your update-issues.yml workflow line 14 under uses.
  4. Review the action.yml file in directory: .github/actions/updates-issues-action. This is a meta file that describes the update-issues-action.
  5. In action.yml, uncomment your action metadata. Helpful documentation here.
  6. Understand the runs meta tag operates like:
  runs:
    using: 'node12'
    main: './main/automation/update-issues.js'

main: should point to where you are building your actual automation logic from the update-issues-action directory. This will behave like a lambda or azure function.

  1. In your text editor, uncomment the automation logic found in update-issues-action/main/automation/update-issues.js for creating an issue using the GitHub Issue APIs. (sorry you will need to do this line by line to keep comments intact!)
  2. Ensure your workflow file at root/workflows/update-issues.yml runs on [repository_dispatch].
  3. Test your workflow using Postman or cURL, build your action using JS, review the Actions logs to debug. Actions Logs

Phase 5: Implement your first CD Action

This phase is a hands-off self driven phase. It requires you to build a workflow that deploys your application to your defined infrastructure using Actions.

  1. If you have gotten here, congratulations.
  2. Here is an example of a Node app that is deployed to Azure using an action for CD.
  3. Leverage GitHub Actions to push your application to GitHub Package Registry.
  4. Leverage another Action to pull your artifact from GPR and deploy to your Infrastructure.
  5. If you finish this step, congratulations you have completed the workshop. Please consider opening a Pull Request on this repo to enhance documentation for future attendees. You are free to exit the session or continue hacking on a personal project. Thank you!

This repository is a simple API written in Node Express and unit tested in Jasmine. Actions are written in vanilla JS.

Specs:

./specs/unit-tests/factServiceSpec.js Line 16 can be modified to ensure tests pass or fail. Simply change the "expected" value of the assertion.

Workflows:

.github/workflows

  • unit-test-ci:

    • Run unit tests on all services when push to Develop Branch or PR on Master.

  • update-issues:

    • Call update-issues-action on repository_dispatch.

Actions:

.github/actions

  • update-issues-action:
    • Creates an issue when the repository_dispatch event is triggered. The contents of that Issue are defined by an associated work item created in a Fictitious Azure Board instance.