Checking edhil against a Forgejo server

No automated test of edhil talks to a real Forgejo server; they use a fake one that behaves as the servers that were studied. This page is a short procedure to check edhil by hand against a real server, for example after a new Forgejo release or before you rely on it for a project. It takes a few minutes and a repository that you can write to. Use a repository for the check, not one that holds real work: the check creates issues.

The check was made against a Forgejo 17 server with a token that had the scopes read:organization, write:issue and write:repository. What differs between the forges is described on its own page.

Prepare the repository

  1. Create a repository, or use one for tests, and note its name as owner/repo.
  2. In the settings of the repository, enable issues and enable issue dependencies. Without the second, edhil stops with the message described in What differs between the forges.
  3. Create the label Projects, in the repository or in its organization.
  4. Create an issue with the title Check project and the label Projects, and note its number. It is the project of the epic that the check imports. Its title becomes a label of the epic and its work items.
  5. Create an access token for the issues of the repository. Put it in the environment variable that you name in the configuration:

    export FORGEJO_TOKEN=...
    
  6. In a git repository for the check, create edhil.yaml:

    forgejo:
      url: "https://forgejo.example.com"
      token_env: "FORGEJO_TOKEN"
      repository: "myowner/myrepo"
    

Read

  1. List what is open:

    edhil work-items
    

    With nothing but the project open it prints No open epics or work items., because a project is not a work item. If it fails, the message names Forgejo and what to check: the token (Forgejo rejected the access token), the repository (Project 'myowner/other' was not found on Forgejo) or the dependencies setting.

Import

  1. Write epic.md, with the number of the project issue in the Project line instead of 1:

    ````text

    Epic 1 - Forgejo check

    Project: #1

    An epic to check edhil against Forgejo.


## WI #1.1 - First item

Depends on: nothing

### High level summary

The first work item of the check.

### Steps

Add the file one.txt with the word one.

### Definition of done

  1. one.txt exists.

### Verification steps

   test -f one.txt

## WI #1.2 - Second item

Depends on: WI #1.1

### High level summary

The second work item of the check.

### Steps

Add the file two.txt with the word two.

### Definition of done

  1. two.txt exists.

### Verification steps

   test -f two.txt

2. See what would be created, without asking the server:

   ```text
   edhil import epic.md --dry-run
  1. Create the issues and answer yes to the question:

    edhil import epic.md
    

    It prints the epic and the two work items with their links. Open them in the browser and check that:

    • the epic has the label Epics, the work items have Work Items, and all three have the label named like the project;
    • the description of a work item is the text of its block and ends with Parent Epic: #N;
    • the epic lists the two work items as the issues it depends on, and the project lists the epic.
  2. List again:

    edhil work-items
    

    The epic is shown with its two work items.

Implement

  1. Choose an agent as in Choosing an agent and run the epic by the number that the import printed:

    edhil implement 2
    

    Both work items are implemented and committed one after the other, and the verification of each is run.

  2. Run edhil work-items again: the two work items are marked as committed.

Close

edhil does not close issues. Check the order that Forgejo accepts:

  1. Try to close the epic in the browser while a work item is open. Forgejo refuses.
  2. Close the two work items, then the epic, then the project.

Check the messages

Each of these changes edhil.yaml or the repository, and the command must stop with a message that names Forgejo and what to change:

Change Message
A token that the server does not accept Forgejo rejected the access token: check it is valid and has the scopes edhil needs
A repository that does not exist Project 'myowner/other' was not found on Forgejo, or the token does not have access to it
Issue dependencies disabled in the repository Issue dependencies are disabled in 'myowner/myrepo' on Forgejo: enable them in the settings of the repository
The variable of token_env not set Environment variable 'FORGEJO_TOKEN' is not set (configured as forgejo.token_env)

If a step does not do what this page says, keep the command, the answer of the server and the message of edhil, and open an issue.