GitHub issue on GitHubissa oleva tehtävä, huomio, virheraportti tai keskustelun aloitus, joka liittyy johonkin repositoryyn. Issue ei ole suoraan koodimuutos, vaan tapa kirjata ylös mitä projektissa pitäisi tehdä, korjata, selvittää tai suunnitella.

Issueita voidaan ajatella projektin tehtävälistana. Niiden avulla tiimi näkee yhdestä paikasta, mitkä asiat ovat kesken, kuka niitä tekee ja miksi jokin muutos tarvitaan.

Issueita tehdään, jotta projektin työ ei jää pelkästään muistin, chat-viestien tai suullisten keskustelujen varaan. Kun asia kirjataan issueksi, se on helpompi löytää, jakaa ja ratkaista.

Tyypillisiä syitä issueiden tekemiseen ovat:

• Bugin ilmoittaminen: sovelluksessa on virhe, joka pitäisi korjata.
• Uuden ominaisuuden ehdottaminen: projektiin halutaan lisätä uusi toiminto.
• Parannusehdotus: olemassa olevaa toimintoa tai koodia voisi kehittää paremmaksi.
• Tehtävän jakaminen: tiimi voi sopia, kuka tekee minkäkin asian.
• Keskustelun dokumentointi: päätökset ja perustelut jäävät talteen projektin yhteyteen.

Hyvä issue auttaa muita ymmärtämään ongelman tai tehtävän ilman, että asiasta tarvitsee kysyä erikseen lisätietoja.

Issue tehdään GitHubissa repositoryn sivulla. Perusvaiheet ovat seuraavat:

1. Avaa GitHubissa se repository, johon asia liittyy.
2. Valitse ylävalikosta Issues.
3. Paina painiketta New issue.
4. Kirjoita issuelle selkeä otsikko.
5. Kirjoita kuvaus, jossa kerrot mitä pitäisi tehdä tai mikä ongelma on.
6. Lisää tarvittaessa kuvia, virheilmoituksia, tehtävälista tai linkkejä.
7. Valitse tarvittaessa vastuuhenkilö kohdasta Assignees.
8. Lisää tarvittaessa aihetta kuvaava label, esimerkiksi bug, enhancement tai documentation.
9. Luo issue painamalla Submit new issue.

Kaikkia lisätietoja ei tarvitse tietää heti. Issuea voi myöhemmin kommentoida, muokata ja sulkea, kun asia on ratkaistu.

Hyvä issue on riittävän tarkka. Pelkkä otsikko kuten "ei toimi" ei yleensä auta muita ratkaisemaan ongelmaa. Parempi issue kertoo, mitä tapahtui, mitä olisi pitänyt tapahtua ja miten ongelman voi toistaa.

Hyvässä issuessa voi olla esimerkiksi seuraavat osat:

• Otsikko: lyhyt ja kuvaava nimi asialle.
• Kuvaus: mitä ongelmaa tai tehtävää issue koskee.
• Toistamisen vaiheet: miten bugi saadaan näkyviin.
• Odotettu toiminta: mitä sovelluksen pitäisi tehdä.
• Todellinen toiminta: mitä sovellus tekee nyt.
• Lisätiedot: kuvakaappaukset, virheilmoitukset, selain, käyttöjärjestelmä tai muut havainnot.

Alla on esimerkki bugiraportista, joka voisi olla GitHub issue:

Otsikko:
Kirjautuminen epäonnistuu oikealla salasanalla

Kuvaus:
Käyttäjä ei pääse kirjautumaan sisään, vaikka sähköposti ja salasana ovat oikein.
Ongelma tapahtuu kirjautumissivulla.

Toistamisen vaiheet:
1. Mene osoitteeseen /login
2. Kirjoita olemassa olevan käyttäjän sähköposti
3. Kirjoita oikea salasana
4. Paina "Kirjaudu"

Odotettu toiminta:
Käyttäjä kirjataan sisään ja siirretään etusivulle.

Todellinen toiminta:
Sivu näyttää virheilmoituksen "Kirjautuminen epäonnistui".

Lisätiedot:
- Selain: Chrome
- Käyttöjärjestelmä: Windows
- Ongelma alkoi viimeisimmän päivityksen jälkeen

Tällainen issue on hyödyllinen, koska se kertoo selkeästi ongelman, antaa ohjeet ongelman toistamiseen ja kertoo, millaista toimintaa sovellukselta odotetaan.

Issue kuvaa yleensä ongelman tai tehtävän. Pull request taas sisältää koodimuutoksen, jolla issue voidaan ratkaista. Yleinen työtapa on:

1. Luodaan issue, jossa kuvataan tehtävä tai bugi.
2. Tehdään uusi branch korjausta tai ominaisuutta varten.
3. Tehdään tarvittavat koodimuutokset.
4. Avataan pull request.
5. Kun muutos hyväksytään ja yhdistetään, issue voidaan sulkea.

GitHubissa pull requestin kuvaukseen voidaan kirjoittaa esimerkiksi Fixes #12. Tällöin GitHub sulkee issuen numero 12 automaattisesti, kun pull request yhdistetään.

GitHub issue voi toimia tehtävänä myös GitHub Copilotille. Jos projektissa on käytössä Copilot coding agent, issuen voi määrätä Copilotille samalla tavalla kuin ihmisellekin kohdasta Assignees.

Tällöin Copilot lukee issuen kuvauksen, tutkii repositoryn koodia ja yrittää tehdä pyydetyn muutoksen. Yleensä Copilot ei muuta suoraan päähaaraa, vaan tekee uuden branchin ja avaa pull requestin, jonka ihminen voi tarkistaa.

Esimerkiksi issue voisi olla:

Otsikko:
Lisää kirjautumissivulle virheilmoitus tyhjästä salasanasta

Kuvaus:
Jos käyttäjä painaa Kirjaudu-painiketta ilman salasanaa, näytä viesti:
"Salasana puuttuu."

Hyväksymiskriteerit:
- Tyhjä salasana estää kirjautumisyrityksen
- Käyttäjälle näytetään selkeä virheilmoitus
- Muut kirjautumistoiminnot säilyvät ennallaan

Tällainen issue on hyvä tehtävänanto sekä ihmiselle että Copilotille, koska siinä kerrotaan mitä pitää tehdä ja mistä tiedetään, että tehtävä on valmis.

Copilotin tekemät muutokset pitää aina tarkistaa ennen mergeä. Tekoäly voi ymmärtää tehtävän väärin, muuttaa liian paljon tai tehdä ratkaisun, joka ei sovi projektin tyyliin. Siksi pull request kannattaa lukea läpi, testata ja tarvittaessa pyytää korjauksia.

Copilotin käyttö issueiden perusteella voi vaatia Copilot-tilauksen tai kuluttaa Copilotin kuukausittaisia käyttörajoja. Saatavuus riippuu GitHub-tilistä, organisaation asetuksista ja siitä, onko Copilot coding agent otettu käyttöön kyseisessä repositoryssa.

Copilot coding agentin käyttöönotto riippuu siitä, onko repository omalla GitHub-tilillä vai organisaation alla. Lisäksi käyttäjällä pitää olla Copilot-tilaus tai muu oikeus käyttää Copilotia.

Huom: Copilot coding agentin käyttö vaatii yleensä maksullisen Copilot-oikeuden, kuten Copilot Pro tai Copilot Pro+. Opiskelija voi saada Copilotin maksutta GitHub Education -opiskelijastatuksen kautta, jos GitHub hyväksyy opiskelijastatuksen ja etu on saatavilla.

Oma repository:
Jos käytössä on Copilot Pro tai Pro+, Copilot coding agent on yleensä käytössä oletuksena. Jos Copilotia ei voi valita issuen vastuuhenkilöksi, tarkista asetukset:

1. Avaa GitHubissa oma profiilikuvasi oikeasta yläkulmasta.
2. Valitse Copilot settings.
3. Valitse sivuvalikosta Cloud agent.
4. Tarkista kohta Repository access.
5. Valitse All repositories tai Only selected repositories ja lisää haluttu repository.

Tämän jälkeen Copilotin pitäisi olla valittavissa issuen Assignees-kohdassa, jos repository tukee toimintoa ja sinulla on tarvittavat oikeudet.

Organisaation repository:
Jos repository kuuluu organisaatiolle, organisaation omistajan tai ylläpitäjän pitää sallia Copilot coding agent organisaation asetuksista. Tyypillinen polku on:

1. Avaa GitHubissa organisaation sivu.
2. Valitse Settings.
3. Valitse sivuvalikosta Copilot.
4. Avaa Cloud agent tai Copilotin policy-asetukset.
5. Salli Copilot coding agent organisaation jäsenille.
6. Valitse, saako agenttia käyttää kaikissa repositoryissa vai vain valituissa repositoryissa.

Kun Copilot coding agent on sallittu repositoryssa, käyttäjä, jolla on oikeus käyttää Copilotia ja kirjoitusoikeus repositoryyn, voi antaa issuen Copilotin tehtäväksi.

Jos Copilot ei näy issuen vastuuhenkilöissä, syynä voi olla esimerkiksi puuttuva Copilot-tilaus, organisaation estävä policy, repositoryn rajoitus tai se, että käyttäjällä ei ole riittäviä oikeuksia repositoryyn.