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 bringing text changes made through Stringtale back into your repository. When edits are available, it can create a pull request so the changes enter your normal Git review workflow without requiring a manual stringtale pull.

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?

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 an API key.
Go to your GitHub repository → Settings → Environments.
Add the API key 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 ** means 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 API key that the CI uses to access the Stringtale API
          STRINGTALE_API_KEY: ${{ secrets.STRINGTALE_API_KEY }}

Using the Stringtale GitHub webhooks

Stringtale can automatically trigger the GitHub Action, using webhooks, whenever changes get saved. This does have the limitation that it only works for the main branch. This is a limitation of GitHub Actions. If you want to run Stringtale on other branches, use the push trigger instead.

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 its 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. In the Permissions section, add the following 3 permissions:
  - Actions: Read and Write (required to trigger the Action using the webhook)
  - Contents: Read and Write (required to update the code)
  - Metadata: Read-only (gets automatically added when you add any of the other ones)
8. Click on Generate Token and copy the token, you’ll need it when configuring the webhook below.
Navigate to the Stringtale Dashboard.
Go to Projects.
Open the project (or click on Edit project settings) you want 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 enter the fine-grained access token generated earlier.
From now on whenever somebody presses ‘Save changes’ in Stringtale, a webhook will automatically be fired to trigger the GitHub Action.