Commit Teller - How to use it?

"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 🔥

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

Let's merge it! 🔥

Let's check the GitHub Action itself:

And now, the result itself:

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:

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:

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):

if: github.event.pull_request.merged == true

Configure the action with any available environment variables:

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. 🔥