Checking edhil against a Forgejo server
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
- Create a repository, or use one for tests, and note its name as
owner/repo. - 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.
- Create the label
Projects, in the repository or in its organization. - Create an issue with the title
Check projectand the labelProjects, 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. -
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=... -
In a git repository for the check, create
edhil.yaml:forgejo: url: "https://forgejo.example.com" token_env: "FORGEJO_TOKEN" repository: "myowner/myrepo"
Read
-
List what is open:
edhil work-itemsWith 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
-
Write
epic.md, with the number of the project issue in theProjectline instead of1:````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
- 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
- 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
-
Create the issues and answer yes to the question:
edhil import epic.mdIt 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 haveWork 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.
- the epic has the label
-
List again:
edhil work-itemsThe epic is shown with its two work items.
Implement
-
Choose an agent as in Choosing an agent and run the epic by the number that the import printed:
edhil implement 2Both work items are implemented and committed one after the other, and the verification of each is run.
-
Run
edhil work-itemsagain: the two work items are marked as committed.
Close
edhil does not close issues. Check the order that Forgejo accepts:
- Try to close the epic in the browser while a work item is open. Forgejo refuses.
- 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.