# Link a GitHub repository Show the code changes of a project on the tasks they belong to, so everyone on the team sees what was actually built and when. GitHub is where many developers keep their code. Every change they save there is a "commit", with a short message that says what changed. Link a repository (the place on GitHub where the code of one project lives) to a project in Taskstand, and those commits show up in Taskstand and hang themselves on the task they mention, so a client project shows what was actually built, next to the work that asked for it. No code involved in your project? Then there is nothing to link, and you can skip this page. ## What you need | | | |---|---| | Plan | The plan of the **project owner** decides. Every paid plan (Plus, Pro and Business) carries repositories, and so does the free trial. See [plans and limits](). | | Who links a repository | The owner of the project, on the project settings. | | Who sees the commits | Owner, Manager and Team member. | | Who never sees them | Client, Reader and Restricted members. | A project can hold more than one repository, for example a website next to an app, up to five. ## Link a repository with the GitHub app The easiest way is the Taskstand app on GitHub. You install it once on your GitHub account or organisation and choose which repositories it may read. 1. Open the project, click **Project settings** (the gear at the end of the project bar) and go to **Code**. 2. Under **Code on GitHub**, click **Install on GitHub**. 3. On GitHub, pick the account or organisation and choose which repositories the app may read. GitHub sends you back to Taskstand. 4. Click **Pick a repository**, choose one under **Which repository?** and click **Link**. Is the app already installed in your organisation, by you or by a colleague? Click **Sign in with GitHub** instead of installing it again. If you may not install apps on an organisation yourself, GitHub asks the owners of that organisation to do it. Once they have, come back and click **Sign in with GitHub**. Repository not in the list? Click **Choose on GitHub** under the form to give the app access to more repositories, or to another organisation. ### What the app may do The app asks GitHub for two permissions only: - **Contents: read**, to read the commits. - **Metadata: read**, to see the names of the repositories and branches. It never writes to your repository, never changes code, and never opens issues or pull requests. Taskstand does not store your code at all, see below. ## Link with an access token instead If you cannot use the app, for example because your organisation does not allow it, open **Or link with an access token instead** on the same page. A token is a kind of password that only opens what you tick. 1. On GitHub, make a fine-grained personal access token (the **Make a token** link takes you there). Limit it to this one repository and give it these permissions: - **Contents**: read - **Metadata**: read - **Webhooks**: read and write 2. Paste it into **GitHub access token** and click **Continue**. Nothing is linked yet. 3. Pick the repository under **Which repository?** and click **Link**. The webhook permission lets Taskstand ask GitHub to send every new push (a new batch of commits) straight to Taskstand. Without it the history still comes in, but new commits do not arrive on their own, and the settings say so. A link made with a token can move to the app later with **Move to the GitHub app** on its row. The commits and the tasks they hang on stay where they are. ## Name a task in a commit message Put the task reference in the commit message, and the commit shows up on that task: ``` Fix the date picker on the booking form (WEB-12) ``` The reference is the project key followed by the task number. You see it at the top of every task, and clicking it copies it. Pasting a link to the task works too. One commit may name several tasks. A bare `#12` does not work, because GitHub writes numbers like that into the merge commits it makes itself, and every merged pull request would then land on the wrong task. Only references with the key of this project count, so a commit that names a task of another project is left alone. If you change the project key later, older references stop matching. ## The history and the branches When you link a repository, Taskstand reads the history of every branch (a separate line of changes, like `main` or `dev`) back to the beginning. A message says **The commits are on their way.**, and the commits appear as they come in. Commits made before the link that already name a task are hung on it as well. After that, every push comes in on its own within moments. A commit often sits on more than one branch, for example after a merge. Taskstand remembers which branches reach each commit, so filtering on a branch shows everything that is on it. ## The Code page Once a repository is linked, Owners, Managers and Team members get a **Code** button in the project bar. The **Commits** list there shows every commit, newest first, grouped by day, with the tasks each one names. - **Search the message or a sha**: finds a word in the message, or a commit by the start of its sha (its code, like `3534da1`). - **All branches**: show only the commits on one branch. - **All repositories**: show one repository when the project has several. A commit whose author uses the same e-mail address as a member of the project shows that member's picture. ## Link a commit to a task by hand Forgot to name the task in the message? You can still hang the commit on the task, from the task itself: - **In a comment**: mention the commit by its sha, like `3534da1`, and it hangs itself on the task. - **With the picker**: under **Commits** on the task, click **Link a commit**, search the message or paste a sha, and click the commit. **Hide commits that are on another task** leaves out the ones already doing work elsewhere. A commit Taskstand has not read yet, for example from a branch nobody pushed to since the link, can be fetched with **Fetch … from GitHub** in the picker. To take a commit off a task, hover it and click **Unlink this commit**. ## Keep the link working Once a day Taskstand asks GitHub whether each link still works. When GitHub clearly says no, the link is switched off (you see **Switched off**) and a red line on the settings explains what to do. A red dot on **Code** in the project settings tells you something needs a look. | What the settings say | What to do | |---|---| | GitHub refused this token | Replace the token. | | This token may not add a webhook | Replace the token with one that has **Webhooks: read and write**. | | The GitHub app was removed | Install the app again and link the repository. | | The GitHub app is suspended | Unsuspend it on GitHub. | | The GitHub app may no longer read this repository | Add the repository to the app on GitHub. | | Whoever linked it can no longer reach it | Link it again with an account that can. | A token usually has an end date. The settings show **Token expires on …**, and that line turns orange a month before. Click **Replace token** (the key icon) to paste a new one: the commits stay. A link through the app has no token to replace. **Read this repository again** (the arrows icon) reads the history once more if you think something is missing. ## Unlink or uninstall - **Unlink** (the cross on the row) removes the link and **all its commits** from this project. The tasks themselves stay. - **Disconnect** next to your GitHub sign in switches off every repository linked through it, on all your projects. Their commits stay. The app stays installed on GitHub until you remove it there. - **Uninstalling the app on GitHub** switches off its links. The commits already in Taskstand stay, and linking the repository again picks up where it left off. If the owner's plan no longer carries repositories, the link and its commits stay where they are but the Code page closes. The owner can still unlink. ## What is stored For each commit Taskstand keeps: - the sha (the code of the commit) and the link to it on GitHub - the full message - the author's name and e-mail address, as git recorded them - the date - which branches it is on, and which tasks it names Your code itself is never read into Taskstand or stored. Deleting the project, or unlinking the repository, removes its commits.