GitHub Integration

GitHub Integration Overview

SDA currently supports integration with GitHub, allowing you to link your GitHub account and repositories directly to the platform. Through this connection, GitHub can serve as a local, version-controlled repository that stays synchronized with the SDA repository. Administrators can configure authentication, select repositories, and manage synchronization settings—enabling teams to maintain familiar GitHub workflows while benefiting from SDA’s centralized project management and automation capabilities.

Key Features of Integration

Integrating GitHub with SDA offers several benefits:

  • Streamlined Workflow: Seamlessly integrates GitHub’s robust version control with SDA’s PLC project versioning and PLC management features, enhancing team collaboration.

  • Centralized Management: Combine code repositories and PLC project management in a single platform to simplify administration and access control.

  • Automation and Deployment: Utilize SDA’s Pipelines for automated deployment features to streamline project releases directly from GitHub repositories.

  • Real-time Collaboration: Instant updates and changes are synchronized, ensuring all team members are working with the latest project version.

By integrating GitHub with SDA, your team can enhance productivity and project efficiency.

How to Connect SDA to GitHub

Configure GitHub for SDA Integration

  1. Log into GitHub: Ensure you have your GitHub credentials ready.

  2. Generate Personal Access Token: To provide SDA access, go to Developer settings, choose Personal access tokens, and create a new Fine-grained token. Set the permissions to Contents and Metadata for the repositories you wish to share.

  3. Copy Token: Store your token securely, as it will be used during the authentication process in SDA.

By following these preparation steps, your GitHub account will be ready for integration with SDA, allowing you to benefit from enhanced collaboration and project management.

Connecting Your GitHub With your SDA Account

To connect your SDA platform to GitHub, follow these steps:

  1. Access Settings: Navigate to the SDA platform and go to the 'General Settings' section.

  2. Create a new integration: Navigates to the Integrations section and adds a new integration by clicking on Add Integration.

  3. Authenticate GitHub Account: On the Add Integration window, enter the integration name and paste your GitHub access token.

Configure Webhooks for Automatic Updates

To enable automatic updates and ensure SDA is promptly informed about changes, you need to set up webhooks within your GitHub repositories effectively. Here’s how you can configure this feature:

  1. Access Repository Settings:

    • Begin by navigating to your GitHub repository.

    • Click on the "Settings" tab, which is typically located at the far right of the repository navigation bar.

  2. Locate the Webhooks Section:

    • Once in the settings, scroll down or look for the "Webhooks" option in the left-hand menu.

    • Click on "Webhooks" to manage and add new hooks.

  3. Create a New Webhook:

    • Press the "Add webhook" button to initiate the setup of a new webhook.

    • You will be prompted to enter a Payload URL, which is the endpoint where you wish to send HTTP POST requests when certain events happen. You can copy this value from your newly created SDASDA newly created integration.

  4. Configure Webhook Payload:

    • Under "Content type," choose application/json to ensure you receive data in a structured format.

    • Set up the secret key to secure your webhook against unauthorized access. You can copy this value from your SDA integration.

  5. Select Events:

    • Choose the "Just push events" option.

  6. Finalize Setup:

    • Double-check the configurations.

    • Click "Add webhook" to finalize and activate the webhook.

Once configured, your webhook will send updates to SDA.

Linking a Repository to an SDA Project

To link a repository to an SDA project, follow these steps:

  1. Access the Project Section: Open your SDA project.

  2. Access Project Edit Menu: Select the three dots in the top-right corner of the project page.

  3. Connect Repository:

    • Select 'Link to Repository'.

    • Choose a repository from the list to link.

  4. Confirmation: Verify the setup is functioning. If successful, you will see a GitHub icon in the project details header.

Preparing Your Repository for SDA Integration

Now that your repository is configured and connected, prepare its content so that SDA can understand how to handle it.

GitHub Repository Folder Structure

The SDA integration process requires each repository to house a single PLC project. Although the folder structure can be customized by the user, the root folder must contain a config.sda.json file. This file specifies the vendor and IDE version of the PLC project.

Configuration File Schema

  • schema_version: Indicates the version of the configuration file schema. The default value is 1.0.0, which supports future enhancements and maintains backward compatibility.

  • vendor: Specifies the PLC project vendor. Accepted values are:

    • siemens

    • rockwell

  • ide_version: Specifies the version of the PLC project. It follows the format {major}.{minor}.{patch}. For example, Siemens TIA V17 translates to 17.0.0, and Rockwell V37 is represented as 37.0.0.

  • project_path: This field specifies the correct path to the PLC project within your repository. It uses a relative path format starting from the root folder of the repository. This means that, when setting the project_path, you should not include the root directory itself in your path. Instead, provide the path segments leading to the specific PLC project folder. For example, if your PLC project is located in a folder named Projects which resides directly in the root directory, and further inside Projects there is a PLC1 folder where the desired project files are kept, your project_path would be ./Projects/PLC1/MySiemensPLCProject.zap17. This setup helps in maintaining consistent file referencing throughout different environments where the repository may be used, as it does not rely on absolute paths that can vary between systems.

    • Siemens PLC project: For managing Siemens PLC projects, we offer support for both the compressed .zap file and the uncompressed folder structure that includes .ap files. Here's how you can work with these formats:

      • Compressed File: If you have your project in a compressed format, you can use the .zap file directly. This is useful for easily transferring projects as a single package. For instance, use the file path:

        • ./Projects/PLC1/MySiemensPLCProject.zap17

        • ./MySiemensPLCProject.zap19

      • Uncompressed Folder: Alternatively, you can work with an uncompressed folder that contains the .ap files. This setup allows for easier access to individual project components, which can be beneficial during development or debugging. Use the following path to access your project:

        • ./Projects/PLC1/MySiemensPLCProject/MySiemensPLCProject.ap17

        • ./MySiemensPLCProject/MySiemensPLCProject.ap19

    • Rockwell PLC Project: For Rockwell PLC projects, the process is streamlined. These projects are encapsulated in a single .ACD file, simplifying project management and sharing. Follow these steps to access your Rockwell PLC project:

      • ACD File: The .ACD file encompasses all the necessary project data. Simply point to the file:

        • ./Projects/PLC1/MyRockwellPLCProject.ACD

        • ./MyRockwellPLCProject.ACD

Example of a config.sda.json File

{
    "schema_version": "1.0.0",
    "vendor": "siemens",
    "ide_version": "17.0.0",
    "project_path": "./SimulatedAxisSinamicsV90_S71212C.zap17"
}

Upon successful completion, your repository will be linked to the SDA project, facilitating better collaboration and project management. From now on, every new commit pushed to your GitHub repository will create a corresponding project version in your SDA project.

PreviousIntegrationsNextTag Management

Last updated