Managing a project with issues

Last updated on 2026-10-21 | Edit this page

Estimated time: 40 minutes

Overview

Questions

  • How can I use Codeberg to plan and track the work in a project?
  • How can I report a problem or make a suggestion for someone else’s project?

Objectives

  • apply issues to report problems and suggest tasks in someone else’s repository
  • apply labels, assignees, milestones and project boards to plan and track the tasks in a project
  • apply references to commits, issues and people in comments
  • explain how the history of issues makes a project transparent and traceable
Callout

Extended workshop

This episode and the next one are part of the extended (lunch-to-lunch) version of this workshop. They build on the my-git-repo-<name> repositories that you created and pushed to Codeberg in the previous episodes.

For the exercises, find a partner and exchange your Codeberg usernames and the names of your repositories.

What are issues?

So far we have used Codeberg to store and share files. But a project is more than its files: there are tasks to do, problems to fix, questions to answer and decisions to document. Codeberg has a feature for this called issues.

An issue is like a ticket or a to-do item that belongs to a repository. It has a title, a description, and a discussion below it, and it is either open (still to be done) or closed (done or no longer relevant). By default, anybody with a Codeberg account can open an issue in a public repository. This makes sense: people can report problems and ask questions, even if they are not allowed to change anything themselves.

In research data management, issues are useful for example to

  • collect tasks for a data publication (“Add README with variable descriptions”, “Choose a license”),
  • report problems with a dataset (“Column age contains negative values in survey_2026.csv”),
  • document decisions and the discussion that led to them, so that they can be found again later.
Caution

Issues in public repositories are public

Everybody can read the issues of a public repository, and closed issues stay visible. Never put personal data, passwords or other confidential information into an issue.

Create an issue

Your partner’s repository has a README, but it doesn’t say who works on the project. You would like to suggest adding a list of contributors – and you would like to help with it and be on that list yourself. Since it’s your partner’s project, you don’t change it directly, but open an issue in their repository to make your suggestion.

We navigate to the repository of our partner, https://codeberg.org/some-researcher/my-git-repo-<partner> (with some-researcher replaced by our partner’s username and <partner> by their name). We click the tab “Issues” and then the button “New issue”.

We give the issue a short, descriptive title, for example “Add a list of contributors”, and a description:

MARKDOWN 

The people who contribute to this project should be mentioned in its documentation.
Their names could be listed in one of the following locations:

- a section in `README.md`
- a separate `CONTRIBUTORS.md` file

The description is written in Markdown, just like our README.md. Click on “Preview” above the text field to see how it will look.

Callout

Markdown code spans and blocks

Markdown provides syntax for formatting text in a monospaced font. This is usually used for file names, commands and code.

For a monospaced snippet within a normal paragraph, enclose the snippet in single backticks, for example

MARKDOWN 

The filename `README.md` will be set in a monospaced font.

For a whole block of monospaced text, for example some lines of code or the output of a command, start and end the block with a line consisting of three backticks:

MARKDOWN 

```
$ git status
On branch main
nothing to commit, working tree clean
```

On the right side of the form you may see fields for labels, milestones, projects and assignees. As we are not a collaborator in our partner’s repository, we can’t set most of them – that’s the job of the repository owner, which we’ll come to in a moment.

We click “Create issue”. This takes us to the new issue’s page. At the top we see its title, followed by its number, #1.

Callout

Issue numbers

On Codeberg, issues and pull requests share the same numbering in a repository. Our issue is the first one in our partner’s repository, so it gets the number #1; the next issue or pull request will be #2. We can refer to any issue or pull request with its number, as we will see.

Comment on an issue and reference a commit

We want to add a concrete suggestion where the list could be linked: in the README, which our partner created in their first commit. So we write a comment that refers to this commit.

When we mention a commit by its identifier, Codeberg automatically turns it into a link to that commit. To find the identifier, we open our partner’s repository in a second browser tab and click on “Commits”. The commit “Add README.md” is at the bottom of the list, with a short sequence of numbers and letters on the right: the beginning of the commit’s identifier, also called its hash or SHA. Next to it is a button to copy the full identifier.

Back on the issue page, we write a comment like this, pasting the identifier of the commit:

MARKDOWN 

The README was added in commit e9e8fd3f12b64fc3cbe8533e321ef2cdb1f4ed39 – it could link to the list of contributors.
I'm happy to help with this and would like to be on the list, too.

and click “Comment”. Our comment appears below the description, and Codeberg shows a shortened version of the identifier as a link.

Callout

Mentioning people, issues and commits

Codeberg recognises some special references in issues, comments and pull requests:

  • @username mentions a person, who will be notified,
  • #1 links to issue or pull request number 1 in the same repository,
  • a commit identifier links to that commit.

Triage: labels, assignees and milestones

In the meantime, our partner has opened an issue in our repository, too. Now we switch roles: as the owner of our repository, we are responsible for sorting incoming issues. This is often called triage.

We go to our own my-git-repo-<name> repository, click the tab “Issues” and open the issue from our partner.

Labels

Labels are coloured tags that help to group and filter issues, for example by type (“bug”, “question”, “documentation”) or by status (“in progress”, “needs discussion”).

Our repository doesn’t have any labels yet, so we create some first. On the “Issues” tab we click on “Labels”. Codeberg offers to load a predefined set of labels: select the “Default” set and confirm. This creates commonly used labels such as bug, enhancement and question.

To add our own label, we click “New label”, call it documentation, choose a colour and click “Create label”.

Back on the issue, we click on “Labels” in the sidebar on the right and select documentation.

Assignees

The “Assignees” field shows who is responsible for working on an issue. Only people with write access to the repository can be assigned, so we assign ourselves: click on “Assignees” in the sidebar and select your own username.

Milestones

A milestone groups issues that should be done by a certain point, for example “README complete” or, in a data project, “Data publication v1.0”. On the “Issues” tab, click “Milestones”, then “New milestone”. Give it a title and, optionally, a due date and click “Create milestone”. Then add the issue to the milestone in the sidebar of the issue. On the “Milestones” page you can now see how many of the milestone’s issues are already closed.

Project boards

When a project has many issues, it helps to see at a glance what is waiting, what is being worked on and what is done. Codeberg offers project boards for this, also known as Kanban boards.

We click the tab “Projects” in our repository and then “New project”.

Callout

No “Projects” tab?

If you don’t see a “Projects” tab, it may be switched off for your repository. You can enable it in the repository “Settings” under “Units” (or “Advanced settings”, depending on the Codeberg version).

We give the project a title, for example “My Git repository”, and choose the template “Basic kanban”. This creates a board with columns such as “To Do”, “In Progress” and “Done”. We click “Create project”.

To put an issue on the board, we open the issue and select our project under “Projects” in the sidebar. Back on the board, the issue appears as a card in the first column. We can now drag the card from one column to another, for example to “In Progress” once we start working on it.

Note that the board is only an overview: moving a card to “Done” does not close the issue. Closing an issue is something we do on the issue itself.

Task lists

Some issues contain several small steps. Markdown task lists turn these into checkboxes:

MARKDOWN 

- [ ] Create `CONTRIBUTORS.md`
- [ ] Link it from `README.md`

Codeberg shows the checkboxes in the issue, and in the list of issues you can see how many of them are already ticked.

Close an issue

Below the comment field of every issue there is a button “Close”. If you write something in the comment field first, you can add a final comment when you close the issue. Closed issues no longer appear in the list of open issues, but they are not deleted: you can still find them with the search or the “Closed” filter on the “Issues” tab. This makes issues a searchable record of what was done in a project and why.

Don’t close your partner’s issue yet! In the next episode, we will close it automatically with a pull request that solves it.

Challenge

Challenge: Issues in your own work

Think about a project you are currently working on (for example a dataset, a publication or a website).

  1. Write down three things that could be an issue in this project.
  2. Which labels would be useful to organise them?
  3. Would a milestone make sense? What would it be called?

If you like, create a new repository on Codeberg for this project and add the issues there. Remember not to include confidential information if the repository is public.

Challenge

Challenge: Explore the history of an issue

Open the issue that your partner created in your repository and scroll down.

What does Codeberg record in the history of the issue, apart from the comments? Why could this be useful?

Besides comments, Codeberg records events such as adding or removing labels, assigning people, adding the issue to a milestone or project, and closing or reopening the issue – each with the person who did it and when. This makes it easy to follow who did what at which point in time, which is helpful in teams and for documenting a project.

Key Points
  • Issues are used to report problems, ask questions and plan tasks in a repository
  • Anybody with a Codeberg account can open issues in a public repository
  • Labels, assignees and milestones help to organise issues
  • Project boards give an overview of the state of issues
  • Commits, issues (#1) and people (@username) can be referenced in issues and comments
  • Closed issues remain as a searchable record of the project