GitHub action

Learn how to use the Stringtale GitHub Action in your workflow for text updates..

What does it do?

The Stringtale GitHub Action automatically creates Pull Requests in your GitHub repository with the latest text updates stored in Stringtale.

Why use it?

The GitHub action automates the process of implementing text changes that have made by you or your client. Your team will gets notified automatically of new Pull Requests, allowing you to see if there is an update without having to check manually.

With our GitHub action you still have full control if you want to run Stringtale on every push on every branch, or if you want to limit this to just release branches.

How do I use it?

There are two ways to trigger the GitHub action. You can either use the various triggers that GitHub has to offer (for example when pushing to a branch), or by letting Stringtale call a webhook whenever text updates are made. Both will then in turn create a pull request with the latest text changes.

Pushing to a branch

Below is an example of how to set up a GitHub action to run Stringtale on every push to any branch in your repository, including an example yaml file for the workflow.

Navigate to the Stringtale Dashboard and obtain yourself an API key.
Go to your GitHub repository => Settings => Environments.
Add the Token you obtained from the dashboard as STRINGTALE_API_KEY to the required environment(s) or create a new one.
Create a stringtale.yaml file in the .github/workflows folder in the root of your project. For example <PROJECT_DIRECTORY>/.github/workflows/stringtale.yaml.
Use the example YAML file from below and adjust to your project’s needs.
The next time this workflow gets triggered Stringtale will automatically create a Pull Request with any pending changes to the branch that triggered it.

Example yaml for GitHub actions

The example yaml file below will enable Stringtale to run on all branches on all pushes. If you prefer a different workflow, please refer to the GitHub Actions documentation.

name: Stringtale

on:
  push:
    branches:
      - '**' # Where ** Mean all branches, * only matches every branch that doesn't contain a '/'

jobs:
  build-web:
    runs-on: ubuntu-latest # Or i.e. ubuntu-20.04, no version requirement there
    environment: CHANGE-ME # Change this to your GitHub environment

    steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Run stringtale action
      uses: demonsters/stringtale-action@v0.3.2
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Automatically provided by GitHub
        # STRINGTALE_API_KEY is the token that the CI uses to access the Stringtale API
        STRINGTALE_API_KEY: ${{ secrets.STRINGTALE_API_KEY }}

Using the Stringtale GitHub webhooks

Alternatively to having GitHub trigger the workflow, you can also set up a webhook to trigger the GitHub action instead. This however has the limitation that it only works for the main branch. This is a limitation of GitHub Actions. So if you want to run Stringtale on other branches, you will need to use the GitHub action.

Follow the steps above to set up the GitHub action for pushes, but replace the section on: push: with on: repository_dispatch: as follows:
```
name: Stringtale

# Remove this section:
on:
  push:
    branches:
       - '**'

# Keep everything from jobs: onwards
```
```
name: Stringtale

# Replace with this section:
on:
   repository_dispatch:
     types: stringtale

# Keep everything from jobs: onwards
```
For more info about the repository dispatch event and it’s payload, refer to the GitHub documentation Create a repository dispatch event and the Webhook events and payloads documentation
To allow Stringtale to communicate with your GitHub repository, we need a Fine grained personal access token. You can set this up by following these steps:
1. Go to your GitHub profile settings.
2. In the menu on the left select the bottom most option Developer Settings
3. Open up the menu for Personal access tokens and then click on Fine grained tokens
4. Click on Generate new token
5. Give it a name and choose an expiration date
6. Under Repository access choose Only select repositories and select which repository/repositories the token should apply to.
7. Open up the newly appeared Repository permissions section and select the following permissions:
  - Actions: Read and Write
  - Metadata: Read-only
  - Contents: Read and Write
8. Click on Generate Token and copy the token, we’ll need it later at step 5.
Navigate to the Stringtale Dashboard.
Go to Projects.
Open the project (or click on Edit project settings) you wnat to enable webhooks for.
Scroll down to Webhooks and click on Add Webhook.
For type select ‘GitHub’, give it a name and for the URL enter https://api.github.com/repos/{owner}/{repository}/dispatches, replacing {owner} with the name of the owner of the repository (typically your organization) and {repository} with the name of the repository as they’d normally appear in the URL when you navigate to the repository on GitHub. For Token you enter the previously generated Fine grained access token.
From now on whenever somebody presses ‘Save changes’ in Stringtale, a webhook will automatically be fired to trigger the GitHub action.