GitHubIssue

The GitHubIssue component acts as a bridge between the Nappai automation system and GitHub’s Issue Tracking system. It allows you to create, view, edit, and manage issues (bugs, features, or tasks) within your GitHub repositories. Whether you need to automatically create new bug reports, add comments to existing discussions, or retrieve a list of open tasks, this component simplifies the interaction with GitHub’s API.

It is designed to handle complex data management by allowing you to connect outputs from other components (like data extractors or AI assistants) directly into issue fields, making it easy to automate workflows such as “Detect a bug and create a GitHub issue” or “Monitor issues and notify the team.”

How it Works

This component interacts with GitHub via its public API. When you configure the component, it authenticates with GitHub using a secure token and then performs specific actions based on the Operation you select.

Internally, the component handles the communication with GitHub’s servers to ensure that issues are created, updated, or retrieved accurately. It supports advanced features like Mapping Mode, which allows you to dynamically pull data from other parts of your Nappai workflow to fill in issue titles, bodies, or labels, rather than just typing static text.

Connection & Credentials

This component requires configuring a credential in the Nappai panel before interacting with the external service:

1. Go to the Credentials section in your Nappai panel.
2. Create a new credential of the type GitHub API.
3. In the credential setup, provide your GitHub Personal Access Token. You can generate this token in your GitHub account settings under Developer Settings. Ensure the token has the repo scope to access private repositories or public_repo for public ones.
4. In your workflow, select the saved credential in the Credential input field of this component.

Operations

This component offers several operations that you can select based on what you need to do. You can only use one operation at a time:

• Get: Retrieve the detailed information of a specific issue by its number.
• List: Retrieve a list of issues from a repository, allowing you to filter by state (open/closed), labels, or assignees.
• Create: Create a new issue in a repository with a title and body.
• Edit: Modify an existing issue by updating its title, body, labels, or state.
• Create Comment: Add a new comment to an existing issue.
• Lock: Prevent further comments or changes to an issue (useful for resolving or archiving discussions).
• Unlock: Allow further comments and changes to a previously locked issue.
• Delete: Permanently remove an issue from the repository.

To use the component, first select the operation you need in the “Operation” field.

Inputs

Mapping Mode

This component has a special mode called “Mapping Mode”. When you enable this mode using the toggle switch, an additional input called “Mapping Data” is activated, and each input field offers you three different ways to provide data:

• Fixed: You type the value directly into the field.
• Mapped: You connect the output of another component to use its result as the value.
• Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

• Operation: Select the issue operation to perform.
  • Visible in: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete
• Repository: Select a repository. The list populates after selecting a credential.
  • Visible in: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete
• Repository Input Type: Select the input type for the repository.
  • Visible in: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete
• Repository ID: Pass the repository name in format ‘owner/repo’ (e.g., ‘octocat/Hello-World’). Overrides the dropdown selection.
  • Visible in: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete
• Issue Number: The number of the issue to get, edit, comment on, lock, or delete.
  • Visible in: Get, Edit, Create Comment, Lock, Unlock, Delete
• Issue Title: The title of the issue.
  • Visible in: Create, Edit
• Issue Body: The main content for the issue or the text for the comment.
  • Visible in: Create, Edit
• Labels: Comma-separated list of labels to assign or filter by.
  • Visible in: List, Create, Edit
• State: Filter issues by their state.
  • Visible in: List, Edit
• Limit: Maximum number of items to return (max 1000).
  • Visible in: List
• Comment Body: The text for the comment.
  • Visible in: Create Comment
• Mapping Mode: Enable mapping mode to process multiple data records in batch
  • Visible in: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete
• Tool Name: The name of the tool that will be used when this component is connected as a tool. This name will be displayed to the agent when it selects tools to use.
  • Visible in: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete
• Tool Description: A detailed description of what this tool does. This description will help the agent understand when and how to use this tool effectively.
  • Visible in: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete
• Tools arguments metadata: Defines the arguments metadata for the tools.
  • Visible in: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete

Outputs

After the component completes its operation, it produces the following outputs which you can connect to other parts of your workflow:

• Data: The primary result of the operation. For Get, Edit, Create, etc., this is the issue object. For List, this is the list of issues.
• Tool: An output formatted for use in AI Agent toolkits, allowing the agent to call this component directly during reasoning.

Output Data Example (JSON)

json { “id”: 12345678, “number”: 42, “title”: “Fix login button alignment”, “state”: “open”, “labels”: [ { “name”: “bug”, “color”: “d73a4a” } ], “assignees”: [], “comments”: 3, “created_at”: “2023-10-25T14:30:00Z”, “body”: “The login button is misaligned on mobile devices…” }

Connectivity

This component is typically used in workflows involving project management, bug tracking, or automated reporting.

• Connection from Data Sources: Often connected to data extraction components (e.g., from a CRM or a log file analyzer) to feed data into the Issue Body or Labels fields.
• Connection to Communication Tools: The output of the Get or List operations can be connected to Email or Slack notification components to alert team members about new issues.
• AI Agent Integration: The Tool output is designed to be connected to AI Agent nodes, allowing the agent to autonomously check issue statuses or create issues based on natural language instructions.

Usage Example

Scenario: Automating Bug Reporting

1. Trigger: A script detects a critical error in your application logs.
2. Action: Connect the log output to the GitHubIssue component.
3. Configuration:
   • Set Operation to Create.
   • Set Repository to your project repo.
   • Set Issue Title to “Critical Error: [Log Message]”.
   • Map the Issue Body to the detailed error log from the previous step.
4. Result: A new GitHub issue is automatically created with the error details, tagged and assigned as defined in your configuration.

Important Notes

🔒 Security Keep Tokens Secret You must provide a valid GitHub personal access token with the appropriate scopes (e.g., repo, issues) for the component to access your repository. Never expose your GitHub token in public repositories or shared workflows; store it securely and use environment variables or secrets managers.

⚠️ Limitation Development Version This component is marked as in development, so some features might not work reliably or could change in future releases. Please check the official GitHub documentation for any changes to the API structure.

📋 Requirement GitHub API Token Needed You must configure the GitHub API credential before using this component. Without a valid token, operations on private repositories will fail.

💡 Best Practice Use Read-Only Tokens for Listing When only reading issues (e.g., using the List operation), use a token with read-only scopes to reduce the risk of accidental modifications or security exposure.

ℹ️ Behavior List Includes All Issue States The List operation returns all issues (open, closed, and pull requests) unless you explicitly filter by state or labels in the input parameters. Use the State input to narrow down your results.

⚙️ Configuration Input Parameters Must Match Base Definition Because the component inherits inputs from the base class, ensure that you provide the required fields (e.g., repository owner, repo name, issue number) exactly as defined in the base documentation.

Tips and Best Practices

• Always use the Mapping Mode when possible to make your workflows dynamic rather than static.
• When creating issues, be specific in the Issue Body to help developers understand the context immediately.
• Use the Lock operation for issues that have been resolved but need to remain visible for historical context.
• If you are using the List operation to monitor progress, consider using the Limit input to prevent overwhelming your workflow with too many results.
• Remember that Labels should be comma-separated if you are typing them manually, or passed as a list if using Mapping Mode.

Security Considerations

• Token Storage: Never hardcode your GitHub Personal Access Token (PAT) in the workflow. Always use the Credential feature in Nappai to securely store and inject the token.
• Least Privilege Principle: When generating your GitHub Token, only request the scopes you actually need. For example, if you only need to read issues, request public_repo scope rather than full repo access.
• Token Expiration: GitHub tokens may expire or be revoked. Regularly check your GitHub account settings to ensure your automation tokens are still valid.