Implementation

Step 1: GitHub Workflow Setup

The implementation of ontobot-change-agent is generally within a github workflow of an ontology repository.

Choosing of a GitHub workflow depends on the type of resource one is trying to edit:
- OBO Resource: The template for the workflow is provided by this YAML file.
Just uncomment the code and change the following:

Update the resource (*.obo file) path in the ontology’s repository.
run: | echo "resource=src/ontology/YOUR-RESOURCE-FILENAME.obo" >> $GITHUB_ENV
- OWL Resource: The template for the workflow is provided by this YAML file.
Just uncomment the code and change the following:

Update the resource (*.owl file) path in the ontology’s repository.
run: | echo "resource=src/ontology/YOUR-RESOURCE-FILENAME.owl" >> $GITHUB_ENV
Note

For OWL resources we use kgcl-java as the underlying package to carry out the change. There are 2 options for implementation here:
- Use existing an instance of ROBOT` (via ODK) with kgcl-java as a plugin.
- Use a standalone JAR file which combines both ROBOT and kgcl-java.
We highly recommend using the standard option (#1). For this you should just uncomment this code block and delete this code block
Warning

This should be done once only. `ontobot-change-agent <https://github.com/apps/ontobot-change-agent>`_ already exists as an app on GitHub. This step is solely for the purpose of documentation.

Create a GitHub App at the Organization level such that it has access to specific repositories of concern. - Go to Settings -> Developer settings -> GitHub Apps -> New GitHub App. - Fill in the necessary details and create the GitHub App:
Github App Name:

Homepage URL:

Expire user authorization tokens: Unchecked

Webhook:

Active: Unchecked

Permissions:

Repository level permissions:

Contents: Read & Write

Metadata (mandatory): Read-only

Pull requests: Read & write

Organization level permissions:

Adminstration: Read-only

Account permissions: None

Where can this GitHub App be installed?:

Only on this account (If you want to restrict the app to a single organization)

Any account (If you want to allow the app to be installed on any organization)
- Generate a private key and download it (.pem file).
- Note the App ID.
- Follow instructions to install the GitHub App on the repository.
  
  Go to Settings -> GitHub Apps -> Install App.
  
  Select the organization and repository.
  
  Click on Install.

Follow instructions in actions/create-github-app-token@v1 to create a GitHub App token.

Add the following code block to the workflow file:

- name: Create GitHub App token
  uses: actions/create-github-app-token@v1
  with:
    app_id: ${{ vars.APP_ID }}
    private_key: ${{ secrets.PRIVATE_KEY }}

Add the following to the repository:
- APP_ID: This will an environment variable.
- PRIVATE_KEY: This will be a secret. This is the whole content of the .pem file.
Finally, add the token generated from above to the pull request generation workflow block:

- name: Create Pull Request
  uses: peter-evans/create-pull-request@v4
  if: ${{ env.PR_TITLE }}
  with:
    branch-suffix: short-commit-hash
    labels: Automated
    author: ${{ env.ISSUE_CREATOR }} <${{ env.ISSUE_CREATOR }}@users.noreply.github.com>
    committer: ${{ env.ISSUE_CREATOR }} <${{ env.ISSUE_CREATOR }}@users.noreply.github.com>
    body: ${{ env.PR_BODY }}
    title: ${{ env.PR_TITLE }}
    base: ${{ github.head_ref }}
    branch: ${{ env.branch-name }}
    token: ${{ steps.app-token.outputs.token }}

Step 2: Take it for a spin!

Create a new issue

Create a new issue in the repository as one would usually do and give it a clear subject.

#. In the body, ontobot-change-agent will be looking for the phrase - “Hey ontobot!, apply:”(the “!” is optional).#. In the next line start writing change language commands as bullets (using “-” or “*”).

The list of commands can be found here (“Command” section).

An example of an issue to trigger a pull request:
Hey ontobot!, apply:

- create exact synonym 'ABCD1' for PREFIX:12345
- create broad synonym 'ABCD2' for PREFIX:12345
There are no limits on the number of bullets one can pass.

Pull request

Once the issue is created, it triggers the GitHub workflow mentioned above and creates a corresponding pull request which should reflect the expected change in the ontology resource based on the commands listed in the issue. The title for the pull request generated corresponds to the issue that triggered its generation. If the issue is edited, the same pull request is updated.

Trigger QC Checks

To ensure that an ontobot generated pull request triggers the GitHub workflow for running Quality Control (QC) checks on the ontology repository, you must follow these steps:

Navigate to the Settings tab of your repository.
Under the Secrets and variables section, select Actions.
Click on New repository secret.
Name the new secret GH_TOKEN.
Set the value to your personal access token.

Note

Personal access tokens are used to grant limited access to your GitHub account with an expiry time. For detailed instructions on creating a personal access token, visit the GitHub documentation here.
In your GitHub Actions workflow file, locate the line containing token: ${{ secrets.GH_TOKEN }}.
Ensure this line is active (not commented out) to use the token during the workflow execution.