Commit Teller - How to use it?
Tags: githubhack23, githubactions, quarks, programming
Published: 2023-05-15 19:18:17

## "Well... We are waiting"

The tool is almost ready, it is time to show of what it can do.

Let's wire it into one of our repositories, start coding and let's open a pull request. When everything is ready, merge your results and let the GitHub action run :fire:

How does our pull request look before the tool is executed?

![Before Story](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/65t5yxkvawfeqsnps68m.png)

Let's merge it! :fire:


![Merge time](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/63kilccqyd7qrsgbbfay.png)


Let's check the GitHub Action itself:

![GitHub Action](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3yjw8251b4ew01lm5ipl.png)

And now, the result itself:

![Comment Result](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/z8favs53k15uzjtss3um.png)


## How to wire it into my repository?

Let's look at how it could be wired into your repository.

The setup is easy, because it is also "just" a GitHub Action, and if you have already setup one you will know what it looks like.

After you created your repository clone it (or you can do it online too) and create a folder named `.github` into the directory. Inside that directory create another one called `workflows` and in that create a `create-pull-request-story.yaml` file.

Open the **yaml** file and use the following as a template:

```yaml
name: Create story about Pull Request
on:
  pull_request:
    types:
      - closed

jobs:
  create-story-for-pull-request:
    runs-on: ubuntu-latest
    name: Create story for pull request at merge
    if: github.event.pull_request.merged == true
    steps:
      - uses: actions/checkout@v3
      - uses: rodnansol/commit-teller-action@v0.1.0
        name: Create story
        env:
          ISSUE_NUMBER: ${{ github.event.number }}
          COMMIT_TELLER_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          COMMIT_TELLER_OPENAI_API_KEY: ${{ secrets.OPENAI_KEY }}
        with:
          version: early-access
          arguments: create-story -pr ${ISSUE_NUMBER}
           --owner ${GITHUB_REPOSITORY%/*}
           --repository ${GITHUB_REPOSITORY#*/}
           -saf=true --file-extension ADOC
      - name: Commit story changes
        shell: bash
        env:
          ISSUE_NUMBER: ${{ github.event.number }}
        run: |
          mkdir -p docs
          mv *.adoc docs
          git add *.adoc
          git config --global user.email "${{ secrets.COMMITTER_EMAIL }}"
          git config --global user.name "${{ secrets.COMMITTER_NAME }}"
          git commit -m "Creating story about pull request #${ISSUE_NUMBER}"
          git push origin main
```

Configure the action to run when a pull request is closed, it starts on the second line:
```yaml
on:
  pull_request:
    types:
      - closed
```

With that `if` you can specify when to really run the GitHub action, as pull request can be done without merging the branch into the specified target, but if you want to run the action only the code is merged specify the following (as seen before):
```yaml
if: github.event.pull_request.merged == true
```

Configure the action with any available environment variables:

```dotenv
COMMIT_TELLER_GITHUB_TOKEN=<github-token> #1
COMMIT_TELLER_OPENAI_API_KEY=<openai-token> #2

COMMIT_TELLER_OPENAI_MODEL=text-davinci-003 #3
COMMIT_TELLER_OPENAI_TEMPERATURE=0.3 #4
COMMIT_TELLER_OPENAI_MAX_TOKEN=512 #5

COMMIT_TELLER_STORY_TEMPLATE='Write me a story about the following commits. \n
  The story can be only 512 characters long. \n
  The story should be based on the commit messages, and it should have the following characteristics:' #6
COMMIT_TELLER_STORY_CHARACTERISTICS='documentation like, funny' #7
```

1 - Create a GitHub token here, for GitHub actions it is optional, because the action is always having a token.
2 - Create an OpenAI token here: https://platform.openai.com/account/api-keys
3 - OpenAI’s models: https://platform.openai.com/docs/models/model-endpoint-compatibility
4 - Temperature value. More about it here: https://platform.openai.com/docs/api-reference/completions/create#completions/create-temperature
5 - Number of the maximum tokens for the completion response.
6 - The message to be passed to the language processor. It will include the commit messages as a list.
7 - Define the characteristics of the story.

For the official documentation please check the following website: https://rodnansol.github.io/commit-teller/latest/index.html

## Commit stories to the repository
By default a comment will be made to the associated pull request, but if you want to collect the stories at one place you generate the result to a file and commit to the repository with the final step. :fire: