Integrate GitHub Actions with BrowserStack

A step-by-step guide to help you integrate GitHub Actions with the BrowserStack device cloud for running all your Selenium tests on BrowserStack Automate.

You can find the BrowserStack GitHub Actions in the GitHub Marketplace. The two Actions are used to set up the required environment variables in the runner environment and set up BrowserStack Local tunnel connection which will be used to route all browser traffic from BrowserStack’s device cloud to the runner environment which hosts your web application.

In this guide, we will cover the following sections:

• Integrate GitHub Actions with BrowserStack
  • Set up GitHub secrets in your repository
  • Set up a GitHub workflow to run BrowserStack tests
  • Use BrowserStack GitHub Actions in your workflow
  • Sample test script
  • Sample GitHub workflow showing a BrowserStack test
  • Additional References

Set up GitHub secrets in your repository

You need to have username and access-key from BrowserStack to be able to run tests on the BrowserStack infrastructure. This section shows how to set them as Secrets in your GitHub repository. You can sign-up for free trial if you do not have an existing account.

If you want to test your open source project on BrowserStack, then sign-up here for lifetime free access to all our products.

As the picture above suggests, go to Settings in your repository and there you will find the Secrets option in the left-hand pane. Go to Secrets and add new secrets as shown below:

Add YOUR_USERNAME as the BROWSERSTACK_USERNAME secret and similarly, add YOUR_ACCESS_KEY as the BROWSERSTACK_ACCESS_KEY secret. After these two steps, the secrets page should contain entries like this:

Set up a GitHub workflow to run BrowserStack tests

You must do the following to run BrowserStack tests from GitHub Actions (see the sample GitHub workflow):

1. Create the workflow file(s) <filename>.yml in the .github/workflows directory in your repository. (Read more about creating GitHub Workflow files)
2. The starting of the workflow specifies on what events the workflow must run. We recommend you to run on both push and pull_request so that you have a 1:1 build mapping against every commit
3. You can run on any GitHub Actions runner e.g. ubuntu-latest (You can also host your own runners)
4. In the initial workflow steps, you must build your web application and start the web server on the runner
5. Thereafter, invoke setup-env BrowserStack Action to set up environment variables in the runner
6. Invoke setup-local BrowserStack Action to set up a tunnel connection between the GitHub Actions runner environment and the BrowserStack device cloud so that the application server on the runner environment can be accessed by the browsers in BrowserStack’s device cloud
7. Run the test scripts from the workflow. (You can visit the Sample Test section to see how you can use the environment variables in your test script to set BrowserStack capabilities)
8. Invoke setup-local BrowserStack Action again to terminate the tunnel connection

You can see the sample GitHub workflow to run a BrowserStack test. The next section explains the purpose and usage of the BrowserStack GitHub Actions in your workflow.

Use BrowserStack GitHub Actions in your workflow

You can find the BrowserStack GitHub Actions in the GitHub Marketplace. The following two Actions are used to set up the required environment variables in the runner environment and set up BrowserStack Local tunnel connection which will be used to route all browser traffic from BrowserStack’s device cloud to the runner environment which hosts your web application.

      - name: 'BrowserStack Env Setup'
        uses: 'browserstack/github-actions/setup-env@master'
        with:
          username:  ${{ secrets.BROWSERSTACK_USERNAME }}
          access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
          build-name: 'BUILD_INFO'
          project-name: 'REPO_NAME'

      - name: 'BrowserStack Env Setup'
        uses: 'browserstack/github-actions/setup-env@master'
        with:
          username:  ${{ secrets.BROWSERSTACK_USERNAME }}
          access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}