How to Create and Publish a GitHub Action in Typescript - ULTIMATE 2023 GUIDE

GitHub Actions are a powerful tool to automate your workflow. They can be used to run tests, deploy your code, publish a package, and much more. The cool thing is, there's a GitHub Actions Marketplace where you can find a lot of actions created by... the community. But what if you can't find the action you need? You can create your own and publish it there! In this tutorial we're going to see in detail how to: Create a GitHub Action in Typescript Expand our Action to support custom inputs Integrate with GitHub's API to add labels to Pull Requests Unit testing our action Debugging in Visual Studio Code Publishing our action to the GitHub Marketplace Using our action in another repository Some final touches to make our project more robust How to use this tutorial This post will be much longer than usual, you can skip through the chapters from the table of contents below, but I'd recommend you to follow each step and not skip anything. One more great piece of advice is to create a new repository and follow along with the steps. This way you'll have a working action at the end of the post and you'll be able to play with it and experiment, rather than just reading a long tutorial and forgetting about 90% of it. The full code of this tutorial is available on GitHub on , so you can always refer to it if you get stuck. this repo Last, but not least, I also recorded a video version of this tutorial, so if you prefer to watch it instead of reading, you can do so here. https://youtu.be/N26xgQ7kLKo?embedable=true Building an MVP Let's begin with an MVP (Minimum Viable Product) of our GitHub Action. We'll start simple with an action having only the required parts to understand the basics, then we'll add more features to it. Action Definition The definition is stored in the file, put directly in the root of the repository. action.yml name: 'My Custom Action' description: 'Say Hello' author: 'Leonardo Montini' runs: using: 'node16' main: 'dist/index.js' The most minimal action definition is composed of a name and a object to define how the action is executed and what file to run. and are optional. runs description author In case your action has some inputs, they will be defined in the file as well, in the object. action.yml inputs inputs: name: description: 'The name of the person to greet' required: true default: 'World' When publishing the action to the store, you might want to customize the appearance of the action in the marketplace. This can be done by adding a object to the file. branding action.yml branding: icon: 'activity' color: 'green' Anyway, for this MVP the first snippet will be enough. Project setup Let's create an empty node project with . npm init -y You can now open and add the build script. package.json { "scripts": { "build": "tsc" } } Since we want to use Typescript, we'll need to install it as a dev dependency. npm install -D typescript Then we'll create a by running and we'll edit it to match our needs. tsconfig.json npx tsc --init { "compilerOptions": { "target": "ES2019", "module": "commonjs", "outDir": "lib", "esModuleInterop": true, "forceConsistentCasingInFileNames": true, "strict": true, "skipLibCheck": true } } Project code We can now create the file and start writing our action. src/index.ts console.log('Hello World!'); We're building an MVP, right? So let's keep it simple for now and focus on all the required steps. We'll have time to expand it later. Building the action We can now build the action by running which will execute the command as we defined in the file. npm run build tsc package.json This will create a folder containing the compiled code. dist dist └── index.js In case you see generated in the root of the project or inside , you might want to add make sure the option to the file is properly set to . index.js src/ outDir tsconfig.json dist Creating the repository In case you haven't done it yet, it's time to create a git repository as we'll need to push our code to GitHub soon. git init Don't forget to add a file to the project to avoid committing files that shouldn't be tracked by git, for example, the folder. .gitignore node_modules A quick way to do it is by running which will create a file with the most common entries for a node project. npx gitignore node .gitignore : in this particular case we want to push the folder to GitHub, so we'll need to remove the entry from the file. Note dist dist .gitignore git add . git commit -m "Initial commit" git remote add origin git push -u origin main Running the Action We're all set! It's time to run our action. Creating a workflow On GitHub, Actions are executed by workflows. A workflow is defined in a file stored in the folder of the repository so let's create it. .yml .github/workflows mkdir -p .github/workflows touch .github/workflows/greet.yml The name of the file doesn't matter, but it's good practice to give it a meaningful name. What matters is the content of the file, which defines the workflow. To keep it simple, here are the minimal instructions you need. name: Say Hello on: workflow_dispatch: jobs: run-my-action: name: Checks if this action works runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: ./ In this case, the action will checkout the current repository and then run the action we just created. We put as the action path because we want to run the action from the current repository, but we could also use a different repository. ./ How does GitHub know what action to run? It's defined in the file we created earlier. action.yml One more line worth mentioning is which tells GitHub to run the workflow when we manually trigger it from the Actions tab. I recorded a dedicated video about running , if you want to learn more about it. on: workflow_dispatch: GitHub Actions manually Running the workflow We can now push our code to GitHub and see the action in action! git add . git commit -m "Add workflow" git push Once the code is pushed, we can go to the Actions tab and trigger the workflow manually. The workflow will start running and we'll see the logs of the action in the console. Congratulations! You just created and ran your first GitHub Action! Running the action locally In case you want to run the action locally, without having to commit/push every time, you can use the tool. act npm install -g act Then you can run the action by executing in the root of the repository. act act You can find more in my video about . running GitHub Actions locally Reading inputs Let's make our action a bit more interesting by reading an input from the workflow. Add inputs to the action definition As usual, the first step is to define the input in the file. action.yml inputs: name: description: 'The name of the person to greet' required: true default: 'World' Read the input in the action code Then we can read the input in the action code. const name = getInput('name'); console.log(`Hello ${name}!`); But where does the function come from? It's defined in the package, which we need to install. getInput @actions/core npm install @actions/core And then add the import on top of the file. index.ts import { getInput } from '@actions/core'; Update the workflow Finally, we need to update the workflow to pass the input to the action. - uses: ./ with: name: 'Leonardo' By adding the section, we're passing the input to the action. with name Run the hello action We can now run the action again and see the input being passed to the action. If it doesn't work ( ) that's ok, we'll fix it in the next section when we inluce in the workflow. Error: Cannot find module '@actions/core' @vercel/ncc Use case: Adding a label to new Pull Requests We learned the basics, we have our MVP ready to be expanded so let's do it! We'll create a new action that will automatically run every time a new Pull Request is created and it will add a label to it. needs-review Update the action code In order to add a label to a Pull Request, we need to use the . We can use the Octokit client to make the API calls. Luckily for us there's an official package we can use. GitHub REST API npm install @actions/github Then we can import the client and use it to add the label to the Pull Request. Here's the full code. Octokit import { getInput, setFailed } from '@actions/core'; import { context, getOctokit } from '@actions/github'; async function run() { const token = getInput('gh-token'); const label = getInput('label'); const octokit = getOctokit(token); const pullRequest = context.payload.pull_request; try { if (!pullRequest) { throw new Error('This action can only be run on Pull Requests'); } await octokit.rest.issues.addLabels({ owner: context.repo.owner, repo: context.repo.repo, issue_number: pullRequest.number, labels: [label], }); } catch (error) { setFailed((error as Error)?.message ?? 'Unknown error'); } } run(); What happened here? We read the and inputs from the workflow. The token is a that we need to create and pass to the action. More on that later. The label is the name of the label we want to add to the Pull Request. gh-token label personal access token We create an instance of the client using the token. Octokit We get the Pull Request number from the object. This object is only available when the action is triggered by a Pull Request event. context.payload.pull_request We call the method to add the label to the Pull Request. octokit.rest.issues.addLabels In case something fails, we catch the error and we set the workflow as failed with the function, also coming from the package. setFailed @actions/core Update the action definition We also need to update the action definition to add the new inputs. inputs: gh-token: description: 'The GitHub token for authentication.' required: true label: description: 'The label to be applied to the pull request.' required: true Update the workflow Finally, we need to update the workflow to run when PRs are opened or reopened: on: pull_request: types: [opened, reopened] ...and to pass the new inputs to the action. - uses: ./ with: gh-token: ${{ secrets.GITHUB_TOKEN }} label: 'needs-review' We're passing the secret to the action. It usually does not require you any extra action, as GitHub automatically creates it for you. GITHUB_TOKEN In case you get an error that says "Resource not accessible by integration", you need to make sure your token on that repository has write access. You can do that by going to the Settings tab > Actions > General and scroll down to the "Workflow permissions" section. Setting it to "Read and write permissions" will be enough. Run the action We can now run the action again and see the label is added to the Pull Request. However, let's not forget to run first, then we can commit and push the changes. The reason is that we told GitHub that the action is located in the folder, so we need to make sure that folder is up to date. npm run build dist npm run build git add . git commit -m "Add label to new Pull Requests" git push Cool! We can now create a new branch, change a file and open a Pull Request. We'll see the action running and adding the label to the Pull Request, aaaand... Error: Cannot find module '@actions/core' What happened here? If you look at your file in , you'll see that the package is not there. That's because we didn't tell TypeScript to include it in the build. dist/index.js @actions/core A good way to include packages and condense everything in one file is with the tool . Let's install it. @vercel/ncc npm install @vercel/ncc Then we can update our script in to use it. build package.json "build": "tsc && ncc build lib/index.js" We also need to change in to . outDir tsconfig.json lib "outDir": "lib" You might also want to double-check that is in your file but is not. This is our desired behavior as will only have our code in javascript, but will have the whole action. lib .gitignore dist lib dist Run the action (2.0) We can now run again, then commit and push the changes. npm run build Create a new branch, change a file and open a Pull Request. This time, you'll see the action running and adding the label to the Pull Request. Testing the action You wouldn't push code into production without testing it, right? So let's write some tests for our action. Setup We'll use to write our tests. It works out of the box with Javascript but needs a little bit of configuration to work with TypeScript. Jest npm install -D jest ts-jest @types/jest We also need to create a new config file for jest, in the root of our project, called . jest.config.json { "preset": "ts-jest", "testEnvironment": "node", "collectCoverage": true, "coverageReporters": ["lcov", "text-summary"], "collectCoverageFrom": ["src/**/*.ts"], "coveragePathIgnorePatterns": ["/node_modules/", "/__tests__/"], "testPathIgnorePatterns": ["/node_modules/"] } We're telling jest to use the preset, to run the tests in node, to collect coverage and to ignore some files. ts-jest Additional changes Without any extra configuration, the build will also include test files, which we don't want. On tsconfig.json, we can add a new property. exclude "exclude": ["node_modules", "**/*.test.ts"] And also, if we'd run tests now, everything would run twice. Why? Because at the end of our file, we're calling the function. This is the entry point of our action, and we want to run it when the action is triggered. However, we don't want it to run by default when we import the file in our tests. index.ts run A possible solution is to wrap the call to in an statement that checks if a jest environment variable is set. run if if (!process.env.JEST_WORKER_ID) { run(); } Writing the tests We can now create a new file called in the folder. This is where we'll write our tests. index.test.ts src/__tests__ I have to say I'm a bit lazy so I asked GitHub Copilot to write the tests for me (guess what, I also made a video on this topic). At first, they were not passing, but after a few tweaks, I got them to pass. Here's an extract, but you can find the full file in the repository. import { run } from '../index'; import { getInput, setFailed } from '@actions/core'; import { context, getOctokit } from '@actions/github'; // Mock getInput and setFailed functions jest.mock('@actions/core', () => ({ getInput: jest.fn(), setFailed: jest.fn(), })); // Mock context and getOctokit functions jest.mock('@actions/github', () => ({ context: { payload: { pull_request: { number: 1, }, }, repo: { owner: 'owner', repo: 'repo', }, }, getOctokit: jest.fn(), })); describe('run', () => { beforeEach(() => { // Clear all mock function calls and reset mock implementation jest.clearAllMocks(); }); it('should add label to the pull request', async () => { // Mock the return values for getInput (getInput as jest.Mock).mockReturnValueOnce('gh-token-value'); (getInput as jest.Mock).mockReturnValueOnce('label-value'); (context as any).payload.pull_request = { number: 1, }; // Mock the Octokit instance and the addLabels method const mockAddLabels = jest.fn(); const mockOctokit = { rest: { issues: { addLabels: mockAddLabels, }, }, }; (getOctokit as jest.Mock).mockReturnValueOnce(mockOctokit); // Run the function await run(); // Assertions expect(getInput).toHaveBeenCalledWith('gh-token'); expect(getInput).toHaveBeenCalledWith('label'); expect(getOctokit).toHaveBeenCalledWith('gh-token-value'); expect(mockAddLabels).toHaveBeenCalledWith({ owner: 'owner', repo: 'repo', issue_number: 1, labels: ['label-value'], }); expect(setFailed).not.toHaveBeenCalled(); }); }); Running the tests Now it's finally time to get rid of that script in . Just replace it with: "test": "echo \"Error: no test specified\" && exit 1" package.json "test": "jest" This will run jest with the configuration we just created. If you want to run the tests in watch mode, you can use . jest --watch We can now run to run the tests. You should see something like this: npm test Our action works as intended and we have some tests to prove it! Debugging the action Our favourite tool is flooding the code with console.log, but we all know there's a better way to debug code. Let's see how we can debug our action with Visual Studio Code. Setup To get started, we need one more package in our dev dependencies: . This will allow us to run our action directly from the source code, without having to build it first. ts-node npm install -D ts-node With vscode, the launch configuration is stored in a file called . We can create it by clicking on the debug icon in the sidebar and then on the gear icon, or manually by creating a file with this content: launch.json .vscode/launch.json { "version": "0.2.0", "configurations": [ { "name": "ts-node", "type": "node", "request": "launch", "args": ["./src/index.ts"], "runtimeArgs": ["-r", "ts-node/register"], "cwd": "${workspaceRoot}", "internalConsoleOptions": "openOnSessionStart" } ] } Debugging You can now put a breakpoint in your code and click on the play button in the debug sidebar. This will start the debugger and run your action. You can also use the key to start the debugger. F5 In this specific example, there isn't too much to debug, but if you're working on a more complex action, this can be a lifesaver. Inputs Ah, I almost forgot, what if your action has some inputs? How can you debug it? You can store them directly in your launch configuration as environment variables with the following rules, the will get picked up by : getInput prefix the name of the input with INPUT_ name the input in uppercase In our example it would be something like this: { "version": "0.2.0", "configurations": [ { "name": "ts-node", "type": "node", "request": "launch", "args": ["./src/index.ts"], "runtimeArgs": ["-r", "ts-node/register"], "cwd": "${workspaceRoot}", "internalConsoleOptions": "openOnSessionStart", "env": { "INPUT_GH-TOKEN": "secret-token-123456", "INPUT_LABEL": "needs-review" } } ] } If you now hit to start the debugger, you'll see that the environment variables are available in your action and are properly read by . F5 getInput Publishing the action The paragraph you've all been waiting for. I'm sure you also skipped the previous one about debugging to jump straight to this one. Branding Hold on for a second, if you remember we mentioned the section in the file. Let's see what it's all about. branding action.yml branding: icon: 'activity' color: 'green' This will add a nice icon and a color to your action in the GitHub Marketplace. You can find the list of available icons . here Publishing Ok, here we are! How do we publish our action? Just look at your GitHub repo. If you've properly set up an file, you should see a banner at the top of the page like this one: action.yml Going live on the GitHub Marketplace Click on and you will get to a page where you can set up all the required/missing information, for example, a well-written and informative file. Draft a release README.md You can decide if you only want to make the action available to everyone, or you also want it to be published and discoverable in the GitHub Marketplace. You can also select a primary and a secondary category from the list of available ones. The next step will be creating a tag and an official release for your action. Almost there... click the green button and you're done! Publish release Congratulations, you've just published your first GitHub Action! Using your action Now that you've published your action, everyone can use it in their workflows! Just create a new file in your repo, for example and add the following content: .github/workflows/label.yml name: Label PR on: pull_request: types: [opened, reopened] jobs: label: runs-on: ubuntu-latest steps: - uses: actions/checkout@main - uses: Balastrong/gh-aciton-test@latest with: gh-token: ${{ secrets.GITHUB_TOKEN }} label: needs-review To specify the version, you can either use (with being the tagged version on the repo, like ) or . owner/repo@{version} {version} v1.0.0 owner/repo@branch Final touches The action is complete, it's live in the store and it works on all GitHub repositories, but unless it's 100% complete and you won't ever update it again, you still have some room for improvements for a better developer experience (DX is quite trending these days). Keeping dist up to date One thing which will annoy you in this workflow is pushing new code and forgetting to also update the content. dist I mean, all you have to do is just make sure to run before pushing, but if something relies on "just remember to do it"... well... good luck! npm run build A simple way to solve this is to use a git hook. You can use the hook to run a script at each commit in your repository. This will work for you, but what if you're working with other people? Ah, just kindly tell them to install the hook as well... did I already say good luck? pre-commit 🐶 A Dog? Yes, specifically a Husky! is a tool which allows you to easily add git hooks to your project. It's very easy to set up and it will make sure that everyone who clones your repo will have the hooks installed as well, as they are part of the project and get installed with the dependencies, right after running . No need to rely on people remembering to install them! Husky npm install Let's follow the and install it: official docs npx husky-init && npm install You will now find a folder in your project, with a file in it. Open it and replace the content with this: .husky pre-commit npm run build Now make sure to run once to update the hook. This will make sure that every time you commit, the folder will be updated. npm install dist Formatting & Linting Since we already set up our hook, we can also add some formatting and linting to it. pre-commit This will make sure that the code is always properly formatted and that there are no linting errors. Let's install and : Prettier ESLint npm install -D prettier eslint lint-staged We will also need to install some plugins for ESLint: npm install -D @typescript-eslint/eslint-plugin@latest eslint-plugin-jest@latest We can now configure eslint and prettier. Create a file in the root of your project and add the following content: .eslintrc { "plugins": ["jest", "@typescript-eslint"], "parser": "@typescript-eslint/parser", "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"], "env": { "node": true, "jest/globals": true }, "ignorePatterns": ["*.test.ts"] } Let's also add a file: .prettierrc { "trailingComma": "es5", "printWidth": 120, "tabWidth": 2 } Last touch, we want to run these two only on the staged files, which means one more config file for lint-staged. Create a file and add the following content: .lintstagedrc { "./src/**/*.{js,ts}": ["prettier --write", "eslint --max-warnings 0"] } Now we can update our hook to run lint-staged as well: pre-commit npx husky add .husky/pre-commit "npx lint-staged" One more and we're done! npm install Closing If you followed all steps, you now have a pretty solid GitHub Action, published in the GitHub Marketplace, which is automatically built and linted on each commit. Ready to make a great Open Source project! If you want to see the final result, you can check out the while writing this article. You can also use it as a reference if you missed some steps. GitHub Action I created Want to see me following along the steps in this article? Check out the video here: https://youtu.be/N26xgQ7kLKo?embedable=true What else to say? I hope you enjoyed this article and that you learned something new. If you have any questions, feel free to add a comment below or reach out to me on . Twitter This was much longer than usual, I had a lot of fun writing it and I learned a lot myself in the process. Would you like more long articles like this one? Let me know! See you next time! Also published . here