Commit Teller

Table of Contents

• Goals
  • Introduction
  • Project
• Usage
  • GitHub Actions
  • Java JAR
• CLI Customizations
• File templates
• Contribution
  • Fork
  • How to build the project?
  • Code formatter
  • Commit messages
• Contributors

Goals

Introduction

Commit Teller is a fun project created for the GitHub + DEV 2023 Hackathon.

The hackathon is based around GitHub Actions, GitHub’s CI/CD component and the Codespaces. In the announcement organizers listed multiple categories, and this one fits in the Wacky Wildcards (Build a random app that doesn’t fit into one of the categories above.).

The announcement can be found here.

Project

What is the purpose of this project? What can we do with it?

With the dawn of the AI techs, this little tool will help you make your pull requests have some sort of backstory, based on the commits they are containing.

Most pieces of software are not really having documentations, and this tool is not a replacement of documentations, but a fun way to tell the story of the project/software/application via the pull request history and its commits.

With the attached GitHub action you are able to hook it into your pull request lifecycles and at merge time, the action will kick in and will tell you the story of the pull request. You name the mood of the story, it can be funny, kind, strict, documentation like, anything you choose.

Usage

GitHub Actions

name: Create story about Pull Request
on:
  pull_request:
    types:
      - closed # (1)

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 # (2)
    steps:
      - uses: actions/checkout@v3
      - uses: rodnansol/[email protected] # (3)
        name: Create story
        with:
          version: early-access # (4)
          arguments: create-story -pr ${ISSUE_NUMBER} --owner ${GITHUB_REPOSITORY%/*} --repository ${GITHUB_REPOSITORY#*/} --file-extension ADOC -saf=true # (5)
        env: # (6)
          ISSUE_NUMBER: ${{ github.event.number }} # (7)
          COMMIT_TELLER_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # (8)
          COMMIT_TELLER_OPENAI_API_KEY: ${{ secrets.OPENAI_KEY }} # (9)
      - name: Commit story changes # (10)
        shell: bash
        env:
          ISSUE_NUMBER: ${{ github.event.number }}
        run: |
          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

1. Specify the event when the action must be executed, for example when the pull request gets closed (The close event can mean closed manually on the website, or by merging the pull request)

2. Specify if the action steps must be executed if the code changes are getting merged and not just the pull request is being closed by hand.

3. Add the rodnansol/[email protected] to your action. Check the latest version before doing so here.

4. Optional - Specify the version of the CLI tool you want to use.

5. Specify the command with the flags. Check the available flags here.

6. Check the customization options here.

7. GitHub action is providing the contextual data which contains the number of the issue/pull request. In the pull request context the issue word is interchangeable.

8. Specify the GitHub token. GitHub Action will always provide one when running the action, but it must be injected into the action.

9. Specify the OpenAI’s API key. Get one after registration here: https://platform.openai.com/account/api-keys

10. Optional - If you want to collect the stories inside your repository do not forget to commit them. Check the available templates here.

More information about the action can be found here.

Java JAR

Download the latest uber-jar/fatjar and run it with Java 17(!) from here: https://github.com/rodnansol/commit-teller/releases

The tool requires the following environment variables that can be put next to the jar file into an .env file

.env

COMMIT_TELLER_GITHUB_TOKEN=<github-token> #(1)
COMMIT_TELLER_OPENAI_API_KEY=<openai-token> #(2)

1. Create a GitHub token here: https://github.com/settings/tokens

2. Create an OpenAI token here: https://platform.openai.com/account/api-keys

For more customization option check the following section.

$ java -jar commit-teller-cli.jar create-story
Missing required options: '--owner=<owner>', '--repository=<repository>', '-pr=<pullRequestNumber>'
Usage: <main class> create-story [-ican] [-pac] [-saf] [-fe=<fileExtension>]
                                 -o=<owner> -pr=<pullRequestNumber>
                                 -r=<repository>
Creates a story for a given issue/pull request and posts it as a comment.

      -fe, --file-extension=<fileExtension>
                        Extension of the file.
                        Supported formats: MD for Markdown, ADOC for AsciiDoc.
                        Default is Markdown

      -ican, --include-commit-author-names
                        If the commit author names should be included in the
                          prompt for the language processor based text
                          generation.

  -o, --owner=<owner>   Owner GitHub identifier.
                        It can be a standalone user or an organization.

      -pac              Post as comment the result.
      -pr=<pullRequestNumber>
                        Number of the pull request that should be analyzed and
                          commented.
  -r, --repository=<repository>
                        Name of the repository owned by the owner option.
      -saf              Save as file. The

CLI Customizations

The CLI tool can be customized via environment variables.

Check the available ones:

Customization options via a .env file next to the jar file

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 #(6)
  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:'
COMMIT_TELLER_STORY_CHARACTERISTICS='documentation like, funny' #(7)

1. Create a GitHub token here: https://github.com/settings/tokens

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.

📎	The default values are used in the above code section. If you want to override them please use the mentioned keys. These can be overwritten in the GitHub action as well. Check the documentations here.

File templates

The created stories can be saved into a file in two different formats:

• Markdown - Default

• AsciiDoc

The file name format is the following: #<pull-request-number> - <pull-request-title>.<extension>

For example, if you have a pull request with the number of 35 and title "feat(core): GitHub and OpenAI integration" the file name will be: #1 - feat(core): GitHub and OpenAI integration.md

The templates are simple:

Markdown

## <Pull request title>
<Generated story>

AsciiDoc

== <Pull request title>
<Generated story>

📎	At the moment they are not editable/customizable.

Contribution

Fork

Please fork the project if you would like to contribute.

How to build the project?

The project requires at least GraalVM 22.3 / Java 17, if SDKMan is installed on your machine sdk e command could be used in the terminal to set up the required Java version.

• To build the project just run: mvn package -Puber-jar

Code formatter

The project contains a .editorconfig file, and it should be utilized as well.

During build time Checkstyle checks the conventions.

Commit messages

The commit messages are based on the conventional-commits, please apply those rules.

Learn more here.

Contributors

Check the list of contributors here.