File

The File component allows you to automate interactions with files stored in GitHub repositories directly from your Nappai dashboard. It acts as a bridge between your automation workflows and the GitHub API, enabling you to manage code, configuration files, or documentation without writing complex scripts.

This component is designed to be intuitive, allowing you to perform common file operations such as reading text content, creating new files, updating existing ones, or removing files from a specific branch. It supports dynamic data handling through “Mapping Mode,” making it flexible for workflows that involve batch processing or dynamic repository selection.

How it Works

This component communicates with the GitHub REST API using a secure connection (credential). When you configure the component, you specify which repository and branch you want to interact with. The specific action performed depends on the Operation you select.

For example, if you choose the Get operation, the component fetches the content of a file and returns it for further processing in your workflow. If you choose Create or Edit, it sends new or updated content to GitHub, generating a new “commit” (a record of change) with a message you provide.

The component automatically handles the authentication required to access your GitHub account securely. It ensures that you only interact with repositories you have permission to access.

Connection & Credentials

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

1. Go to the Credentials section in your Nappai panel.
2. Create a new credential of the type GitHub API and fill in the required fields (specifically, your GitHub Personal Access Token with repo scope).
3. In your workflow, select the saved credential in the Credential input field of this node.

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: Reads the content of a specific file from the repository and returns it as data.
• List Files: Retrieves a list of files within a specified directory path.
• Create: Adds a new file to the repository with the specified content.
• Edit: Updates the content of an existing file in the repository.
• Delete: Removes a file from the specified branch in 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:

• Credential: The secure token used to authenticate with GitHub.

  • Visible in: Get, List Files, Create, Edit, Delete

• Operation: Select the file operation to perform.

  • Visible in: Get, List Files, Create, Edit, Delete

• Repository: Select a repository. The list populates after selecting a credential.

  • Visible in: Get, List Files, Create, Edit, Delete

• Repository Input Type: Select the input type for the repository.

  • Visible in: Get, List Files, Create, Edit, Delete

• Repository ID: Pass the repository name dynamically (e.g., ‘owner/repo’). Overrides the dropdown selection.

  • Visible in: Get, List Files, Create, Edit, Delete

• Branch: Branch name (default: main).

  • Visible in: Get, List Files, Create, Edit, Delete

• File Path: Path to the file relative to the repository root (e.g., ‘src/data/config.json’). Do not start with a slash (/).

  • Visible in: Get, List Files, Create, Edit, Delete

• File Content: The content for the file. Accepts text, Data objects, or file paths.

  • Visible in: Create, Edit

• Commit Message: The commit message for the change.

  • Visible in: Create, Edit

• Directory Path: Path to directory (leave empty for root). Used in List Files operation.

  • Visible in: List Files

• Limit: Maximum number of items to return (max 1000).

  • Visible in: List Files

• 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 Files, Create, Edit, 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 Files, Create, Edit, Delete

• Tools arguments metadata: Defines the arguments metadata for the tools.

  • Visible in: Get, List Files, Create, Edit, Delete

• Mapping Mode: Enable mapping mode to process multiple data records in batch.

  • Visible in: Get, List Files, Create, Edit, Delete

Outputs

The component produces output data that you can pass to other components in your workflow for further processing.

Output Data Example (JSON)

When you use operations like Get, Create, Edit, or Delete, the component returns structured data about the operation. Here is an example of what the output might look like for a Get operation: json { “content”: ”# Hello World\nThis is a sample file.”, “sha”: “a1b2c3d4e5f6…”, “status”: “success”, “commit_id”: “9876543210…”, “file_url”: “https://github.com/username/repo/blob/main/readme.md” }

For List Files, the output would contain an array of file metadata. For Create and Edit, it confirms the successful update with a new SHA and commit ID.

Connectivity

This component is typically connected to:

• Previous Components: Data sources that provide the file content (for Create/Edit) or specify the file path/branch (for all operations). In Mapping Mode, it can be connected to a loop or batch data processor.
• Next Components: Action components that process the retrieved data (e.g., a text analyzer, a database saver, or an email sender). For Create/Edit/Delete, it connects to components that handle the confirmation or logging of the change.

Logical flow: [Data Source] -> [GitHub File Component] -> [Data Processor/Action]

Usage Example

Scenario: Automating Documentation Updates

Imagine you want to update a README.md file in your GitHub repository automatically whenever a new report is generated.

1. Setup: Configure the Credential with your GitHub token.
2. Operation: Select Edit.
3. Repository: Select your target repository (e.g., my-company/docs).
4. File Path: Enter docs/README.md.
5. File Content: Use the output from a previous component that generates the latest report summary.
6. Commit Message: Type “Auto-update README with latest report”.
7. Execute: Run the workflow. The component will fetch the current version of the file (using SHA validation), update the content, and push the change to the main branch.

Important Notes

🔒 GitHub Personal Access Token Needed 🔴 You must supply a GitHub Personal Access Token (PAT) with the “repo” scope to authenticate the component. Without a valid token, the component cannot access or modify files in the repository.

🔒 Repository Access Must Be Granted 🔴 The PAT must have read/write permissions for the target repository. Verify that the token owner is a collaborator or has the appropriate rights to create, edit, or delete files.

🔒 Keep Your Token Secret 🔴 Never hard‑code the PAT in source files or share it in logs. Store it in a secure environment variable or secret manager to prevent unauthorized access to your repository.

⚠️ Development Version – Unstable Behavior 🟡 The component is marked as “is_development = True”, meaning the API could change or contain bugs. Expect occasional failures or unexpected changes in behavior.

⚠️ GitHub API Rate Limits Apply 🟡 Frequent file operations may hit GitHub’s rate limits, causing temporary failures. If you plan many actions, add retry logic or space requests over time.

⚠️ Large File Size Restrictions 🟡 The GitHub API typically limits raw file uploads to about 100 MB. For larger files, consider using Git LFS or splitting the content into smaller parts.

💡 Use Descriptive Commit Messages 🟢 Each file operation creates a commit. Include clear, concise commit messages to help you track changes and collaborate with others.

💡 Specify Correct Branch and Path 🟢 Provide the exact branch name and file path to avoid accidental overwrites or deletions on the wrong branch. Double‑check path spelling and case sensitivity.

ℹ️ Delete Operation is Permanent 🟡 Deleting a file removes it from the repository history on the specified branch. If you need to recover the file, use Git history or a backup before executing delete.

⚙️ Avoid Leading Slashes in File Path 🟡 The component expects file paths without a leading slash (e.g., “docs/readme.md”, not “/docs/readme.md”). Leading slashes can cause the file not to be found or written.

Tips and Best Practices

• Always test your workflows on a temporary branch or a test repository before applying changes to production code.
• Use Mapping Mode when you need to update multiple files at once or process data from a list.
• Keep your Commit Messages descriptive to maintain a clear history of changes in your repository.
• Ensure your GitHub Personal Access Token has the necessary scopes (repo) to avoid permission errors.
• Be aware of GitHub’s rate limits if you are performing bulk operations; consider adding delays between calls if needed.

Security Considerations

• Credential Management: Never expose your GitHub Personal Access Token in public repositories or logs. Use Nappai’s secure credential storage.
• Scope Minimization: Grant only the minimum required permissions (e.g., repo for read/write access to your specific repositories) to your token.
• Token Rotation: Regularly rotate your PATs if possible, especially if you suspect any unauthorized access.
• Data Privacy: When editing files, ensure that sensitive data is not accidentally written to public repositories.