diff --git a/.github/steps/1-step.md b/.github/steps/1-step.md index 518b06c..204e367 100644 --- a/.github/steps/1-step.md +++ b/.github/steps/1-step.md @@ -1,8 +1,14 @@ -## Step 1: Initializing the Dad Jokes GitHub Action +## Step 1: Setting up the project -Imagine you have a repetitive task that you want to automate. You've searched through the [**GitHub Marketplace**](https://github.com/marketplace?type=actions) to see if there are any existing actions that suit your needs, but found nothing - because your task is very specific: **generating DAD JOKES**! 🎭 +Imagine you’ve got a repetitive task you’d love to automate. You've searched through the [**GitHub Marketplace**](https://github.com/marketplace?type=actions) for existing actions that might help, you come up empty-handed… -Since no pre-built action exists for your quirky automation needs, it's time to roll up your sleeves and create your own +Maybe that’s because your task is a bit _too_ unique 😆 + +**GENERATING DAD JOKES**! 🎭 + +dadjoke-mona + +Since no pre-built action exists for your quirky automation needs, it's time to roll up your sleeves and create your own! ### ⌨️ Activity: Set up your development environment diff --git a/.github/steps/2-step.md b/.github/steps/2-step.md index 912172c..b66a16b 100644 --- a/.github/steps/2-step.md +++ b/.github/steps/2-step.md @@ -1,14 +1,21 @@ ## Step 2: Create Source Files & Run Locally -### 📖 Theory +Nice! Now that we have the project initialized and dependencies installed, it's time to create the source files for your Dad Jokes GitHub Action. + +### 📖 Theory: The GitHub Actions Toolkit + +The `@actions/core` library is the main library from the [GitHub Actions Toolkit](https://github.com/actions/toolkit), a collection of packages for building JavaScript GitHub Actions. It provides essential methods to interact with the GitHub Actions runtime environment, accept action inputs, and produce outputs for other workflow steps. + +> [!TIP] +> The [GitHub Actions Toolkit](https://github.com/actions/toolkit) includes other useful libraries like `@actions/github` for interacting with the GitHub API and `@actions/artifact` for uploading and downloading artifacts. +> +> Visit the [actions/toolkit](https://github.com/actions/toolkit) repository for more. -Author the action’s core logic and verify it runs locally before bundling. ### ⌨️ Activity: Implement the Dad Jokes Action Now that your project is initialized and dependencies are installed, it's time to create the source files for your Dad Jokes GitHub Action. - 1. Create `src/` directory to hold your GitHub Action JavaScript files: ```sh @@ -38,20 +45,26 @@ Now that your project is initialized and dependencies are installed, it's time t module.exports = getJoke; ``` + The `getJoke` function makes an HTTP GET request to the `icanhazdadjoke.com` API and returns a random dad joke. + + We export the `getJoke` function so it can be used in other files. + 1. Create `src/main.js` that will be the main entry point for your action: - ```js - const getJoke = require("./joke"); - const core = require("@actions/core"); + ```js + const getJoke = require("./joke"); + const core = require("@actions/core"); - async function run() { - const joke = await getJoke(); - console.log(joke); - core.setOutput("joke-output", joke); - } + async function run() { + const joke = await getJoke(); + console.log(joke); + core.setOutput("joke", joke); + } - run(); - ``` + run(); + ``` + + We call the `getJoke` function and call the `core.setOutput()` method to set the `joke` output of your GitHub Action. 1. Run the action locally to verify it works: @@ -59,7 +72,7 @@ Now that your project is initialized and dependencies are installed, it's time t node src/main.js ``` - + 1. Commit and push: @@ -68,43 +81,3 @@ Now that your project is initialized and dependencies are installed, it's time t git commit -m "Add Dad Joke action source files" git push ``` - -### 🛠 Activity (Optional): Debug your action - ->[!NOTE] -> This activity is optional and not required to complete the exercise. -> -> Learning how to debug your action code can be very helpful! - -
-Show steps
- -1. Install dev dependency: - - ```sh - npm install -D @github/local-action - ``` - -1. Create `.vscode/launch.json`: - - ```json - { - "version": "0.2.0", - "configurations": [ - { - "name": "Debug Action", - "type": "node", - "request": "launch", - "runtimeExecutable": "npx", - "cwd": "${workspaceRoot}", - "args": ["@github/local-action", ".", "src/main.js"], - "console": "integratedTerminal", - "skipFiles": ["/**", "node_modules/**"] - } - ] - } - ``` - -1. Set breakpoints in `src/main.js` and start the "Debug Action" configuration. - -
diff --git a/.github/steps/3-step.md b/.github/steps/3-step.md index 1f07648..89918a9 100644 --- a/.github/steps/3-step.md +++ b/.github/steps/3-step.md @@ -1,25 +1,37 @@ ## Step 3: Bundle the Action -### 📖 Theory: Bundling the action +Good job! :tada: +Now that you've created the source files for your Dad Jokes GitHub Action and tested it locally, it's time to bundle the action so it can be used in GitHub workflows. + +### 📖 Theory: Bundling Your Action + +When someone uses your action in their workflow, GitHub downloads and executes it as a complete package of code. This means you must include any package dependencies required to run the JavaScript code, such as the `@actions/core` and `request-promise` packages your action uses. + +Rather than committing your `node_modules` directory (which causes problems with repository size and performance), you can use bundling tools like `@vercel/ncc` to combine your code and dependencies into a single `dist/index.js` file for distribution. ### ⌨️ Activity: Build Setup & Bundle 1. Add a build script to `package.json` (inside the existing scripts block or create one): - ```json - "scripts": { - "build": "ncc build src/main.js -o dist" - } - - ``` + ```json + "scripts": { + "build": "ncc build src/main.js -o dist" + } + ``` 1. Run the build command. This should create a `dist/` directory with a bundled `index.js` file: - ```sh - npm run build - ``` + ```sh + npm run build + ``` + +1. (optional) Run the bundled action to verify it works: + + ```sh + node dist/index.js + ``` 1. Commit and push the changes to the `main` branch: diff --git a/.github/steps/4-step.md b/.github/steps/4-step.md index 5f5920e..d740e05 100644 --- a/.github/steps/4-step.md +++ b/.github/steps/4-step.md @@ -1,26 +1,61 @@ ## Step 4: Add Action Metadata -### 📖 Theory +Great work! :tada: You've successfully bundled your Dad Jokes GitHub Action into a single file. -Define the action’s interface (name, description, outputs, runtime, main entry) via `action.yml` pointing to the bundled file. +Now it's time to create the **action metadata file** - this special file tells GitHub exactly how to use your action when someone includes it in their workflow! + +### 📖 Theory: Action Metadata + +Every GitHub Action requires a metadata file that defines how the action should be executed and what parameters it accepts. + +#### Metadata File Requirements + +The metadata file has specific requirements: + +- **Filename**: Must be `action.yml` +- **Required for**: All actions types - JavaScript, Docker container, and composite actions +- **Format**: Written in YAML syntax + +#### Core Metadata Parameters + +| Parameter | Description | Required | +| ----------------- | -------------------------------------------------------------- | :------: | +| **`name`** | The name of your action. | ✅ | +| **`description`** | A short description of what your action does. | ✅ | +| **`author`** | The name of the action's author. | ❌ | +| **`inputs`** | Data that the action expects to receive. | ❌ | +| **`outputs`** | Data that other actions can use after this action runs. | ❌ | +| **`runs`** | Tells GitHub how to execute your action. | ✅ | +| **`branding`** | Optional color and icon for your action in GitHub Marketplace. | ❌ | + +#### JavaScript Action `runs` Configuration + +For JavaScript actions, the `runs` section needs: + +- **`using`**: Which Node.js version to use +- **`main`**: The main JavaScript file to run + +> [!TIP] +> For complete details on all available metadata parameters, optional fields, and advanced configurations, see the official [GitHub Actions metadata syntax documentation](https://docs.github.com/en/actions/reference/workflows-and-actions/metadata-syntax). + +--- ### ⌨️ Activity: Create Metadata File 1. Create `action.yml` at the repository root (same level as `package.json`). - ```yaml - name: "Joke Action" - description: "Fetches a random joke and exposes it as an output" - - outputs: - joke: - description: "The fetched joke text" + ```yaml + name: "Joke Action" + description: "Fetches a random joke and exposes it as an output" - runs: - using: node24 - main: dist/index.js - ``` + outputs: + joke: + description: "The fetched joke text" + runs: + using: node24 + main: dist/index.js + ``` 1. Commit and push: diff --git a/.github/steps/5-step.md b/.github/steps/5-step.md index 9f56e25..56163a4 100644 --- a/.github/steps/5-step.md +++ b/.github/steps/5-step.md @@ -1,11 +1,13 @@ ## Step 5: Create Workflow & Consume Output -### 📖 Theory +Well done! :clap: You've created the Dad Jokes GitHub Action and defined its metadata. -Use a workflow triggered by `issue_comment` to run the local action and then post the retrieved joke as a comment. +Your action should be ready to use in any GitHub repository now! ### ⌨️ Activity: Author Workflow +Let's see your Dad Jokes action in action by creating a GitHub Actions workflow that uses it! + 1. Create a new GitHub Actions workflow file with the following name ```txt @@ -17,10 +19,10 @@ Use a workflow triggered by `issue_comment` to run the local action and then pos ```yaml name: Joke Action on: - issue_comment: - types: [created] + issue_comment: + types: [created] - permissions: + permissions: issues: write contents: read @@ -40,6 +42,12 @@ Use a workflow triggered by `issue_comment` to run the local action and then pos body: {% raw %}${{ steps.get-joke.outputs.joke }}{% endraw %} ``` - The workflow will run on every issue comment created event. If the comment starts with `/joke`, it will execute the Dad Jokes action and post the joke as a comment in the same issue. + This workflow triggers when someone comments `/joke` on an issue and responds with a joke! + +1. Commit and push the workflow file to the `main` branch: -1. Commit and push the workflow file to the `main`: + ```sh + git add .github/workflows/joke-action.yml + git commit -m "Add workflow to test joke action" + git push + ``` diff --git a/.github/steps/6-step.md b/.github/steps/6-step.md index e786dbd..631542f 100644 --- a/.github/steps/6-step.md +++ b/.github/steps/6-step.md @@ -1,9 +1,30 @@ ## Step 6: Trigger & Validate +Awesome! :rocket: You've created the Dad Jokes GitHub Action, defined its metadata, and authored a workflow to use it. +The only thing left to do is test it out! -### ⌨️ Activity: Try out your action! +### ⌨️ Activity: Try out your action -1. Create a comment in this issue (or create a new one) with the text `/joke` -1. Monitor the `actions` tab for the "Joke Action" workflow run to complete. -1. After it completes you should see a new comment posted by the bot with the dad joke! +1. Create a comment in this issue (or create a new one) with the text `/joke` + +1. Monitor the **Actions** tab for the "Joke Action" workflow run to complete: + - Click on the **Actions** tab in your repository + - Look for a new workflow run titled "Joke Action" + - The run should show a green checkmark when completed successfully + +1. Return to the issue and you should see a new comment posted by `github-actions[bot]` containing a random dad joke! + +1. Mona will post the review of the exercise once the workflow completes **successfully**! + +
+ Having trouble? 🤷
+ + If the workflow doesn't trigger or fails: + - Make sure your comment starts exactly with `/joke` + - Check the Actions tab for error messages + - Verify that your `dist/index.js` file exists and was committed + - If you did any updates to your source code, ensure you re-bundled with `npm run build` and pushed the changes + - Ensure your `action.yml` file is correctly formatted + +
diff --git a/.github/steps/x-review.md b/.github/steps/x-review.md index 58521c1..427aa01 100644 --- a/.github/steps/x-review.md +++ b/.github/steps/x-review.md @@ -1,34 +1,23 @@ - +## Review -## Finish +_Congratulations, you've completed this exercise and learned how to write JavaScript GitHub Actions!_ -celebrate +celebrate -### Congratulations, you've completed this course! +Here's a recap of your accomplishments: -In this course, you've learned a lot about developing custom actions using JavaScript and Actions Toolkit. - -## Publishing your actions - -Publishing your actions is a great way to help others in your team and across the GitHub community. Although actions do not need to be published to be consumed, by adding them to the marketplace you make them easier to find. - -Some notable actions you will find on the marketplace are: - -- [Actions for Discord](https://github.com/marketplace/actions/actions-for-discord) -- [GitHub Action for Slack](https://github.com/marketplace/actions/github-action-for-slack) -- [Jekyll action](https://github.com/marketplace/actions/jekyll-action) -- [Run Jest](https://github.com/marketplace/actions/run-jest) - -And that just scratches the surface of the 1600+ and counting actions you will find on the marketplace - -Follow [this guide](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/publishing-actions-in-github-marketplace#publishing-an-action) to learn how to publish your actions to the GitHub Marketplace +- **Initialized a Node.js project** with proper dependencies and excluded `node_modules` with a `.gitignore` configuration +- **Created JavaScript source files** implementing a Dad Jokes action and leveraged the `@actions/core` library to handle action outputs +- **Bundled your action** into a single distributable `dist/index.js` file +- **Created action metadata** (`action.yml`) defining name, description, outputs, and execution parameters +- **Authored a GitHub Actions workflow** that uses your custom action +- **Tested your action** by triggering it with issue comments and validating the output ### What's next? -- [Take another GitHub Skills course](https://github.com/skills). -- We'd love to hear what you thought of this course in our [discussion board](https://github.com/orgs/skills/discussions/categories/write-javascript-actions). -- [Read the GitHub Getting Started docs](https://docs.github.com/en/get-started). -- To find projects to contribute to, check out [GitHub Explore](https://github.com/explore). +- Check out the other [GitHub Skills exercises](https://learn.github.com/skills). +- Try using your Dad Jokes action in your other repositories to add some humor to your workflows! + +- **Create your next action** using GitHub's template repositories with best practices like tests and linting already built-in: + - [actions/javascript-action](https://github.com/actions/javascript-action) template repository + - [actions/typescript-action](https://github.com/actions/typescript-action) template repository \ No newline at end of file diff --git a/README.md b/README.md index 2b296fe..35c4ecd 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,10 @@ _Write your own GitHub JavaScript Action and automate customized tasks unique to ## Welcome - **Who is this for**: Developers, GitHub users, users new to Git, students, managers, and for teams. -- **What you'll learn**: How to consume actions within a workflow file, create custom JavaScript based actions and publish your newly created action to the marketplace. -- **What you'll build**: A custom JavaScript-based GitHub Action that can be published to the marketplace. +- **What you'll learn**: How to create custom JavaScript-based GitHub Actions, bundle them for distribution, and use them in workflows. +- **What you'll build**: A Dad Jokes GitHub Action that fetches random jokes and responds to issue comments. - **Prerequisites**: + - You should be familiar with GitHub and GitHub Actions. We recommend taking the [Hello GitHub Actions](https://github.com/skills-dev/hello-github-actions) exercise first. - **How long**: This exercise takes about 1 hour to complete. @@ -15,11 +16,11 @@ _Write your own GitHub JavaScript Action and automate customized tasks unique to In this exercise, you will: 1. Initialize a JavaScript project -2. Configure an action -3. Create a metadata file -4. Create JavaScript files -5. Add actions to workflow file -6. Trigger action +2. Create JavaScript source files for a Dad Jokes action +3. Bundle your action into a distributable file +4. Create action metadata with `action.yml` +5. Author a workflow that uses your custom action +6. Test your action by triggering it with issue comments ### How to start this exercise