| 1 | --- |
| 2 | title: Milestones |
| 3 | description: Gather issues and pull requests under a goal and a due date, and see how much of it is done. |
| 4 | --- |
| 5 | |
| 6 | A milestone gathers issues and pull requests under one goal, such as a |
| 7 | release, with an optional due date. Its page shows everything in it and how |
| 8 | far along it is: the share of its issues and pull requests that are |
| 9 | closed. A merged pull request counts as closed. |
| 10 | |
| 11 | ## Make a milestone |
| 12 | |
| 13 | You need the Triage [role](/guides/access-and-roles/) or higher. |
| 14 | |
| 15 | 1. Open the project's **Issues**, then **Milestones**. |
| 16 | 2. Choose **New milestone**. |
| 17 | 3. Give it a title, unique in the repository, and if you like a due date |
| 18 | and a description. The description is Markdown. |
| 19 | 4. Choose **Create milestone**. |
| 20 | |
| 21 | Milestones are numbered from 1 in each repository, apart from issues and |
| 22 | pull requests. The number is in its address: |
| 23 | `g1t.sh/<owner>/<repo>/milestones/3`. |
| 24 | |
| 25 | ## Put an issue or a pull request in one |
| 26 | |
| 27 | 1. Open the issue or pull request. |
| 28 | 2. In the sidebar, choose the settings icon beside **Milestone**. |
| 29 | 3. Pick a milestone, or **Clear milestone** to take it out. |
| 30 | |
| 31 | An item is in at most one milestone. Moving it is noted in the |
| 32 | conversation, and is an `issue.milestoned` or `issue.demilestoned` event |
| 33 | (`pull.milestoned` and `pull.demilestoned` on a pull request). With the |
| 34 | Triage role you can also choose a milestone on **New issue**. |
| 35 | |
| 36 | ## Follow its progress |
| 37 | |
| 38 | **Milestones** lists open milestones soonest due first, then those without |
| 39 | a due date; **Closed** lists the rest, most recently closed first. Each |
| 40 | shows its due date, how many of its items are open and closed, and a bar |
| 41 | of how much is done. One whose due date has passed says how late it is. |
| 42 | |
| 43 | A milestone's page lists its open and closed issues and pull requests, |
| 44 | newest first. On **Issues** or **Pull requests**, choose **Milestone** to |
| 45 | filter the list by one; the address keeps it as `?milestone=3`. |
| 46 | |
| 47 | ## Change, close or delete one |
| 48 | |
| 49 | With the Write role or higher, on **Milestones** or a milestone's page (putting an issue in one needs only Triage): |
| 50 | |
| 51 | | To | Do this | |
| 52 | | --- | --- | |
| 53 | | Change its title, due date or description | **Edit**, on its page. | |
| 54 | | Close it, once it is done | **Close**. **Reopen** opens it again. | |
| 55 | | Delete it | **Delete**. What was in it stays as it is, in no milestone. This cannot be undone. | |
| 56 | |
| 57 | ## From the API |
| 58 | |
| 59 | | To | REST | MCP | |
| 60 | | --- | --- | --- | |
| 61 | | List milestones | `GET /repos/{owner}/{name}/milestones`, `state` to filter | `repository` `list_milestones` | |
| 62 | | Get one with its items | `GET /repos/{owner}/{name}/milestones/{milestone}` | `repository` `get_milestone` | |
| 63 | | Make one | `POST /repos/{owner}/{name}/milestones` | `repository` `create_milestone` | |
| 64 | | Change one | `PATCH /repos/{owner}/{name}/milestones/{milestone}` | `repository` `update_milestone` | |
| 65 | | Delete one | `DELETE /repos/{owner}/{name}/milestones/{milestone}` | `repository` `delete_milestone` | |
| 66 | |
| 67 | A milestone has `number`, `title`, `description`, `due_on` (`YYYY-MM-DD`), |
| 68 | `state` (`open` or `closed`), `open_items` and `closed_items`. Send |
| 69 | `"due_on": ""` to clear a due date, and `"state": "closed"` to close it. |
| 70 | |
| 71 | ```sh |
| 72 | curl -X POST https://api.g1t.sh/repos/acme/web/milestones \ |
| 73 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 74 | -H "Content-Type: application/json" \ |
| 75 | -d '{"title": "Launch", "due_on": "2026-10-14"}' |
| 76 | ``` |
| 77 | |
| 78 | `milestone`, a milestone's number, puts an item in it on `create_issue`, |
| 79 | `update_issue` and `update_pull_request`; `null` or `0` takes it out. |
| 80 | Issues and pull requests carry `milestone` as `{"number", "title"}`, and |
| 81 | `milestone` filters `list_issues` and `list_pull_requests`. Managing |
| 82 | milestones needs a token with `issues:write`. |
| 83 | |
| 84 | [Dependency updates](/guides/dependency-updates/) put their pull requests |
| 85 | in the milestone their entry's `milestone` names. |