Hello, DEV community! 😉 New day and new useful information about GitHub Actions. Earlier, we figured out how to build & deploy a static 11ty website to remote virtual server after pushing and, I hope, you've learned the principles I set out in that article.
Using ready-made GitHub Actions from Marketplace is good, but... what if they are not available or/and your configuration is too specific?
That's right! 👌 Let's write your own first action.
- The basis for the example
- GitHub action basics
- Publish action to GitHub Marketplace
- Questions for better understanding
- Exercises for independent execution
Let's take GitHub action, what I created for build Sapper-based website:
:octocat: GitHub Action for generating a static website with Sapper.
GitHub Action for Sapper
Use this action to build your static website with Sapper.
☝️ How to use?
To use it, create a
.github/workflows/sapper_build.yml file in your Sapper-based website repository as an action.
📌Tip: read this article to more understand GitHub Actons steps.
This action accepts a couple of optional inputs:
||Build mode to the Sapper|
||Arguments to pass to the Sapper invocation|
- name: Build uses: truewebartisans/actions-sapper@master with build_mode: "export" args: "--legacy --entry about"
👀 More complex examples
These are examples, which builds the website with this action, then deploys with another action.
💡 Deploy to GitHub Pages
- Deploy action: peaceiris/actions-gh-pages
name: Build Sapper and Deploy to GitHub Pages on: [push] jobs: build_deploy: runs-on: ubuntu-latest steps:…
Usually, the structure of a project for GitHub action, looks like this:
. ├── .gitignore ├── .github │ ├── gh-cover.png │ └── workflows │ └── test_deploy.yml ├── action.yml ├── Dockerfile ├── entrypoint.sh ├── LICENSE └── README.md
Now, let's take apart the most basic files. In the code samples below, I specifically separated sections and marked them to make it easier to read.
But, you may not do this in your actions... 😏
This is the settings file for the action.
# Action's main info name: "Sapper Action" description: "Build your Sapper-based static website" # Action's author name author: "Vic Shóstak" # Action's branding data for GitHub Marketplace # See docs:  branding: icon: "package" # icon name from Feather open source icons pack color: "blue" # Action's inputs (options) # See docs:  inputs: # First input (option) name # See docs:  build_mode: # Input's description description: "Build mode to the Sapper (could be `build` or `export`, by default `export`)" # Specify, if this input is required to define required: false # Input's default value default: "export" # Second input (option) name args: description: "Arguments to pass to the Sapper invocation (by default `--legacy`)" required: false default: "--legacy" # Configures the image (used for the Docker action) # See docs:  runs: # Use Docker to run the action using: "docker" # The Docker image to use as the container to run the action # or path to 'Dockerfile' with settings image: "Dockerfile"
Yeah, as you have already understood, this is a regular
Dockerfile with container settings (the same as you usually use in your projects):
# Select the Docker image FROM node:10-alpine # Copy `entrypoint.sh` file to container's root COPY entrypoint.sh / # Set permissions for `entrypoint.sh` file execution RUN chmod +x /entrypoint.sh # Define an entrypoint to be called after the container is created ENTRYPOINT ["/entrypoint.sh"]
☝️ Tip: please read The Best practices for writing Dockerfiles here.
The entrypoint, wich will be called after the container is created. In our case, it's just a simple
#!/bin/sh echo "Running \`npm install\`" npm install echo "Build Sapper" npx sapper $INPUT_BUILD_MODE $INPUT_ARGS
$INPUT_BUILD_MODE is equal to
actions.yml file and the same logic also applies to
inputs.args). In other words, all variables, that you would allow for definition to your users should be defined as
If some variable is specific, you can define it with a
boolean variable in
action.yml and then, check in
- Specify a new input for
# ... inputs: npm_install: description: 'If set to `true`, `npm install` will be run' required: false default: false # ...
☝️ Tip: it doesn't matter, what case the variable name is in
action.ymlfile, but there should be either only uppercase or only lowercase letters!
- And now, just add
#!/bin/sh if [ "$INPUT_NPM_INSTALL" = "true" ]; then echo "Running \`npm install\`" npm install fi # ...
.github/workflows/test_build.yml— test for your action (optional).
.github/gh-cover.png— cover image for preview, like this:
Documentation and usage examples in
README.md are the most important parts of your GitHub action. Because, your action (possibly) will be used by other developers! Always remember that, when you create a new action.
Here are some simple rules to help you write really good docs:
- Write a detailed start guide right at the beginning.
- Format all optional values (
inputs) in tabular format, following the string structure:
- Add more examples, especially, if your action can be built into a chain of actions or used only in combination with another GitHub action.
- Add beautiful and understandable image cover for preview of your GitHub repository. This is also important, because when people sharing link of your GitHub action, will see an attractive preview that can create a great conversion!
☝️ Tip: You can download a special template (with safe indents) to create a cover image for preview of your repository.
- (advanced) Add a demo repository with an example of how to apply your GitHub action, such as I did for action of this example:
Okay! 👍 We are now fully ready to publish your first action to the GitHub Actions Marketplace.
- Go to Releases page in your repository and draft new release.
Publish this Action to the GitHub Marketplace.
- GitHub will check all the files related to the action and will show warnings, if something doesn't comply with best practices or/and community agreements.
Security contact email.
- Specify tag version (use a Semantic versioning), title and description.
If you did everything right, then on the main page of your repository will be added a badge with an invitation to view this action on the GitHub Marketplace:
In fact, that's it! 😎 You have just created your first GitHub action, written excellent documentation for it and published it on the Marketplace.
🎉 Congratulations! We did it!
- In what case should you write the name of each
- Which collection of icons does GitHub Actions use for
- What are the best practices, when selecting a tag for a release version?
- How can you define environment variables in
input? Read this section in the GitHub Actions docs.
- Try to repeat everything you have seen in the article, but with your own action. Please, write about your results in the comments to this article!
- Change color and icon of your action at GitHub Marketplace.
- GitHub Actions promo website (link)
- GitHub repository settings (link)
- True web artisans
If you want more — write a comment below & follow me. Thx! 😘