Attach your E2E/API Tests to your Github actions jobs pipeline.
Creating a health CD/CI pipeline for microservices architecture seems easy at first, but with the number of options and integrations available in the market, its time consuming to find a good solution that fits all.
GHA can be costly when you don't have GitHub enterprise and understand that.
By the way, GHA == Github Actions
I witnessed companies using Github actions jobs that are triggered by other software which manages multiple pipeline workflows to save some money.
Other companies didn't use GitHub actions at all due to costs but they have complicated software and pipelines that consumes time from multiple developers and some additional hidden costs that are not taken into consideration when choosing a tool/service.
Yes, my friend, quality of life is usually not considered when it comes to tooling that will manage your pipeline.
With that in mind, I'm here to make some free advertising for GitHub action and show you how to simplify your CD/CI pipeline process by including your E2E/API tests that probably reside on a separate repository. You're welcome.
Knowledge Dependency
Before we jump to the solution, you must understand how GHA works. I select some documents and videos so you can understand how simple the solution is.
1. GHA Basics
First, familiarize yourself with how to structure your YML, where to place it on your repository, invoke actions from the marketplace, trigger your jobs, repository/organization secrets, and how to use them.
The official documentation is a good place to start but there are also good tutorials and videos about it:
- Tutorial: https://docs.github.com/en/actions/learn-github-actions
- Oficial documentation: https://docs.github.com/en/actions/quickstart
- Video overview: https://www.youtube.com/watch?v=cP0I9w2coGU
- GHA Secrets: https://octopus.com/blog/githubactions-secrets
- GHA Events: https://michaelcurrin.github.io/dev-cheatsheets/cheatsheets/ci-cd/github-actions/triggers.html
2. GHA Workflows(Job dependency) and GHA environments
To use the full potential of your workflows, you need to get familiarised with how to create a chain of jobs and which environment your tests will run.
Using GHA Environments will make your life easier when managing secret/ environment keys. It will help you communicate their context so other developers can use them in the right environment.
Take a look at those documents and videos to learn a bit more about it:
- Official documentation for Environments: https://docs.github.com/en/actions/deployment/targeting-different-environments
- Offical documentation for Workflows: https://docs.github.com/en/actions/using-workflows/about-workflows
- Video tutorial for workflows: https://www.youtube.com/watch?v=JNqButrPjcE
- Video tutorial for CD/CI process: https://www.youtube.com/watch?v=36hY0-O4STg
3. GHA Custom Actions (Composite Action)
You could achieve the same result without creating a custom action for your E2E/API test repository, but then you would have to copy/paste the same steps across the repositories that will trigger your E2E.
If you are testing microservice architecture, I highly recommend creating a custom action for your tests as it will save you some headaches that only copying the same code over and over will give you.
Take a look at those documents to understand a bit more:
- General info about Custom Actions from the Official Documentation: https://docs.github.com/en/actions/creating-actions/about-custom-actions
- Overview of Composite Action from the Official Documentation: https://docs.github.com/en/actions/creating-actions/creating-a-composite-action
- Overall tutorial for GHA Custom Actions: https://www.thisdot.co/blog/creating-custom-github-actions (this particular one you need to go all the way to publish to the marketplace)
Creating a custom action for your E2E test
Now that you are almost an expert on GHA, lets create a foobar action that will run your test.
On the repository that resides your E2E/API/<Test phase that contemplates the exercise of components in multiples repositories> tests, create a file called action.yml
with something like this:
The example above is a slight variation of the sample code that can be found on the official documentation and I will break down some valuable information.
Let's break down some important information:
- This example is using an action from the marketplace to configure the AWS credentials. You can use actions from the GHA marketplace or from your own organization.
- You can see that I'm defining the output for the action. The output name isn't relevant (it can be anything), but the "value" option is the part that will tell the consuming pipeline if the test passed or not. You need to use the ID of the step that executes the test and get the
stdout
from it. - You cannot use secrets from your own repository when creating an action, as GitHub says that it can lead to misuse of the action.
- Unlike the normal workflows, when you want to execute something in the shell, you need to define it explicitly, or it will complain that the shell option is missing.
In the example above, I'm setting two inputs (composite doesn't allow passing secrets) that will be used to configure the AWS credentials.
It may seem insecure but since you are using it within the same organization AND setting the actions configuration to enforces the usage only by other repositories within your organization, lower its risk.
As you can see, this custom action contains a straightforward setup to the environment (nodejs), install all dependencies, and execute the test.
You can also test your action on in the same repository by creating a foobar action workflow to try it out:
Adding your action to the pipeline
Now its time to glue everything together and hope for the best :)
As you can check in the code above, there is a job to "deploy" something, and there is our code to call the test from the other repository.
It consist in 2 steps:
- The first one clones the test repo on a specific branch using a github token to authenticate and clone the repository
- The second step calls the action itself with the params that we covered before.
If this step fails, your pipeline will fail. UHUHU!
See how simple it is? But I couldn't let you go trough the trouble to figure out everything by yourself.
Also, be aware that each JOB on GHA have specific billing, so I would advice you to only run your E2E when something is pushed to main or a similar strategy.