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

> Discover how the action maps GitHub usernames to Asana user GIDs using a simple YAML configuration file. Learn the process for seamless integration.

- Repository: [Keita Kitamura/github-asana-request-review-action](https://github.com/keitap/github-asana-request-review-action)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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`](https://github.com/keitap/github-asana-request-review-action/blob/main/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:

```go
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`](https://github.com/keitap/github-asana-request-review-action/blob/main/testdata/config_v1.0.yml):

```yaml
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:

```go
// 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`](https://github.com/keitap/github-asana-request-review-action/blob/main/handler.go), the action consults this mapping when processing GitHub review request events. The handler isolates the lookup logic in a dedicated method:

```go
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`](https://github.com/keitap/github-asana-request-review-action/blob/main/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`](https://github.com/keitap/github-asana-request-review-action/blob/main/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`](https://github.com/keitap/github-asana-request-review-action/blob/main/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`](https://github.com/keitap/github-asana-request-review-action/blob/main/testdata/config_v1.0.yml) in the source repository demonstrates the expected format and structure.