GitHub

GitHub connects software-development activity to Hamstik Projects and Work Items. Hamstik reads the development evidence that GitHub already owns and presents the relevant repository, commit, pull-request, review, GitHub Actions, and artifact metadata alongside your planning work.

GitHub remains the authoritative source-control and continuous-integration system. This integration is read-oriented: Hamstik does not write code or change GitHub records.

Preview

GitHub is currently a Preview Application. The available workflow and limits may change as the integration matures.

Overview

After you connect the Hamstik GitHub App and select repositories for a Project, Hamstik can associate the following evidence with that Project:

• repository identity and metadata, including visibility, archive state, default branch, and GitHub link;
• commits, including the message, author, branch, timestamp, and GitHub link;
• pull requests and their reviews, including draft, open, closed, merged, and review states;
• GitHub Actions workflow runs, jobs, status, conclusion, timestamps, and provider link;
• artifact metadata associated with completed workflow runs; and
• automatic relationships between development evidence and existing Hamstik Work Items.

Project Development shows the shared development view for selected repositories. A Work Item’s Development area shows the commits, pull requests, reviews, and builds that link to that Work Item. GitHub and Gitea evidence can appear together, with the provider identity preserved.

Availability

GitHub is available as a Preview first-party Application. An Organization owner or administrator can manage the Organization connection and Project repository bindings. Organization members can view Apps where their Hamstik permissions allow it.

What Hamstik Reads from GitHub

Hamstik reads repository and development evidence through the Hamstik GitHub App. It reads repository metadata, commit history, pull requests, pull-request reviews, GitHub Actions runs and jobs, and artifact metadata. Hamstik stores the normalized evidence needed for Project and Work Item views; it does not copy artifact files into Hamstik.

Hamstik does not treat GitHub as a second Work Item system. A GitHub reference links an existing Hamstik Work Item when the repository and Project rules below are satisfied; it does not create a Work Item or synchronize GitHub Issues.

Requirements

Before connecting GitHub, make sure that:

• you are an Organization owner or administrator with permission to manage Apps;
• the GitHub account or GitHub Organization you intend to connect can install the Hamstik GitHub App;
• any GitHub Organization approval policy has been satisfied; and
• the repositories you need are accessible to the GitHub App installation.

GitHub v1 supports GitHub.com and GitHub Enterprise Cloud hosted on GitHub.com. GitHub Enterprise Server with a customer-controlled hostname is not supported.

Required GitHub permissions

The Hamstik GitHub App requests these read-oriented repository permissions:

Permission	Why Hamstik needs it
Metadata — Read	Identify repositories and read repository metadata such as visibility, archive state, and default branch.
Contents — Read	Read commit information and the source branches associated with development activity.
Pull requests — Read	Read pull requests and their review activity.
Actions — Read	Read workflow runs, jobs, statuses, conclusions, and artifact metadata.

You do not paste a GitHub personal access token (PAT) into Hamstik. You also do not enter an API hostname, private key, webhook secret, or repository webhook in Hamstik.

Connect GitHub

An Organization owner or administrator starts the connection from Hamstik. The connection uses the Hamstik GitHub App and a temporary authorization through GitHub; it does not use a user-supplied token.

To connect GitHub:

1. Open Organization Settings.
2. Select Apps.
3. Select GitHub.
4. Select Connect GitHub.
5. When GitHub opens, sign in to the GitHub account that should authorize the installation.
6. Choose whether to install the Hamstik GitHub App on a GitHub Organization or on your personal GitHub account, if GitHub offers both choices.
7. Choose All repositories or Only select repositories in GitHub, then approve the installation. A GitHub Organization owner may need to approve the request.
8. Return to Hamstik. Hamstik verifies the specific installation and starts discovering the repositories that installation can provide.

After a successful connection, the GitHub card in Organization Settings shows the connected account, account type, GitHub repository access mode, repository counts, synchronization information, and connection health. A successful connection does not automatically select repositories for every Project.

GitHub Account Installations

Each GitHub App installation appears as its own connection in Hamstik. You can connect multiple installations to one Hamstik Organization, such as:

• more than one GitHub Organization; or
• a GitHub Organization and a personal GitHub account.

When a Project has access to more than one connected installation, choose the appropriate installation/account before selecting repositories. A single GitHub installation can belong to only one active Hamstik Organization.

Repository Access

There are two separate repository decisions:

GitHub access and Project selection are different

GitHub App repository access is the set of repositories that GitHub permits the Hamstik GitHub App installation to read.

Hamstik Project repository selection is the smaller set of accessible repositories that a user explicitly associates with one Hamstik Project.

Giving the GitHub App access to a repository does not attach that repository to every Hamstik Project. Hamstik can select a repository only after the GitHub App installation is permitted to access it.

To change GitHub-side access, select Manage on GitHub on the connection card in Hamstik. GitHub’s installation settings let you change between all repositories and selected repositories, or add and remove individual repositories. Changing GitHub access does not change Hamstik Project selections by itself.

Add Repositories to a Project

Repository selection is explicit for each Project.

To add repositories:

1. Open the Project.
2. Open Project Settings.
3. Select Apps.
4. Find the GitHub repositories card and choose the connected GitHub installation/account.
5. Search repositories or move through the pages of the accessible catalog.
6. Select the repositories for this Project. The list identifies private, public, archived, and inaccessible repositories.
7. Select Save repositories.

The Project can select up to 50 repositories for one GitHub connection. Selections on other catalog pages are retained while you search or page through the list. Use Refresh access to request an updated GitHub repository catalog, then Reload list to read the current catalog in the Project view.

Removing a checkmark and selecting Save repositories removes that repository from this Project. It does not remove the GitHub App’s access. A repository may participate in more than one Hamstik Project.

Development Activity

Open Development from a Project to review normalized development evidence for its selected repositories. The view includes repository identity, commits, pull requests and reviews, GitHub Actions builds, jobs, and artifact metadata. Links open the original record in GitHub.

Open a Work Item’s Development area to see the activity that Hamstik linked to that Work Item. GitHub and Gitea use the same Hamstik Development experience; they are not separate Work Item record types.

Work Item Linking

Hamstik recognizes a full Work Item reference in this format:

PROJECTKEY-123

For example:

HAM-123

GitHub references can appear in:

• commit messages;
• pull-request titles;
• pull-request descriptions or bodies; and
• source branch names.

For example, each of these can link development activity to HAM-142:

Fix authentication timeout HAM-142

feature/HAM-142-github-retry

HAM-142 Add repository synchronization

Matching is case-insensitive, and repeated references are deduplicated. Multiple Work Item keys can be present in the same supported field.

For a link to be created:

• the full PROJECTKEY-123 reference must be present;
• the referenced Work Item must already exist;
• the repository must be selected for the Hamstik Project that owns the Work Item; and
• the reference must be in one of the supported locations above.

The number alone, such as 142, is not enough. A key belonging to another Project does not automatically link to this Project, and Hamstik does not create missing Work Items. If a reference did not link, check the key, Work Item, Project repository selection, and repository access before requesting Sync now.

GitHub Actions

Hamstik reads GitHub Actions in a read-only way. It records workflow name and run identity, triggering event, branch, commit, status, conclusion, timestamps, jobs, and a link back to GitHub. The Development view summarizes the workflow and its current status or conclusion.

Hamstik does not dispatch, rerun, cancel, or edit GitHub Actions workflows. It does not mirror Actions logs. Use GitHub to interact with the workflow run.

Synchronization

Saving a new repository selection queues an asynchronous initial synchronization. The browser does not wait for the history import to finish. Recently queued work can take a short time to appear in Project Development or a Work Item’s Development area.

The initial synchronization is bounded:

Evidence	Initial window and bound
Default-branch commits	Previous 90 days, up to 1,000 commits.
Pull requests	Pull requests updated in the previous 90 days, up to 500, including open, closed, and merged pull requests.
Reviews	Reviews for the synchronized pull requests, paginated as needed.
GitHub Actions runs	Previous 30 days, up to 500 runs.
Run jobs and artifacts	Paginated metadata for synchronized runs; artifact files are not copied.

GitHub events normally update selected repositories automatically. Hamstik also performs periodic reconciliation to refresh repository access and recover from missed events. Sync now in Organization Settings or Project Settings queues reconciliation and returns promptly; it does not mean the work is complete immediately. Repeated requests may be combined. Refresh repositories or Refresh access updates the repository catalog, while Reload list rereads the catalog already available to the Project.

Artifact Metadata

For completed GitHub Actions runs, Hamstik records artifact metadata such as the artifact name, size, creation and expiry information, expired state, and workflow-run association.

Hamstik does not mirror artifact binaries, store them in Hamstik storage, or retain authenticated artifact download URLs. Open the workflow run in GitHub to interact with its artifacts.

Connection Health

Organization Settings shows the health of each GitHub connection. The labels currently exposed by Hamstik include:

UI label	What to do
Connected	Hamstik can communicate with the active GitHub installation.
Degraded · failed synchronization	Review the queued and failed counts, confirm repository access, and select Sync now after correcting the cause.
Degraded · sync delayed	A provider delay, rate limit, or temporary outage is slowing synchronization. Allow the queued work to retry, then check again.
Degraded · connection needs attention	Test the connection and review the GitHub installation, permissions, or access state.
Suspended on GitHub	The installation is suspended at GitHub. Resolve the suspension in GitHub before testing or syncing again.
Removed on GitHub	The GitHub installation was removed. Reinstall or authorize the App in GitHub, then connect it again in Hamstik if needed.
Disabled	The Hamstik connection is locally disabled. An Organization administrator can select Enable.
Awaiting installation	The Hamstik connection has not completed a verified GitHub installation yet. Start again with Connect GitHub.
Reconnection required	This is a legacy or unverified connection. Disconnect it and use the current Connect GitHub flow.

Change Repository Access

If GitHub App access is removed from a repository that a Project already selected:

1. Hamstik stops receiving and synchronizing new development information for that repository.
2. The Project relationship and existing normalized development evidence are retained.
3. The repository remains visible as Inaccessible, and its historical evidence remains available.
4. Restore the repository’s access in the GitHub App installation settings.
5. Select Refresh repositories in Organization Settings, then Refresh access or reload the Project repository list.
6. Synchronization resumes for the existing selection after access is restored.

Removing GitHub access is not the same as disconnecting the Hamstik connection. The GitHub installation can still serve other accessible repositories and Projects.

Disconnect GitHub

These actions have different effects:

Action	Effect
Change repository access in GitHub	Changes which repositories the App installation may read. Existing Hamstik selections can become inaccessible until access is restored.
Disconnect in Hamstik	Stops future synchronization for that connection and removes its Hamstik Project bindings. Historical Development evidence, Work Item relationships, and audit evidence remain readable under normal retention rules. It does not uninstall the App in GitHub.
Uninstall the Hamstik GitHub App in GitHub	Removes the provider installation’s active access. Hamstik shows the installation as removed when it receives and reconciles that state; existing historical evidence remains available.

If you reconnect after disconnecting, select the repositories for each Project again. Disconnecting Hamstik does not change or uninstall the GitHub App itself.

Security and Permissions

Hamstik connects through the Hamstik GitHub App installation and requests only the read-oriented permissions listed above. Users do not need to create or paste a PAT. Repository access remains governed by GitHub’s App installation settings.

Hamstik limits the integration to GitHub.com’s fixed service and does not accept a customer-selected GitHub server URL. GitHub information is shown only within the authorized Hamstik Organization and the Projects that select the repository. The integration does not grant write access to code, pull requests, repositories, or Actions.

Current Limitations

GitHub v1 does not provide:

• GitHub Issues synchronization or Work Item ↔ GitHub Issue synchronization;
• comments written back to GitHub;
• creating, updating, approving, or otherwise managing pull requests;
• committing source code or administering repositories;
• branch-protection administration;
• GitHub Actions dispatch, rerun, cancellation, or workflow editing;
• Actions log mirroring;
• artifact binary mirroring;
• GitHub Enterprise Server support; or
• PAT-based authentication.

Troubleshooting

GitHub does not appear connected

Confirm that the Hamstik GitHub App is installed on the intended GitHub Organization or personal account, that any Organization approval is complete, and that you returned to Hamstik using the same signed-in user who started the connection. Start again from Organization Settings → Apps → GitHub → Connect GitHub if the authorization expired or was already used.

A repository is not listed

First check GitHub-side App access and Organization approval. Then choose the correct connected installation/account in Project Settings, select Refresh repositories in Organization Settings, select Refresh access in the Project, clear the search, and select Reload list. GitHub App access only makes a repository available to Hamstik; it does not select the repository for a Project.

A repository says access removed

Open Manage on GitHub for the connection and restore access to the repository. Refresh the Organization catalog and the Project list. The existing Project selection and historical evidence are retained while the repository is inaccessible.

The GitHub connection is suspended

Resolve the suspension in GitHub. Hamstik pauses provider reads while the installation is suspended. After GitHub restores the installation, return to Hamstik, test the connection if available, and select Refresh repositories or Sync now.

Development activity has not appeared yet

Initial synchronization is asynchronous and bounded. Check the connection’s last sync time and queued or failed counts, then select Sync now. A queued response means Hamstik accepted the work; it does not mean the provider data is already visible. Temporary provider rate limits and outages can delay synchronization.

A Work Item did not link

Check all of the following:

• the reference uses the full PROJECTKEY-123 form, such as HAM-142;
• the Project key is correct and the Work Item already exists;
• the reference is in a commit message, pull-request title or body, or source branch;
• the repository is selected for the Project that owns the Work Item; and
• the repository is still accessible to the GitHub App.

Numbers alone, nonexistent Work Items, and references to another Project key do not create links. After correcting the reference or binding, allow synchronization to run or select Sync now.

GitHub Actions activity is missing

Check that the repository is accessible to the GitHub App and that the App still has Actions — Read permission. Confirm the repository is selected for the Project, then check synchronization state and select Sync now. Hamstik records metadata and links to GitHub; it does not mirror Actions logs or artifact files.

For related product concepts, see Applications, Projects, Work Items, Users & permissions, and the Roles & permissions reference.