-
Notifications
You must be signed in to change notification settings - Fork 11
CI and Automation guidelines
For most Kontent repositories, we highly recommend adding automation workflows. With some basic automation, we want to perform automatic checks, tests and builds. Moreover, when it makes sense, it's a good practice to automate deploying or publishing processes to the respective registry. With this initiative, we aim to reduce human errors and increase productivity. Whenever it's possible, we recommend using GitHub Actions instead of other automation providers - this will helps us with better maintenance. This page contains general info about GitHub Actions and their usage. Subpages focus on the specific stacks.
GitHub Actions are the feature of GitHub that consists of the API and an environment for running your tasks. You just need to create a YAML file at a specific location in the repository. The configuration .yml file contains all the specific information about the environment, such as trigger events, jobs, or strategies. Additionally, you can choose the environment where you want to run your tasks—it might be Linux (Ubuntu), Windows (Windows Server), or even macOS (Big Sur or Catalina).
Continuous integration is the automation of building and testing. This means that typically, with some code changes, the machine checks whether it’s possible to build the project and whether your tests are passing. Continuous delivery is a little bit broader. To sum it up, this automation process will deploy or publish your code to various environments. This might be a little bit abstract and connected with the nature of your project, but you can visualize it as publishing to package registries like NPM or Nuget—or deploying your site to a staging or production environment.
Each action is represented by a .yml
file located directly in the repository at the .github/workflows
location. To be able to run it, you need to allow the Actions feature in the repository’s Settings section.
It's common, the Action needs API keys or secrets to be able to release the version or perform some automation tasks. The practice is to use the Repository or Organization secrets.
If you are not familiar with the YAML
format, for the purposes of the GitHub Actions, you just need to know that key-value pairs are represented by key: value
. The quotes for string values are optional. Nesting of objects is done by indentation (typically two spaces), and items of the array are denoted by a dash.
key: value
nested_property: Nested value
my_array:
- First Item
- Second Item
- name - The name of the workflow.
- on - Is required, specifies events when you want to run your action.
- jobs - A job is a unit of work; jobs run in parallel by default. Each job runs in a runner environment specified by runs-on.
- jobs.<job_id>.runs-on - Is required, specifies the type of the machine to run the job.
- jobs.<job_id>.steps - A step is an individual task that can run commands in a job. A step can be either an action or a shell command. Each step in a job executes on the same runner, allowing the actions in that job to share data with each other (definition by GitHub).
- jobs.<job_id>.steps[*].uses - Selects an action to run as part of a step in your job. This is beneficial for reusing existing actions. You can check existing actions in the official actions repository or on the marketplace.
- jobs.<job_id>.runs-on - Provides a shell where you can run your commands.
Let’s write the action that runs the Python script every day. This action will run on Ubuntu, using code from our repository, and will run our main.py script on the environment with Python 3.8. The explanation of each line is described in the respective comment directly in the code.
- Create
main.py
in the root of your repository with contentprint("Hello, World!")
. - In the
.github/workflows
create theminimal-action.yml
file with the following content.
name: Hello World From Python # Represents the name of the whole action.
on: # Specifies the section where we describe our build triggers.
schedule: # Specifies the section where we describe the schedule of running the action.
- cron: '* 1 * * *' # The CRON expression describing when to run the action.
workflow_dispatch: # Adds the ability to run the action manually by button on the Actions tab.
jobs: # Specifies the section where we describe our jobs.
hello_world_job: # Specific job section.
name: A greeting job # The name of the job.
runs-on: ubuntu-latest # Describes the environment.
steps: # Specifies the section where we describe the job's steps.
- name: Checkout # The name of the step.
uses: actions/checkout@v2 # Using already existing action actions/checkout@v2. This action provides us with access to the code of the repository.
- name: Set up Python 3.8 # The name of the step.
uses: actions/setup-python@v1 # Using already existing action actions/setup-python@v1. This action sets up a Python environment for us.
with: # Configuration of the python action.
python-version: 3.8 # Specific python version.
- name: Run the script # The name of the step.
run: python main.py # Command for running our main.py.
It’s not possible to cover all capabilities and combinations for each stack here. Nevertheless, in the subpages, you can find some real-world examples—you can choose them for scaffolding your Action quickly for your specific stack and use case. They showcase configuration for various languages, platforms, and publishing to external package repositories. However, before you start with more advanced Actions, you'll need some more commands.
- on.release.types - Runs the action when a specific release event occurs.
- on.<push|pull_request>.<branches|tags> - Runs an action when push or pull request event occurs on a specific branch.
- jobs.<job_id>.strategy.matrix - Allows to set different job configurations.
- env - Context for specified environment variables.
- env.NODE_AUTH_TOKEN - Specifies the location of stored NPM_TOKEN. It’s a good practice to store secrets and keys to Encrypted Secrets storage of the repository.
- jobs.<job_id>.if - The job will run if the condition is met.
- GitHub Actions documentation
- An article about GitHub Actions containing Kontent specific examples: With GitHub Actions, you don’t have to do boring tasks manually ever again