# Open an issue

Track a bug or a task in a repository, with a Markdown description, labels, assignees and comments.

Issues and pull requests share one numbering per repository, as on GitHub, so `#12` in an issue or
comment names exactly one of them and links to it. The examples use the repository id
`5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60` and issue 12.

## Prerequisites

- Permission for `git:CreateIssue`. Reading issues needs `git:ListIssues`; editing, closing,
  labelling or assigning `git:UpdateIssue`; commenting `git:CommentOnIssue`. Choosing assignees in
  the Deutsche Cloud Console also needs `iam:ListUsers`, which lists the people to pick from.
- In the Deutsche Cloud Console, also `git:GetRepository` to open the repository's pages (without it the page
  is not found).
- The repository is not archived. In an archived repository **New issue** is not shown, and the API
  answers 409 `Repository is archived` to every change to an issue.
- Every label you name exists in the repository ([Manage labels](manage-labels.md)). An unknown one
  is refused with 422 `No such label: <name>`; an assignee that is not an IAM user of the
  organization with 422 `No such IAM user: <id>`.

## Open it

**Console**
1. In the repository, choose **Issues**, then **New issue**.
2. For **Title**, enter a title. **Description** (Markdown) is optional.
3. (Optional) Under **Labels**, pick labels. The field is shown only when the repository has
   labels. Assignees are set on the issue once it is open.
4. Choose **Open issue**. The issue's page opens with its number.

**CLI**
```sh
dcloud git issues create 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  --title "Checkout fails on empty cart" --labels bug
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/issues
{ "title": "Checkout fails on empty cart", "body": "Steps to reproduce: …", "labels": ["bug"] }
```

## Comment, close and reopen

On an issue, **Comment** adds to the thread. **Close issue** closes it as completed and **Close as
not planned** as not planned; with text in the box the first button reads **Close with comment**,
and either one posts the comment first. **Reopen issue** opens it again. **Edit** next to the title
renames it. Labels and assignees are edited under **Labels** and **Assignees** beside the thread; an
assignee must be an IAM user of the organization. Without a `stateReason`, the API closes an issue
as `completed`.

**Console**
1. Open the issue.
2. (Optional) Enter a comment.
3. Choose **Close issue** (**Close with comment** when you entered one) or **Close as not
   planned**. The issue shows its new state.

**CLI**
```sh
dcloud git issues update 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 12 \
  --state closed --state-reason not_planned
```

**API**
```http
PATCH /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/issues/12
{ "state": "closed", "stateReason": "not_planned" }
```

## Result

The issue's timeline shows, between the comments, who added or removed a label, assigned someone,
closed, reopened or renamed it.

## Related

- [Manage labels](manage-labels.md)
- Milestones, issue templates and closing an issue from a commit message are not supported; see
  [Not supported](not-supported.md).
- `git.issues.create` · `dcloud git issues create`
