Building Blocks - Creating your own GitHub Actions in JavaScript

This was presented at GitHub Universe 2019's workshop day.

Transcript

1. November 2019 Building Blocks: Creating your Own GitHub Actions in JavaScript
2. Building Blocks: Creating your Own GitHub Actions in JavaScript @IAmHughes Thomas Hughes Partner Engineering @imjohnbo John Bohannon Partner Engineering
3. Building Blocks: Creating your Own GitHub Actions in JavaScript • Learning objectives • Introducing GitHub Actions • Container Actions vs. JavaScript Actions • Hands-on: Building a GitHub action in JavaScript • Break out session • Best practices • Q&A Agenda
4. Building Blocks: Creating your Own GitHub Actions in JavaScript • Obtain a general understanding of GitHub Actions • Build a JavaScript action that wraps a GitHub API endpoint • Learn about tooling available to create a JavaScript action • Learn best practices for creating and maintaining GitHub Actions • Learn how to publish an action to the GitHub Marketplace Learning objectives
5. Building Blocks: Creating your Own GitHub Actions in JavaScript • Custom workflows triggered on any GitHub event • World class CI/CD primitives • Matrix builds • Live, streaming logs • Built in secret store • Familiar YAML syntax • Linux, macOS, and Windows hosted runners • Self hosted runners in beta • GitHub Enterprise Server support coming soon Introducing GitHub Actions Events Workflows Actions Trigger Use
6. Building Blocks: Creating your Own GitHub Actions in JavaScript Workflows Workflows let you codify useful processes to your liking. They belong in YAML files in a special directory in your repository, .github/ workflows. Examples • Organizational: Welcoming new contributors • Legal: Ensuring license uniformity • Application: Testing across multiple operating systems Events Workflows Actions Trigger Use
7. Building Blocks: Creating your Own GitHub Actions in JavaScript Events Workflows are triggered on events: • push, pull_request, public, etc. • schedule • repository_dispatch (outside systems) Events Workflows Actions Trigger Use
8. Building Blocks: Creating your Own GitHub Actions in JavaScript Starting with a repository with existing tests, we will add a workflow and see GitHub Actions do its magic. First workflow
9. Building Blocks: Creating your Own GitHub Actions in JavaScript Actions Actions are reusable units of code made available to your workflows. GitHub runs them in a Node.js runtime or in Docker containers and are referenced from workflows as uses: owner/repo@ref. Examples • stale • javascript-action • Lots more on GitHub Marketplace Events Workflows Actions Trigger Use
10. Building Blocks: Creating your Own GitHub Actions in JavaScript Actions: which kind? TLDR; Write in the language and environment that makes sense for you. JavaScript actions are faster, runtime is more versatile, and offer a better user experience. Events Workflows Actions Trigger Use JavaScript action Container action Virtual environment Linux, MacOS, Windows Linux Language Anything that compiles to JavaScript Any Speed ++ + User experience ++ +
11. Building Blocks: Creating your Own GitHub Actions in JavaScript Starting with another stub repository, we'll add an action.yml and the script defined in its entrypoint. First action
12. Building Blocks: Creating your Own GitHub Actions in JavaScript • We'll create a basic action wrapping the Create Release API endpoint • Code is available in the README.md for reference • Template repository: https://git.io/JeaAX (universeworkshops/create-release) Let's build our own GitHub action!
13. Building Blocks: Creating your Own GitHub Actions in JavaScript • Edit the release body • Upload release assets to the existing release • Modify the README.md file to include the latest release version • Add additional outputs • For example, the tag that was used to create the release How would you improve this action?
14. Building Blocks: Creating your Own GitHub Actions in JavaScript Breakout session!
15. Building Blocks: Creating your Own GitHub Actions in JavaScript • Bite-sized, chainable, primitive actions versus monolithic • Versioning your action • Well written documentation (README, CONTRIBUTING, LICENSE) • Test coverage • action.yml metadata • Publishing to the GitHub Marketplace Best practices
16. Building Blocks: Creating your Own GitHub Actions in JavaScript • Chainable actions are easier to debug than monolithic actions • Bite-sized primitives that serve one function allow for better composition • Workflow steps are more clear in what they accomplish • Workflows are more modular, think LEGO bricks • Monolithic actions require much more logic handling and complexity Chainable actions versus monolithic actions
17. Building Blocks: Creating your Own GitHub Actions in JavaScript Monolithic action example
18. Building Blocks: Creating your Own GitHub Actions in JavaScript Chainable action example
19. Building Blocks: Creating your Own GitHub Actions in JavaScript • Tags allow for logical releases of your action • Allow users to reference a specific version (instead of master) • Ensures they upgrade to the latest version of your action when they are ready Versioning your action
20. Building Blocks: Creating your Own GitHub Actions in JavaScript • Ensure your documentation is targeted to your audience • Write for an external audience, eliminate internal jargon, be explicit • README.md - Details specifics about your action • CONTRIBUTING.md - Allows users a clear path to submit feedback and make OSS contributions • LICENSE - Appropriate for your open source repository Documentation
21. Building Blocks: Creating your Own GitHub Actions in JavaScript • Renders on the repository and GitHub Marketplace listing • Should contain an example workflow to get started • A list of inputs and outputs • Any prerequisites or assumptions to use the action README.md
22. Building Blocks: Creating your Own GitHub Actions in JavaScript • Explain the versioning and release process • Describe how to submit feature requests and bugs • Discuss specifics around OSS contributions, coding standards, etc • State how to run your tests and expected test coverage for contributions CONTRIBUTING.md
23. Building Blocks: Creating your Own GitHub Actions in JavaScript • Verify functionality of your action • A few simple tests go a long way to verify "Happy Paths" • You can display a build badge in your README.md to show the status of your latest release Test Coverage
24. Building Blocks: Creating your Own GitHub Actions in JavaScript • Defines the author and description of your action • Should be located in the root of your repository • Defines your inputs and outputs • Consider adding a branding section for your listing on the marketplace action.yml metadata
25. Building Blocks: Creating your Own GitHub Actions in JavaScript • The best way to increase discoverability of your action • Automatically renders your README.md in the listing • Any new releases can be made available on the marketplace immediately Publishing to GitHub Marketplace
26. Building Blocks: Creating your Own GitHub Actions in JavaScript Q&A