How GitHub Usernames Are Mapped to Asana User GIDs in the Action Configuration

The action resolves GitHub usernames to Asana user GIDs via a YAML configuration file that unmarshals into a map[GithubLogin]AsanaGID where keys are GitHub logins and values are Asana global IDs.

The keitap/github-asana-request-review-action synchronizes GitHub pull request reviewers with Asana tasks by translating GitHub identities into Asana-assignable entities. Understanding how GitHub usernames are mapped to Asana user GIDs is essential for configuring the action, as this mapping is defined in a YAML file and loaded into a strongly-typed Go struct at runtime.

Configuration Schema in config.go

In config.go (lines 11-15), the Config struct declares an Accounts field that stores the username-to-GID mapping. The code defines type aliases for clarity:

type GithubLogin = string
type AsanaGID = string

type Config struct {
    DueDate  int                      `yaml:"due_date"`
    Holidays map[string]bool          `yaml:"holidays"`
    Accounts map[GithubLogin]AsanaGID `yaml:"accounts"`
}

The Accounts field uses these type aliases to create a clear contract: GitHub logins map directly to Asana GIDs without nested structures or intermediate lookup tables.

YAML Configuration Format

The mapping is specified in the YAML configuration file under the accounts key. Each entry consists of a GitHub username followed by its corresponding Asana GID string, as shown in testdata/config_v1.0.yml:

accounts:
  user1: "123"        # GitHub "user1" maps to Asana GID 123

  user2: "456"        # GitHub "user2" maps to Asana GID 456

  user3: "789"        # GitHub "user3" maps to Asana GID 789

According to the source code, the unmarshalled data populates the Accounts map exactly as written in YAML, with the GitHub login serving as the map key and the numeric or string GID as the value.

Loading and Resolving Mappings at Runtime

The LoadConfig function reads the YAML configuration and unmarshals it into the Config struct. You can then resolve a GitHub username to an Asana GID by accessing the map directly:

// Load configuration from YAML bytes
cfg, err := githubasana.LoadConfig(data)
if err != nil {
    log.Fatalf("failed to load config: %v", err)
}

// Resolve a GitHub username to Asana GID
githubUser := "user2"
asanaGID, ok := cfg.Accounts[githubUser]
if !ok {
    log.Printf("no Asana mapping for GitHub user %s", githubUser)
} else {
    log.Printf("GitHub user %s → Asana GID %s", githubUser, asanaGID)
}

If the username exists in the map, the lookup returns the corresponding GID and true; otherwise, it returns false, signaling that no mapping exists for that reviewer.

Implementation in Event Handlers

In handler.go, the action consults this mapping when processing GitHub review request events. The handler isolates the lookup logic in a dedicated method:

func (h *handler) mapReviewerToAsana(githubLogin string) (asana.GID, bool) {
    gid, found := h.cfg.Accounts[githubLogin]
    return gid, found
}

This pattern ensures that every review request triggers a direct lookup in the Accounts map, translating the GitHub event's requested_reviewer.login into the Asana user GID required for task assignment.

Summary

• Type-safe mapping: The Config struct in config.go uses map[GithubLogin]AsanaGID to enforce clear typing between platforms.
• YAML-driven configuration: The accounts section in the YAML file defines simple key-value pairs linking GitHub usernames to Asana GIDs.
• Runtime resolution: LoadConfig unmarshals the YAML, and handlers access cfg.Accounts[username] to resolve identities during event processing.
• Fail-safe lookups: The map access returns a boolean ok value, allowing the action to handle unmapped users gracefully.

Frequently Asked Questions

What data structure holds the GitHub username to Asana GID mapping in the code?

The mapping is stored in a Go map field named Accounts within the Config struct, typed as map[GithubLogin]AsanaGID where both GithubLogin and AsanaGID are string aliases. This structure is defined in config.go (lines 11-15) and populated by unmarshalling the YAML configuration.

How do I add a new user to the GitHub-to-Asana mapping?

Add a new entry under the accounts key in your YAML configuration file, using the format github_username: asana_gid. For example, newdeveloper: "1205345678912345678" maps the GitHub user "newdeveloper" to the specified Asana GID. No code changes are required; restart the action to pick up the new configuration.

What happens if a GitHub reviewer is not listed in the accounts map?

If the GitHub username is absent from the Accounts map, the lookup returns false for the found boolean, as implemented in handler.go. The action treats this as an unmapped user and typically skips Asana assignment for that specific reviewer rather than failing the entire workflow.

Where is the configuration file usually located?

The action expects the YAML configuration file to be specified at runtime, often passed via the config input parameter or loaded from a default path in the repository. The example file testdata/config_v1.0.yml in the source repository demonstrates the expected format and structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}