Skip to main content
The GitHub integration links a GitHub repository to an Arca list so that issues and tasks stay in sync. You can choose one-way sync (GitHub issues flow into Arca) or two-way sync (Arca tasks are also exported to GitHub). Commit message keywords let developers close, reopen, or change task state directly from their terminal without ever opening Arca.

​
Requirements

  • You must be an Admin or Owner of the Arca workspace to connect and configure the integration.
  • You need permission to install GitHub Apps on the target GitHub organization or personal account.

​
Connect GitHub

1

Open Integrations settings

In Arca, click your workspace name in the top-left, then go to Settings → Integrations.
2

Open the GitHub integration

Find the GitHub card and click it.
3

Install the GitHub App

Click Connect. You are redirected to GitHub where you install the Arca GitHub App. Choose the organization or account, then select which repositories to grant access to (you can grant access to all repositories or only specific ones).
4

Return to Arca

After installation, GitHub redirects you back to Arca. The connection is now active and the integration page shows a connected status.
5

Select a repository and list

In the integration settings, choose the Repository you want to link with the current Arca workspace and the Arca list where synced issues should land. These selections are required before any sync features work.
6

Enable features and save

Turn on Issues sync and Magic words as needed, then click Save configuration.

​
Issues sync

Issues sync imports GitHub issues into Arca as tasks and keeps them updated as things change on GitHub.

​
Enable issues sync

In the integration settings, turn on Issues sync and select a Sync mode (see below), then save.

​
Sync modes

GitHub is treated as the source of truth. This mode does the following:
  • Open GitHub issues are imported into the linked Arca list as tasks.
  • When a GitHub issue is closed, its linked Arca task status is automatically moved to the first completed status in your workspace.
  • Changes made to Arca tasks are not reflected back in GitHub.

​
Initial sync

An initial sync runs automatically (in the background, without blocking your workflow) whenever:
  • Issues sync is turned on for the first time.
  • Issues sync is already on and you change the repository.
  • Issues sync is already on and you change the target list.
During initial sync, Arca fetches all open issues from the GitHub repository (excluding pull requests) and creates tasks for any that are not already linked. If two-way mode is selected, Arca also exports all unlinked tasks from the configured list to GitHub.
Issues that already have a mapping in Arca are always skipped to prevent duplicates.

​
What gets imported

When a GitHub issue is imported, Arca creates a task with the following field mapping:
Arca task fieldValue
TitleGitHub issue title
DescriptionGitHub issue body (plain text and Markdown preserved)
StatusFirst pending status in your workspace
PriorityNone
ReporterThe workspace owner
ListThe configured Arca list
GitHub labels, assignees, and milestones are not imported into Arca fields at this time.
Arca does not modify or close issues on GitHub when you change a task’s status in Arca. Changes flow from GitHub to Arca, not the other way around for status updates, except when two-way mode exports initial tasks.

​
When a GitHub issue is closed

When a GitHub issue is closed, the linked Arca task status is updated to the first completed status in your workspace. The task’s timeline and subscribers are updated in real time, no page refresh needed.

​
When a GitHub issue is reopened

When a GitHub issue is reopened, the linked Arca task status is automatically moved back to the first pending status in your workspace, the same status assigned when the task was originally imported. This happens in real time via webhooks and requires no manual action. The reopen only takes effect if the task is currently in a completed status category. If the task was already moved to an in_progress status category before the reopen event arrived, its status is left unchanged.

​
When a GitHub issue title changes

In two-way mode, renaming a GitHub issue title updates the linked Arca task title automatically. This works in real time via GitHub webhooks.

​
When a GitHub issue description changes

In two-way mode, editing the body of a GitHub issue also updates the linked Arca task description automatically. GitHub issue bodies are written in Markdown; Arca converts them to rich text so they display correctly in the task editor.

​
When an Arca task description changes

In two-way mode, editing the description of a linked task in Arca pushes the updated content to the corresponding GitHub issue body. The description is converted from Arca’s rich text format to Markdown before being sent to GitHub so that formatting (headings, lists, code blocks, task checklists, bold, italic, and links) is preserved correctly.
Description sync only works in two-way mode. In one-way (From GitHub) mode, descriptions flow from GitHub into Arca during import but subsequent edits on either side are not synced.

​
Magic words

Magic words let developers reference and update Arca tasks directly from commit messages. When a commit is pushed to the linked repository, Arca scans the message for recognized keywords followed by a task identifier and performs the corresponding action.

​
Enable magic words

In the integration settings, turn on Magic words and save.

​
Task identifier format

Every Arca task has an identifier in the format WORKSPACE-NUMBER, for example MYAPP-42. The workspace part is the slug of your workspace, and the number is the task’s sequential number. You can copy the identifier from the task context menu (Copy Full ID button). Identifiers are case-insensitive in commit messages.

​
Closing keywords

The following keywords, when followed by a task identifier, mark the task as completed by moving it to the first completed status in your workspace: 
fix  fixes  fixed
close  closes  closed
resolve  resolves  resolved
Example commit messages: 
fix MYAPP-42
Closes myapp-7
resolved MYAPP-55: updated the payment flow
When a matching keyword is found, Arca:
  1. Moves the task to the first completed status in your workspace.
  2. Sends an in-app notification to all task subscribers (status changed).
  3. Updates the task in real time for everyone currently viewing it.
The action is skipped if the task is already in a completed status category.

​
Part of keyword

The Part of keyword followed by a task identifier logs a relationship between the commit and the task. Example: 
refactor auth helper, Part of MYAPP-99
This does not change the task’s status, priority, or any other field. It is intended for traceability and does not yet trigger a visible action in the Arca UI.
Magic words work on any commit pushed to the linked repository, regardless of the branch. Make sure your commit messages follow the KEYWORD IDENTIFIER pattern exactly.Extra text before or after the pattern is allowed.

​
Branch name generation

Any workspace member can copy the suggested Git branch name for a task. Open a task and look for the Copy branch name option. The format is controlled by the Branch naming style setting in the integration configuration:
StyleFormatExample
Title and identifier (default){title-slug}-{workspace}-{number}fix-login-bug-myapp-42
Identifier and title{workspace}-{number}-{title-slug}myapp-42-fix-login-bug
Identifier only{workspace}-{number}myapp-42
The title is automatically slugified (lowercase; special characters replaced with -; limited to 60 characters). You can change the style at any time in the integration settings without affecting existing branches.

​
Disconnect GitHub

To remove the GitHub integration from your workspace:
  1. Go to Settings → Integrations → GitHub.
  2. Click Disconnect.
  3. Confirm the action.
Disconnecting removes all configuration including the linked repository, the target list, and all feature toggles. Existing Arca tasks that were imported from GitHub remain in your workspace, they are not deleted. The GitHub App installation on your GitHub organization is not uninstalled automatically, you can remove it from GitHub → Settings → Applications if you no longer need it.
Only Admins and Owners can disconnect the GitHub integration. Disconnecting affects the entire workspace and stops all sync and magic word processing immediately.

​
Troubleshooting

Check the following:
  • Issues sync is enabled and the configuration has been saved.
  • A repository and a target list are both selected.
  • The GitHub App has access to the repository. Go to GitHub → Settings → Applications → Arca and confirm the repository is listed under repository access.
If the configuration looks correct, try changing the target list to a different one and saving, then back to the original list and saving again to re-trigger the initial sync.
Make sure:
  • Magic words is enabled in the integration settings and saved.
  • The commit message uses one of the recognized keywords (fix, close, resolve, and their variants).
  • The task identifier format is correct: WORKSPACE-NUMBER where WORKSPACE is your workspace slug. Check the slug in Settings → Workspace.
  • The repository being pushed to is the one selected in the integration settings.
Note: magic words are not retroactive. Only commits pushed after the feature is enabled are processed.
If the task was completed via a closing commit or by closing the linked GitHub issue, reopening the GitHub issue will automatically move the Arca task back to pending, which allows the next closing commit to fire correctly, no manual action needed.If the task was completed without a linked GitHub issue (for example by manual status change in Arca), reopen it by reopening the corresponding GitHub issue or by changing its status manually in Arca.
The initial export runs in the background after you save the configuration. Wait a moment and then refresh GitHub. If issues still do not appear, check that the repository has Issues enabled (GitHub repository settings) and that the Arca GitHub App has write permission to the repository.
Changing the repository triggers a new initial sync against the new repository. Tasks already imported from the old repository remain in Arca but they are no longer linked to any active GitHub issue. Future webhook events from the old repository are ignored because the integration now points to the new repository.