# Data Processing Addendum Source: https://docs.blacksmith.sh/about/data-processing-addendum **Last Updated:** June 15, 2026 This Blacksmith Data Processing Addendum ("***DPA***") is incorporated by reference into the Services Agreement (defined below) between you ("***Customer***" or "***You***") and Blacksmith Software, Inc. ("***Blacksmith***"). This DPA sets out the terms that apply when Personal Data (defined below) from Customer is processed by Blacksmith under the Services Agreement. Capitalized terms used but not defined in this DPA shall have the meanings ascribed to them in the Services Agreement. ## 1. Definitions **a. "Applicable Data Protection Laws"** means any applicable laws, statutes or regulations as may be amended, extended, re-enacted from time to time, or any successor laws which relate to Personal Data including: (i) the GDPR and any European Economic Area (the "***EEA***") Member State laws implementing the GDPR; (ii) the California Consumer Privacy Act of 2018 (the "***CCPA***"), as amended by the California Privacy Rights Act of 2020 (the "***CPRA***"), and the California Attorney General Regulations thereof; (iii) the United Kingdom (the "***UK***") Data Protection Act 2018, as amended, and the GDPR, as incorporated into UK law (the "***UK GDPR***"); (iv) the Swiss Federal Act on Data Protection of 25 September 2020 and its corresponding ordinances, as in force from September 1, 2023 (the "***Swiss FADP***"), and (v) any other applicable data protection or privacy law to which the Processing under this DPA is subject, in each case to the extent applicable to the respective Party in its role under this DPA. **b. "Data Breach"** means a confirmed accidental or unlawful destruction, loss, alteration, unauthorized disclosure of, or access to Customer's Personal Data. **c. "GDPR"** means the Regulation (EU) 2016/679 of the European Parliament and of the Council of April 27, 2016 and Regulation (EU) 2016/679 as transposed into national law of the United Kingdom by the UK European Union (Withdrawal) Act 2018 and amended by the UK Data Protection, Privacy and Electronic Communications (Amendments etc.) (EU Exit) Regulations 2019 (as may be amended from time to time). **d. "Personal Data"** has the meaning set out in Article 4(1) of the GDPR and, to the extent applicable, the equivalent term under any other Applicable Data Protection Law, in each case where Processed by Blacksmith under this DPA. **e. "Process", "Processing", "Processor", and "Controller"** shall have the meaning as defined under GDPR and include equivalent terms in CCPA and CPRA, in each case as applicable to the Services. **f. "Restricted Transfer(s)"** means a transfer of Personal Data from the EEA, the UK or Switzerland to a country that has not received an adequacy decision from the European Commission or the UK or Swiss authorities. **g. "Service(s)"** means the software and services provided under the Services Agreement. **h. "Standard Contractual Clauses (SCCs)"** means (i) where the GDPR applies, the contractual clauses annexed to the European Commission's Implementing Decision 2021/914 of 4 June 2021 available at [https://eur-lex.europa.eu/eli/dec\_impl/2021/914/oj](https://eur-lex.europa.eu/eli/dec_impl/2021/914/oj) (the "***EU SCCs***"); (ii) where the UK GDPR applies, the International Data Transfer Addendum issued by the United Kingdom's Information Commissioner's Office to the EU Commission's Standard Contractual Clauses available at [https://ico.org.uk/media/for-organisations/documents/4019539/international-datatransfer-addendum.pdf](https://ico.org.uk/media/for-organisations/documents/4019539/international-datatransfer-addendum.pdf) (the "***UK SCCs***"); and (iii) where the Swiss FADP applies, those clauses in Section 15.d of this DPA (the "***Switzerland Clauses***"). **i. "Sub-processor(s)"** means any third-party Processor engaged by Blacksmith to Process Personal Data in order to provide the Services to Customer under the Services Agreement. **j. "Services Agreement"** shall mean Blacksmith's standard terms with respect to its Services generally made available at: [https://docs.blacksmith.sh/about/terms-of-service](https://docs.blacksmith.sh/about/terms-of-service) or such other agreement (e.g. Blacksmith Master Services Agreement) as agreed to between the parties in writing, governing the use and delivery of Services. ## 2. Scope and Order of Precedence This DPA applies when Blacksmith Processes Customer Personal Data in the provision of the Services. In the event of any conflict or inconsistency between the terms of this DPA and any other terms in the Services Agreement, the terms of this DPA shall prevail. The terms of this DPA shall supersede any conflicting provisions with respect to the processing of Customer Personal Data. ## 3. Processing Roles **a. Roles.** You are the Controller of Customer Personal Data, and Blacksmith is the Processor of that data, unless: **i.** You are the Processor of the Customer Personal Data. In that case, Blacksmith is a Sub-processor; or **ii.** Blacksmith is an independent Controller processing Customer Personal Data for the purposes listed in Section 3.b of this DPA. **b. Blacksmith's Independent Processing of Data.** Blacksmith Processes some Customer Personal Data as an independent Controller. Blacksmith conducts such Processing in compliance with Applicable Data Protection Laws generally, and the GDPR specifically, and in a manner consistent with the [Blacksmith Privacy Policy](https://docs.blacksmith.sh/about/privacy-policy). Those purposes include: **i.** To manage the relationship with Customer, such as billing and licensing management, the creation of customer relationship accounts, and facilitating transactional notifications related to Services; **ii.** To conduct internal business operations; including auditing, tax compliance, accounting, and various financial reporting obligations; **iii.** To ensure Service security and integrity, such abuse and misuse detection, and fraud prevention; **iv.** To comply with legal or regulatory obligations; **v.** To create aggregated statistical data for purposes such as capacity planning, product improvement, and sales/marketing. ## 4. Processing of Customer Personal Data **a. Documented Instructions.** Where Blacksmith acts as a Processor, Blacksmith shall only Process Personal Data on behalf of Customer and only in accordance with documented instructions received from Customer. The parties agree that this DPA, the Services Agreement, any features and settings used in the Services, and any processing initiated by Customer's users in their use of the Services shall constitute Customer's documented instructions. **b. Compliance with Laws.** It is Customer responsibility to ensure that the Processing instructions comply with Applicable Data Protection Laws. Customer will ensure that processing Customer Personal Data in accordance with its instructions will not cause Blacksmith to violate any law or regulation, including Applicable Data Protection Laws. Blacksmith will inform Customer if it becomes aware, or reasonably believes, that Customer instructions violate any applicable law or regulation. **c. Disclosure of Customer Personal Data.** Blacksmith will not disclose or provide access to any Customer Personal Data to third parties unless instructed by Customer, or as described in this DPA, or required by law or compelled by the legal process. Requests by law enforcement for Customer Personal Data will be directed to Customer where possible and Blacksmith will contact Customer if disclosure of Customer Personal Data is compelled, unless legally prohibited from doing so. ## 5. Personnel Confidentiality Blacksmith will limit access to Customer Personal Data strictly to those who are required to access Customer Personal Data to perform obligations under the Services Agreement. Blacksmith shall impose appropriate contractual obligations upon its personnel to ensure the confidentiality of Customer Personal Data. ## 6. Security of Processing Blacksmith will implement and maintain appropriate technical and organizational measures and security safeguards as set out in Annex II to this DPA. ## 7. Security Incident Notification If Blacksmith confirms a Data Breach, Blacksmith shall: **a.** Inform Customer without unnecessary delay following such confirmation; **b.** Provide details regarding the Data Breach, as available, to facilitate Customer's compliance with notification obligations under Applicable Data Protection Laws; and **c.** Promptly initiate an inquiry into the incident and implement remediation to mitigate potential damage. Failed attempts or activities that leave Personal Data security intact are not considered a Data Breach. Customer must immediately alert Blacksmith to any suspected compromise of credentials or security events involving the Services. Any notification or action taken regarding a Data Breach under this Section does not constitute an acknowledgement by Blacksmith of any fault or liability with respect to the Data Breach. ## 8. Sub-processors **a. General Authorization.** Customer hereby authorizes Blacksmith to engage Sub-processors of our choosing. **b. Written Agreement.** Blacksmith will enter into written agreements with each Sub-processor that impose data protection obligations consistent with this DPA and remain liable to Customer where a Sub-processor fails to fulfill its data protection obligations. **c. Sub-processor List.** Blacksmith maintains an up-to-date list of Sub-processors, available at [https://docs.blacksmith.sh/about/sub-processors](https://docs.blacksmith.sh/about/sub-processors) which contains details about Sub-processor functions, the location of processing, and a mechanism for the Customer to subscribe to notification of new Sub-processors or replacement of existing Sub-processors. **d. Notification of Changes.** At least thirty (30) days before a new Sub-processor begins processing Customer Personal Data, Blacksmith will add such new Sub-processor to the Sub-processor list and, if Customer has subscribed to notifications, provide Customer with a written notice. **e. Objections to Sub-processors.** Customer may submit a written objection to Blacksmith's use of any new Sub-processor during the notification period, provided such objection is based on reasonable grounds relating to data protection. Upon receipt of such objection, the parties will engage in good faith discussions to identify a mutually acceptable resolution. Should a consensus not be reached prior to the conclusion of the 30 day notice period, Blacksmith reserves the right to engage the Sub-processor. In such circumstances, Customer's exclusive recourse is the termination of the relevant Services Agreement for the impacted Services via written notification to Blacksmith. ## 9. Data Subject Rights If Blacksmith, acting as a Processor, receives requests from data subjects concerning Customer, Blacksmith will notify Customer or advise the individual to contact Customer. Customer remains responsible for managing such requests under Applicable Data Protection Laws. Blacksmith shall provide reasonable assistance to Customer in fulfilling these obligations. Where Blacksmith acts as an independent Controller and receives such requests, Blacksmith will fulfill its duties in accordance with Applicable Data Protection Laws. ## 10. Impact Assessments and Consultations Considering the processing's specific nature, Blacksmith shall offer reasonable aid to Customer regarding data protection impact assessments or regulatory authority consultations necessitated by Applicable Data Protection Laws. ## 11. International Data Transfers Customer designates Blacksmith to execute the transfer of Customer Personal Data to the United States or any other jurisdiction where Blacksmith or its Sub-processors maintain operations, and to Process and store such data for the delivery of Services, contingent upon the protective measures established herein and elsewhere in this DPA. **a. Adequacy.** Customer agrees that Blacksmith may transfer Customer Personal Data outside the EEA, the United Kingdom, Switzerland, or other relevant geographic territory as necessary to provide the Services and to administer the Customer relationship. If Blacksmith transfers such data to a territory for which the European Commission, the UK Secretary of State / ICO, or the Swiss FDPIC has not issued an adequacy decision, Blacksmith will implement appropriate safeguards consistent with Applicable Data Protection Laws. **b. Adaptations.** A transfer of Personal Data from the EEA, the UK or Switzerland to a country that has not received an adequacy decision from the European Commission or the UK or Swiss authorities, Blacksmith will implement an adequate level of protection through the SCCs. **c. SCCs.** For the SCCs, all parties agree: **i. Ex-EAA Transfers.** **1. Module One (Controller to Controller).** Applies to Personal Data where Customer is a Controller and Blacksmith is an independent Controller. **2. Module Two (Controller to Processor).** Applies to Personal Data, where Customer is a Controller and Blacksmith Processes that data as a Processor. **3. Module Three (Processor to Sub-Processor).** Applies to Personal Data, where Customer is a Processor and Blacksmith Processes that data as a Sub-processor. **4. For each applicable Module, the following applies:** **i.** In Clause 7, the optional docking clause will apply; **ii.** Clause 9 applies to Modules Two and Three only. Where it applies, Option 2 applies, and the time period for prior notice of Sub-processor changes shall be as set out in Section 8 of this DPA; **iii.** In Clause 11, the optional language will not apply; **iv.** In Clause 17, Option 1 will apply, and the New EU SCCs will be governed by the law of the Netherlands; **v.** In Clause 18(b), disputes shall be resolved before the courts of the Netherlands. **ii. Ex-UK Transfers.** Regarding Personal Data governed by the UK GDPR, the UK SCCs shall be implemented and finalized as follows: **1.** Personal Data transfers are additionally governed by the SCCs, as modified by subsection (2) below; **2.** Tables 1 through 3 of the UK Addendum incorporate the information from the SCCs as finalized in Section 11.b of this DPA, with Table 4 set to "neither party"; **3.** The UK Addendum's effective date is the date of DPA execution. **iii. Ex-Switzerland Transfers.** With respect to Personal Data subject to the Swiss FADP, the EU SCCs shall be implemented pursuant to Section 11.c.(i)-(ii) of this DPA subject to the following adjustments: **1.** Any mention of "Directive 95/46/EC" or "Regulation (EU) 2016/679" within the EU SCCs shall be construed as a reference to the Swiss FADP; **2.** Terms such as "EU", "Union", "Member State", or "Member State law" shall be understood to denote Switzerland or Swiss law, as appropriate; and, **3.** References to the "competent supervisory authority" or "competent courts" shall be deemed to refer to the FDPIC or the relevant judicial bodies in Switzerland, unless the EU SCCs as adapted above are insufficient for the lawful transfer of Personal Data under the Swiss FADP, in which case the Swiss SCCs shall be incorporated by reference as an essential component of this DPA. In such instances, the applicable Annexes of the Swiss SCCs shall be completed using the data provided in Annexes I and II of this DPA. ## 12. Audits and Certifications **a. Certification Audits.** Blacksmith engages external auditors to validate the sufficiency of its security protocols, omitting the physical and environmental protections of third-party data centers used for Services delivery, as such controls are maintained by the respective third-party Sub-processors. This assessment: (i) shall occur no less than annually; (ii) shall be conducted pursuant to SOC 2 Report standards or equivalent alternative frameworks; (iii) shall be performed by independent security experts at Blacksmith's discretion and cost; and (iv) shall produce an audit report, which constitutes Blacksmith Confidential Information. Blacksmith makes its security compliance documentation, including the SOC 2 Type 2 audit report, available to customers upon request via our [trust center](https://trust.blacksmith.sh/). **b. Customer Audits.** Blacksmith facilitates remote self-service evaluations of its security framework by providing Customer access to the [trust center](https://trust.blacksmith.sh/). These resources include evidence of Blacksmith's policies and security safeguards, as well as the third-party reports referenced in Section 12.a. Blacksmith may decline to disclose information that would present a security risk to Blacksmith or its customers. **c. Feedback.** Following the remote self-service assessment, Customer is permitted to provide written findings to Blacksmith. Blacksmith shall, at its discretion, use commercially reasonable endeavors to address and integrate any proposed enhancements suggested by Customer. **d. Audit Rights Under SCCs.** If Blacksmith's role is that of a Processor and the self-service evaluations or third-party reports provided in Section 12 fail to satisfy Customer's audit obligations under Article 28 of the GDPR or the SCCs, Customer may solicit a supplementary audit. Prior to any such engagement, the parties shall mutually establish the audit's scope, schedule, duration, and associated costs. Blacksmith will grant access to relevant information to the extent necessary for the audit, excluding any third-party confidential information. Audits shall be performed by a third party accredited auditing firm during Blacksmith's standard business hours, upon at least thirty (30) days written notice, and adhering to strict confidentiality protocols. Customer shall bear all associated cost, including compensation for Blacksmith's time. Customer must disclose all findings and results of the audit to Blacksmith and all findings and results of such audit shall be considered Confidential Information of Blacksmith. Customer may not disclose such findings or the results to third parties. This provision does not alter the SCCs or infringe upon the rights of data subjects or regulatory authorities. ## 13. Return and Deletion of Customer Personal Data Following the termination of Services, provided Blacksmith is acting as a Processor, Blacksmith will, at Customer's election, return or delete all Customer Personal Data and destroy existing copies within thirty (30) days in accordance with its standard deletion and retention policies, unless applicable law requires continued storage. ## 14. CCPA and CPRA The following provisions shall govern where Blacksmith Processes Customer Personal Data subject to the CCPA or the CPRA: **a.** The parties acknowledge and agree that Blacksmith serves as a service provider (as such term is defined by the CCPA), and any transfer of Personal Data is conducted solely for legitimate business purposes and to enable the performance of Services; **b.** Save for CCPA-specified exclusions, Blacksmith covenants that it shall neither sell nor share Personal Data governed by the Services Agreement, according to the statutory meanings of "sell" and "share" within such law; **c.** Blacksmith shall refrain from the retention, use, or disclosure of Personal Data for any objectives outside of the specific business purposes delineated within this DPA and the Services Agreement, except as otherwise sanctioned by the CCPA; **d.** Blacksmith shall refrain from the use or disclosure of Personal Data beyond the scope of its immediate engagement with Customer; **e.** Blacksmith shall refrain from commingling Personal Data obtained via the Services Agreement or through Service delivery with data acquired from third parties or collected directly from California residents; provided, however, that Blacksmith may aggregate Personal Data as necessary to fulfill legitimate business purposes authorized under the CCPA or CPRA; and **f.** Blacksmith hereby confirms it understands the limitations prescribed within this section, and ensures compliance with such requirements. ## 15. Regulated Data Absent explicit and prior written authorization from Blacksmith, Customer shall refrain from submitting any Personal Data that: **a.** Concerns criminal history or offenses, or any information processed under the FBI's Criminal Justice Information Services Security Policy; **b.** Represents "protected health information" as defined by the Health Insurance Portability and Accountability Act of 1996 ("HIPAA") and its implementing regulations at 45 C.F.R. Parts 160 and 164; **c.** Was gathered during clinical trials or biomedical research governed by the Federal Policy for the Protection of Human Subjects; **d.** Is subject to any biometric privacy regulations, including data relating to physical, biological, or behavioral traits used for individual identification, whether processed individually or in combination with each other or other information, to establish individual identity. ## 16. Liability Subject to the maximum extent permitted by Applicable Data Protection Laws, the total aggregate liability of either party arising from or in connection with this DPA, regardless of the legal theory, shall be governed by the "Limitation of Liability" provision set forth in the Services Agreement. Any reference to a party's liability in the Services Agreement shall be construed as the combined liability under both the Services Agreement and this DPA. ## 17. Miscellaneous **a. Supersedes.** This DPA, inclusive of the SCCs, represents the final and complete understanding between the parties, and supersedes any previous arrangements or discussions concerning the Processing of Personal Data under this engagement. The obligations set forth in this DPA shall remain in effect notwithstanding the expiration or termination of the Services Agreement. **b. Updates.** Blacksmith reserves the right to modify the provisions of this DPA if such revisions are (i) mandated for adherence to Applicable Data Protection Laws, relevant regulations, or directives from a competent regulatory body; or (ii) do not result in a material reduction of the security measures or safeguards afforded to Personal Data herein. ## DPA Attachment 1: Annex I to the SCCs (EU/EEA) ### A. List of Parties Module One: Controller to Controller; Module Two: Controller to Processor; and Module Three: Processor to Processor. **Data exporter(s) for the above modules:** **Name and contact details:** as delineated in the Services Agreement. **Activities relevant to the data transferred under these Clauses:** as delineated in the Services Agreement. **Signature and date:** Annex I is considered finalized upon the initiation of data transfer or the execution of the Services Agreement, whichever occurs first. **Role:** Module One: Controller, Module Two: Controller, Module Three: Processor. **Data importer(s):** **Name and contact details:** as delineated in the Services Agreement. **Activities relevant to the data transferred under these Clauses:** as delineated in the Services Agreement. **Signature and date:** Annex I is considered finalized upon the initiation of data transfer or the execution of the Services Agreement, whichever occurs first. **Role:** Module One: Controller, Module Two: Processor, Module Three: Processor. ### B. Description of Transfer Module One: Controller to Controller; Module Two: Controller to Processor; and Module Three: Processor to Processor. **Categories of data subjects whose personal data is transferred:** The data subjects are determined by Customer through its use of the Service. Depending on that use, the Personal Data may concern the following categories of data subjects: * Customer employees, contractors, temporary workers, and other personnel (current, former, or prospective), including developers, operators, and administrators who use or configure the Service; * Customer account administrators and billing contacts (relevant to Account Data, for which Blacksmith acts as an independent Controller); * Customer own end users, customers, collaborators, and other natural persons whose personal data Customer or its personnel include in source code, repositories, build inputs, configuration, test data, logs, or other content processed through the Service; and * Any other individuals whose personal data is contained in Customer Personal Data that Customer elects to process using the Service. **Categories of personal data transferred:** The categories of Personal Data are determined and controlled by Customer through its use of the Service. Depending on that use, the personal data may include: * Basic personal data (for example name, username, email address); * Authentication data (for example usernames, password, security question); * Contact information (for example addresses, email); * Device identification; * Pseudonymous identifiers; * Any other personal data identified in Article 4 of GDPR. Blacksmith does not require, request, or design the Service to receive any particular category of Personal Data, and receives such data only as and when Customer elects to process it through the Service. **Sensitive data transferred (if applicable), and applied restrictions or safeguards:** Blacksmith does not request or require sensitive or special-category data (as described in Articles 9 and 10 GDPR) and does not design the Service to process it. Blacksmith receives such data only if and to the extent Customer elects to include it in Customer Personal Data. Where such data is processed, the technical and organisational measures set out in Annex II apply, including encryption, access controls, isolation of execution environments, and logging of access. **Frequency of the transfer:** Continuous, for the duration of Customer's use of the Service under the Services Agreement. **Nature of the processing:** The basic processing activities associated with the transferred Personal Data are as follows: **Duration and Objective of Processing.** The processing period shall align with the term specified in the Services Agreement governing the relationship between the parties. The primary objective is the delivery of the Services as defined therein. **Personal Data Management.** Throughout the designated term, Blacksmith shall, at its discretion or as mandated by law, facilitate the correction, deletion, or restriction of Personal Data either through self-service features or by performing such actions on Customer's behalf. **Documented Instructions.** Regarding the provision of Services, Blacksmith shall Process Personal Data strictly in accordance with documented instructions from Customer and the terms of the Services Agreement. **Purpose(s) of the data transfer and further processing:** The specific nature and objectives of Processing Personal Data are delineated within Section 2 (Scope and Order of Precedence) and Section 3 (Processing Roles) of this DPA. Such activities may be conducted in any jurisdiction where Blacksmith or its authorized Sub-processors maintain operational facilities, pursuant to the provisions established in Section 11 (International Data Transfers) regarding data locations and transfers. **Period for which the personal data will be retained, or criteria used to determine that period:** Following the conclusion of the Service term, and provided Blacksmith is acting as a Processor, Blacksmith shall, at Customer's discretion, facilitate the return or execution of the deletion of all Customer Personal Data in accordance with the retention and deletion protocols set forth in the DPA and Services Agreement. **For transfers to (sub-)processors, also specify the subject matter, nature, and duration of the processing:** Pursuant to the terms of this DPA, Blacksmith is authorized to engage third-party entities to perform specialized functions on its behalf, including the provision of technical support services. Such Sub-processors shall be granted access to Personal Data strictly for the purpose of executing their designated service obligations and are expressly restricted from utilizing such data for any auxiliary objectives. Barring the earlier substitution of a specific Sub-processor, the duration of such processing shall align with the term specified in the Services Agreement governing the relationship between Customer and Blacksmith. ### C. Competent Supervisory Authority Module One: Controller to Controller; Module Two: Controller to Processor; and Module Three: Processor to Processor. The supervisory authority with responsibility for ensuring compliance by the data exporter with Regulation (EU) 2016/679. ## DPA Attachment 2: Annex II to the SCCs (EU/EEA) Module One: Controller to Controller; Module Two: Controller to Processor; and Module Three: Processor to Processor. The Technical and Organizational Security Measures below describe the security measures implemented and maintained by Blacksmith. Further detail is set out in Blacksmith's [trust center](https://trust.blacksmith.sh/), and Blacksmith's compliance is evidenced by its SOC 2 Type 2 report, available on request and via the [trust center](https://trust.blacksmith.sh/). | Technical and Organizational Security Measure | Description | | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Confidentiality and encryption of Customer Personal Data** | Encryption of Customer Personal Data in transit and at rest, and other confidentiality measures consistent with industry standards. | | **Systems integrity, availability, and resilience** | Measures to ensure the ongoing confidentiality, integrity, availability, and resilience of processing systems and services, including redundancy, backup, and disaster-recovery arrangements. | | **Restoring availability after an incident** | Backup and disaster-recovery processes designed to restore access to and availability of Customer Personal Data in a timely manner following a physical or technical incident. | | **Regular security testing and validation** | A security program including regular risk assessments, vulnerability scanning, and penetration testing, validated by an independent SOC 2 Type 2 examination. The current SOC 2 Type 2 report is available via the trust center on request. | | **User access control and authentication** | Role-based access controls and strong authentication (including multi-factor authentication) governing access to systems that process Customer Personal Data. | | **Isolation of execution environments** | Customer workloads are executed in isolated, ephemeral virtual machine environments that are provisioned per job and torn down on completion, providing isolation between tenants and between workloads. | | **Secrets and credential management** | Controls for the handling of secrets, access tokens, API keys, and environment variables used within the Services, including restricted access, encryption, and scoping of credentials to the workloads that require them. | | **Physical security of data processing locations** | Physical and environmental security of the data centers and facilities where Customer Personal Data is processed is provided through Blacksmith's infrastructure Sub-processors, which maintain their own independently audited physical-security controls and certifications for those facilities. | | **Logging and monitoring** | Logging of system and security events, security monitoring, and incident detection and response procedures. | | **Limited data retention and deletion** | Customer Personal Data is retained only as long as necessary to provide the Services and is deleted or returned on termination in accordance with Section 13 of this DPA, except where retention is required by applicable law. | | **Data portability and erasure** | Mechanisms enabling Customer to access, export, or delete Customer Personal Data, as described in Section 13 of this DPA. | | **Sub-processor oversight** | Written agreements with Sub-processors imposing data-protection obligations no less protective than this DPA, with Blacksmith remaining liable for their performance, as described in Section 8. The current Sub-processor list is available at [https://docs.blacksmith.sh/about/sub-processors](https://docs.blacksmith.sh/about/sub-processors). | ## Changelog Subscribe to this changelog via the [RSS feed](https://docs.blacksmith.sh/about/data-processing-addendum/rss.xml) to be notified about changes to this Data Processing Addendum. Published the initial Blacksmith Data Processing Addendum. # Privacy Policy Source: https://docs.blacksmith.sh/about/privacy-policy ## Owner and Data Controller Blacksmith Software Inc. 95 Third Street, 2nd Floor, San Francisco CA, 94103, United States Owner contact email: [hello@blacksmith.sh](mailto:hello@blacksmith.sh) ## Types of Data Collected Blacksmith Software Inc. ("Blacksmith") collects the following types of Personal Data when you sign in with your GitHub account and set up our GitHub integration in your organization: GitHub webhook metadata used for billing purposes and to provide analytics on your GitHub Actions performance and trends, as well as payment information, including credit card details securely processed through Stripe for monthly billing based on your usage. This data is collected automatically through your interactions with the service and is essential for Blacksmith to deliver and improve its offerings. Users are responsible for ensuring they have consent to provide any third-party Personal Data and understand that withholding mandatory data may affect the functionality of the Service. ## Mode and place of processing the Data ### Methods of processing Blacksmith Software Inc. ("Blacksmith") implements robust industry-standard security measures to protect your data from unauthorized access, disclosure, modification, or destruction. Data processing is performed following strict organizational procedures aligned with the purposes outlined in this Privacy Policy. In addition to Blacksmith's internal teams responsible for administration, sales, marketing, legal, and system administration, your data may be accessed by trusted third-party service providers, including payment processors like Stripe, hosting providers, and communication tools appointed as Data Processors. These external parties are bound by confidentiality agreements and are only granted access as necessary to provide the Service. An updated list of these Data Processors is available upon request from Blacksmith by contacting [hello@blacksmith.sh](mailto:hello@blacksmith.sh). ### Legal basis of processing Blacksmith Software Inc. ("Blacksmith") processes Personal Data of Users based on the following legal grounds: (1) **Consent:** Users have provided explicit consent for specific purposes, such as billing and analytics related to GitHub Actions performance; (2) **Contractual Necessity:** Processing is necessary to fulfill our service agreement with Users, including running GitHub Actions runners and managing billing through Stripe; (3) **Legal Obligations:** We process data to comply with applicable legal requirements and regulations; (4) **Legitimate Interests:** Processing is essential for our legitimate business interests, such as improving service performance and ensuring secure operations. Blacksmith does **not** use Personal Data for training Artificial Intelligence (AI) or Machine Learning (ML) models. However, Blacksmith may process Personal Data using third-party AI services solely to provide Service features (such as intelligent analytics and insights). Data processed by these AI services is not used to train or improve AI models. These AI-powered features are enabled by default but Users may disable them at any time through the Service settings. In jurisdictions where consent is not required for certain processing activities, Blacksmith relies on these alternative legal bases. Users may contact Blacksmith to clarify the specific legal basis applicable to their data processing, including whether providing Personal Data is a statutory or contractual requirement or necessary to enter into a contract. ### Place Blacksmith Software Inc. ("Blacksmith") processes Personal Data on our servers located in the United States and the European Union. Depending on your location, your data may be transferred between these regions. If you have concerns about where your data is processed, you may request to have your workload moved to a specific region by contacting us at [hello@blacksmith.sh](mailto:hello@blacksmith.sh). While we will consider such requests, relocation of data processing is not guaranteed until an agreement is reached. For more information about data processing locations, data transfers, and the legal basis for transferring data, please contact us directly. ### Retention Blacksmith Software Inc. ("Blacksmith") retains Personal Data only for as long as necessary to fulfill the purposes for which it was collected. Personal Data related to the performance of a contract between Blacksmith and the User is retained until the contract is fully performed. Data processed under Blacksmith's legitimate interests is kept as long as needed to achieve those purposes. Additionally, Personal Data may be retained longer if required by law or with the User's explicit consent, which can be withdrawn at any time. While you are a customer, your data will not be deleted. Upon termination of the agreement or upon your request, Blacksmith will delete all relevant user data within **30 days** using industry-standard methods, ensuring compliance with backup and security protocols. To request data deletion, please contact us at [hello@blacksmith.sh](mailto:hello@blacksmith.sh). Once the retention period has expired, your rights to access, erase, rectify, and port data cannot be enforced. ## Detailed information on the processing of Personal Data Personal Data is collected for the following purposes and using the following services: ### Handling payments Unless otherwise specified, this Application processes any payments by credit card, bank transfer or other means via external payment service providers. In general and unless where otherwise stated, Users are requested to provide their payment details and personal information directly to such payment service providers. This Application isn't involved in the collection and processing of such information: instead, it will only receive a notification by the relevant payment service provider as to whether payment has been successfully completed. #### Stripe (Stripe Inc.) Stripe is a payment service provided Stripe Inc. Personal Data processed: email address; payment info; purchase history; Tracker; Usage Data. Place of processing: United States – Privacy Policy. ### Registration and authentication By registering or authenticating, Users allow this Application to identify them and give them access to dedicated services. Depending on what is described below, third parties may provide registration and authentication services. In this case, this Application will be able to access some Data, stored by these third-party services, for registration or identification purposes. Some of the services listed below may also collect Personal Data for targeting and profiling purposes; to find out more, please refer to the description of each service. #### GitHub OAuth (GitHub Inc.) GitHub OAuth is a registration and authentication service provided by GitHub Inc. and is connected to the GitHub network. Personal Data processed: various types of Data as specified in the privacy policy of the service. Place of processing: United States – Privacy Policy. ### Traffic optimization and distribution This type of service allows this Application to distribute their content using servers located across different countries and to optimize their performance. Which Personal Data are processed depends on the characteristics and the way these services are implemented. Their function is to filter communications between this Application and the User's browser. Considering the widespread distribution of this system, it is difficult to determine the locations to which the contents that may contain Personal Information of the User are transferred. #### Cloudflare (Cloudflare Inc.) Cloudflare is a traffic optimization and distribution service provided by Cloudflare Inc. The way Cloudflare is integrated means that it filters all the traffic through this Application, i.e., communication between this Application and the User's browser, while also allowing analytical data from this Application to be collected. Personal Data processed: various types of Data as specified in the privacy policy of the service. Place of processing: United States – Privacy Policy. #### User database management This type of service allows the Owner to build user profiles by starting from an email address, a personal name, or other information that the User provides to this Application, as well as to track User activities through analytics features. This Personal Data may also be matched with publicly available information about the User (such as social networks' profiles) and used to build private profiles that the Owner can display and use for improving this Application. Some of these services may also enable the sending of timed messages to the User, such as emails based on specific actions performed on this Application. #### Supabase Supabase is an open-source backend-as-a-service platform built on PostgreSQL. It provides a full Postgres database for every project, along with features like real-time functionality, authentication, and auto-generated APIs, making it easy to build and manage web and mobile applications. Personal Data processed: email address, usage data, and various types of data as specified in the privacy policy of the service. Place of processing: United States – Privacy Policy. ## Information on opting out of interest-based advertising In addition to any opt-out feature provided by any of the services listed in this document, Users may follow the instructions provided by YourOnlineChoices (EU), the Network Advertising Initiative (US) and the Digital Advertising Alliance (US), DAAC (Canada), DDAI (Japan) or other similar initiatives. Such initiatives allow Users to select their tracking preferences for most of the advertising tools. The Owner thus recommends that Users make use of these resources in addition to the information provided in this document. The Digital Advertising Alliance offers an application called AppChoices that helps Users to control interest-based advertising on mobile apps. Users may also opt-out of certain advertising features through applicable device settings, such as the device advertising settings for mobile phones or ads settings in general. ## Further information about the processing of Personal Data ### The rights of Users Blacksmith Software Inc. ("Blacksmith") empowers Users with the following rights regarding their Personal Data: * **Withdraw Consent:** Users can withdraw their consent to data processing at any time. * **Object to Processing:** Users may object to data processing based on legitimate interests or other legal grounds beyond consent. * **Access Data:** Users can request information on whether their data is being processed and obtain a copy of their Personal Data. * **Rectify Data:** Users have the right to correct inaccurate or incomplete Personal Data. * **Restrict Processing:** Users can limit the processing of their data, allowing Blacksmith to store it without further use. * **Erase Data:** Users may request the deletion of their Personal Data under specific circumstances. * **Data Portability:** Users can receive their data in a structured, commonly used, machine-readable format and transfer it to another controller. * **Lodge a Complaint:** Users have the right to file a complaint with their competent data protection authority. * **Restrict Data Flow from GitHub:** Users can restrict data flow by uninstalling or suspending the Blacksmith GitHub integration. Please note that doing so may affect the functionality and performance of the Service. * **Disable AI-Powered Features:** Users can disable AI-powered features at any time through the Service settings. When disabled, User data will not be processed by third-party AI services for feature functionality. Disabling AI features may limit access to certain Service capabilities such as intelligent summaries or recommendations. To exercise any of these rights, Users can contact Blacksmith at [hello@blacksmith.sh](mailto:hello@blacksmith.sh). Users should be aware that some jurisdictions may impose specific limitations on these rights. ### Details about the right to object to processing Blacksmith Software Inc. ("Blacksmith") processes Personal Data based on legitimate interests, such as improving service performance and providing billing and analytics for GitHub Actions. Users have the right to object to this processing by providing a reason related to their specific situation. To exercise this right, please contact us at [hello@blacksmith.sh](mailto:hello@blacksmith.sh). Blacksmith does not process Personal Data for direct marketing purposes. If you object to the processing based on legitimate interests, we will assess your request and determine whether to continue processing your data. For more information on how we process Personal Data, please refer to the relevant sections of this Privacy Policy. ## Additional information about Data collection and processing ### Legal action The User's Personal Data may be used for legal purposes by the Owner in Court or in the stages leading to possible legal action arising from improper use of this Application or the related Services. The User declares to be aware that the Owner may be required to reveal personal data upon request of public authorities. ### System logs and maintenance For operation and maintenance purposes, this Application and any third-party services may collect files that record interaction with this Application (System logs) use other Personal Data (such as the IP Address) for this purpose. ### How "Do Not Track" requests are handled This Application does not support "Do Not Track" requests. To determine whether any of the third-party services it uses honor the "Do Not Track" requests, please read their privacy policies. ### Changes to this privacy policy Blacksmith Software Inc. ("Blacksmith") reserves the right to modify this Privacy Policy at any time. We may update this policy by posting changes on this page without prior notice. However, for significant changes that materially affect how we process your Personal Data, we will notify you via the email address associated with your account. We encourage Users to regularly review this Privacy Policy to stay informed about our data practices. ## EU and UK Representatives for Data Protection Requests In accordance with Article 27 of the EU GDPR and UK GDPR, Blacksmith has appointed representatives in the European Union and the United Kingdom to act as our point of contact for data subjects and supervisory authorities on all matters relating to personal data protection and GDPR compliance. ### GDPR EU Representative Company Name: Instant EU GDPR Representative Ltd Name: Adam Brogden Data protection request form: [https://blacksmithsoftwareinc.gdprlocal.com/eu](https://blacksmithsoftwareinc.gdprlocal.com/eu) Email: [contact@gdprlocal.com](mailto:contact@gdprlocal.com) Tel: +353 15 549 700 Address: INSTANT EU GDPR REPRESENTATIVE LIMITED Office 2 12A Lower Main Street, Lucan Co. Dublin K78 X5P8 Ireland ### GDPR UK Representative Company Name: GDPRLocal Ltd. Name: Adam Brogden Data protection request form: [https://blacksmithsoftwareinc.gdprlocal.com/uk](https://blacksmithsoftwareinc.gdprlocal.com/uk) Email: [contact@gpdrlocal.com](mailto:contact@gpdrlocal.com) Tel: +441 772 217 800 UK Address: GDPRLocal Ltd. 1st Floor Front Suite 27-29 North Street, Brighton England BN1 1EB ## Definitions and Legal References ### Personal Data (or Data) Any information that can directly or indirectly identify a natural person, including personal identification numbers, email addresses, and other identifiers. ### Usage Data Information automatically collected through Blacksmith's service or third-party integrations, which may include IP addresses, domain names, Uniform Resource Identifiers (URIs), request times, methods used to submit requests, file sizes received, server response codes, country of origin, browser features, operating systems, time spent on each page, navigation paths within the service, and device or IT environment details. ### User An individual who uses Blacksmith's service and, unless otherwise specified, is synonymous with the Data Subject. ### Data Subject The natural person to whom the Personal Data pertains. ### Data Processor (or Data Supervisor) Any natural or legal person, public authority, agency, or other body that processes Personal Data on behalf of Blacksmith, as outlined in this Privacy Policy. This includes third-party service providers like Stripe, hosting providers, and IT firms. ### Data Controller (or Owner) Blacksmith Software Inc., the entity that determines the purposes and means of processing Personal Data, including implementing security measures related to the operation and use of the service. ### This Application The platform provided by Blacksmith through which Users sign in with their GitHub accounts, install the Blacksmith GitHub integration into their organizations, and utilize GitHub Actions runners. ### Service The GitHub Actions runners offered by Blacksmith, enabling Users to run their GitHub Actions faster and more cost-effectively. ### European Union (or EU) All current member states of the European Union and the European Economic Area, unless otherwise specified within this document. ### Legal Information This Privacy Policy is crafted in accordance with various legislations, including Articles 13 and 14 of Regulation (EU) 2016/679 (General Data Protection Regulation). This policy exclusively pertains to Blacksmith's service unless stated otherwise within this document. # Sub-processors Source: https://docs.blacksmith.sh/about/sub-processors **Last Updated:** August 12, 2026 This page lists the sub-processors that Blacksmith engages to process Customer Personal Data on behalf of Customers and to support the delivery of our Services as defined in the Data Processing Addendum. The sub-processors relevant to a particular Customer depend on the specific Services they use. Blacksmith maintains an up-to-date list of all sub-processors below, with a description of their processing activities and the locations where data is processed. Customers may subscribe to updates about new or replacement sub-processors via the RSS feed on this page. ## Blacksmith's sub-processors | Subprocessor | Applicable Services | Processing Activities | Location | | -------------------------------- | ------------------- | ----------------------------------------------------- | ----------------------------- | | Anthropic PBC | AI Features | AI model provider | United States | | BaseTen Labs, Inc. | AI Features | AI model provider | United States | | Grok, Inc. (xAI) | AI Features | AI model provider | United States | | OpenAI Foundation | AI Features | AI model provider | United States | | Mistral AI SAS | AI Features | AI model provider | European Union | | Daytona Platforms Inc. | AI Features | Sandbox environments | European Union | | Turbopuffer Inc. | AI Features | Embedding vector storage | European Union | | Braintrust Data, Inc. | AI Features | LLM-trace observability | United States | | Functional Software Inc (Sentry) | All services | Error monitoring and crash reporting | United States | | Axiom, Inc. | All services | Logging and metrics | United States | | PostHog, Inc. | All services | Product analytics, feature flags | United States | | Vercel Inc. | All services | Frontend hosting and edge delivery | European Union | | Pylon Labs, Inc. | All services | Customer service and technical support | United States | | Plus Five Five, Inc. (Resend) | All services | Outbound email | European Union | | Astrodon Corporation (Loops) | All services | Outbound email | United States | | Cloudflare, Inc. | All services | DNS and object storage | United States, European Union | | Amazon Web Services, Inc. | All services | Cloud hosting | United States, European Union | | PlanetScale, Inc. | All services | Application database hosting | European Union | | ClickHouse, Inc. | All services | Observability and analytics database hosting | United States, European Union | | Redis Inc | All services | Queueing, streaming, and caching | United States, European Union | | PhoenixNAP LLC | All services | Datacenter provider | United States, European Union | | Hetzner Online GmbH | All services | Datacenter provider | European Union | | Summit Hosting LLC | All services | Datacenter provider | United States | | Megaport (Latitude.sh) | All services | Datacenter provider | United States | | MacWeb | All services | Datacenter provider | United States | | Salesforce (Slack) | All services | Collaboration; customer service and technical support | United States | For questions about our sub-processors, contact us at [hello@blacksmith.sh](mailto:hello@blacksmith.sh). ## Changelog Subscribe to this changelog via the [RSS feed](https://docs.blacksmith.sh/about/sub-processors/rss.xml) to be notified about new or replacement sub-processors. Updated applicable services for Anthropic, BaseTen Labs, Grok, OpenAI Foundation, Mistral, Daytona, Turbopuffer, and Braintrust to AI Features. Simplified OpenAI Foundation and Mistral processing activities to AI model provider. Added MacWeb (datacenter provider for All services). Added Codesmith as an applicable service and AI model provider as a processing activity for OpenAI Foundation. Updated the processing location for Vercel Inc., Plus Five Five, Inc. (Resend), and Daytona Platforms Inc. to European Union. Added BaseTen Labs, Inc. (AI model provider for Codesmith) and OpenAI Foundation (test failure log embeddings for Test Failure Summaries). Published the initial list of Blacksmith sub-processors. # Support Terms Source: https://docs.blacksmith.sh/about/support-terms Blacksmith has 3 different levels of support plans (**"Support Plans"**) to provide support for the Services (**"Support Services"**): Standard Support, Premium Support, and Enterprise Support. Unless otherwise stated in the contract between customer and Blacksmith, the Services that customer procures will automatically determine the level of its Support Plan. Support Services are provided in the English language only. ## 1. Support Plans | Standard Support | Premium Support | Enterprise Support | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Available to all customers at no additional charge. Applies to free accounts and accounts not qualifying for a higher plan. No Uptime SLA or service credits apply. | Available to customers who have either (a) purchased a Premium Support add-on, or (b) entered into an annual or committed-spend contract. Premium Support is available at the greater of US \$250 per month or 5% of the customer's monthly Blacksmith spend. No Uptime SLA or service credits apply. | Available to customers who have purchased Enterprise Support. Enterprise Support includes Uptime SLA and service credits as described in the Service Level Agreement section, plus the items listed below. | Enterprise Support additionally includes: * **Dedicated Slack Channel:** A private Slack channel shared between the customer's team and Blacksmith for direct communication with Blacksmith engineers and support staff. The Slack channel is not the designated channel for opening or tracking Support requests. * **Dedicated Team of Global Support Engineers:** A team of support engineers is prioritized to Enterprise customers to assist with the more technical aspects of issues, provide faster resolution, and serve as the primary point of contact for all support requests. * **Onboarding Assistance:** Blacksmith's engineering team will work directly with customer to migrate, configure, and validate CI workflows on the Blacksmith platform. * **CI Optimization:** Ongoing guidance on runner sizing, caching, parallelization, and workflow configuration. Blacksmith will deliver quarterly reviews covering optimization recommendations, ticket trends, resolution times, and service level performance. * **Priority Escalation:** The Enterprise Support team can escalate requests directly to Blacksmith's product and engineering teams. Business Critical Incidents will be raised to senior engineering and management personnel as needed. * **Environmental Runbook:** An internal support resource prepared by Blacksmith and tailored to customer CI implementation, services, and use cases, to facilitate a more individualized approach to reviews and responses provided by Blacksmith support personnel. ## 2. Support ### A. Support Requests Tickets for Incidents must be submitted through the Blacksmith dashboard. If customer encounters an error submitting a ticket via the dashboard, please contact [support@blacksmith.sh](mailto:support@blacksmith.sh) with a description of the submission error. Email is not a designated support channel. Customer shall provide Blacksmith with reasonable information and assistance to facilitate performance of Support Services, including a detailed description of the issue, related configuration and log files, and reasonable cooperation to enable Blacksmith to reproduce errors. Customers shall not include sensitive data such as personal, health, or financial information in the ticket. ### B. Response Times Blacksmith's production infrastructure is monitored continuously with automated health checks and error condition alerting. All alerts are reviewed and triaged in accordance with Blacksmith's Incident Response Plan. Platform availability and active incidents are published at [status.blacksmith.sh](https://status.blacksmith.sh). Blacksmith will assign an initial severity level to each ticket upon receipt and reserves the right to reclassify severity at any time, including downgrading severity where a Workaround has been provided or where customer has not supplied information required to progress resolution. In the event of an Incident, Blacksmith will respond as follows: | Impact | Premium Support | Enterprise Support | Additional Actions | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------- | :--------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Business Critical Incident.** Total failure or severe degradation of the Services. Customer is unable to run CI workloads or access the Services. | Every response within 2 hours (24/7) | Every response within 30 minutes (24/7) | Engineers work continuously toward a Workaround or Resolution. Status updates are published at status.blacksmith.sh. Incidents are raised to senior engineering and management personnel as needed. | | **Degraded Services Incident.** Partial failure or degradation of the Services. Customer can access some but not all features, or experiences reduced runner performance. | Initial response within 8 hours (24/7) | Every response within 4 hours (24/7) | Engineers work toward a Workaround or Resolution. If the Incident is not resolved within 8 Business Hours, it is raised to senior engineering personnel. | | **General Issue.** All other issues, including non-critical technical problems, configuration questions, integration guidance, optimization queries, and feature requests. | Initial response within 24 Business Hours | Initial response within 12 Business Hours; subsequent responses within 24 Business Hours | Engineers work during Business Hours to provide a Workaround, Resolution, or response to queries. Enterprise customers may raise CI optimization questions through this channel. | *Response time commitments apply only to tickets filed through the dashboard and do not apply to email submissions.* ### C. Defined Terms | Term | Definition | | :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"Business Hours"** | 8:00 AM to 8:00 PM Eastern Time, Monday through Friday, excluding the following holidays: New Year's Day, Martin Luther King Jr. Day, Presidents' Day, Memorial Day, Juneteenth, Independence Day, Labor Day, Thanksgiving Day, the Friday following Thanksgiving, Christmas Eve, and Christmas Day. | | **"Incident"** | A failure of the Services to perform in material conformance with the Master Services Agreement between the parties or Documentation. | | **"Resolution"** | Either Blacksmith has: (a) corrected the Incident so that the Services perform in material conformance with the Master Services Agreement between the parties and the Documentation, or (b) determined the reported Incident was the result of an Exception. | | **"Exception"** | Any event outside of Blacksmith's reasonable control that contributes to or causes an Incident, including GitHub platform or GitHub Actions infrastructure outages, Customer-caused misconfigurations, third-party service failures, scheduled maintenance communicated in advance via [status.blacksmith.sh](https://status.blacksmith.sh), or force majeure events. | | **"Workaround"** | A configuration change, manual procedure, or other measure that restores previously functioning features or functionality without providing a complete Resolution. | ## 3. Service Level Agreement This Service Level Agreement (**"Uptime SLA"**) applies exclusively to Enterprise Support customers. Customers on Standard Support, Premium Support, or any other support plan are not eligible for this Uptime SLA, service credits, or any other commitment described in this section. This Uptime SLA applies only to the services and products specifically listed under the applicable Order, and is subject to the definitions, scopes, and exclusions outlined in this document. Blacksmith commits to 99.9% monthly platform availability to Enterprise Support customers, measured using data from [status.blacksmith.sh](https://status.blacksmith.sh) as the source of record. 99.9% monthly availability equates to approximately 43 minutes of allowable downtime per calendar month. Uptime is calculated as follows: *(Total minutes in calendar month minus Downtime minutes) divided by Total minutes in calendar month, multiplied by 100)* Scheduled maintenance communicated in advance via status.blacksmith.sh is excluded from the downtime calculation. In the event Blacksmith fails to meet the uptime commitment of 99.9%, the Enterprise customer may be eligible for service credits as set forth in the applicable Order to the Blacksmith Master Services Agreement. Service credits are an Enterprise Support customer's sole and exclusive remedy for Blacksmith's failure to meet the uptime commitment in this section. ### Exclusions from Uptime SLA Blacksmith is not responsible for outages or service interruptions caused by factors outside of its reasonable control. The following categories of events are excluded from downtime calculations and do not qualify for Uptime SLA credits: * ***Third-party infrastructure and cloud providers:*** Issues attributable to external vendors or cloud providers, including but not limited to AWS, Cloudflare, GCP, Azure, GitHub, or other similar providers upon whose infrastructure Blacksmith's services depend. * ***GitHub platform issues:*** Incidents originating from GitHub Actions infrastructure, GitHub API availability, or GitHub-side outages are outside the scope of Blacksmith Support. * ***Integration partners:*** Failures or downtime related to third-party integration partners or services that the customer connects to the Blacksmith platform. * ***Force majeure and factors outside our control:*** Events such as natural disasters, acts of war, government action, internet service provider (ISP) outages, or other circumstances outside Blacksmith's reasonable control. ## 4. Self-Help Materials Blacksmith provides the following self-help resources: * **Documentation:** Blacksmith documentation covers runner setup, caching, integrations, security, and platform configuration. Available at [docs.blacksmith.sh](https://docs.blacksmith.sh) * **Platform Status Page:** Real-time platform availability, incident history, and scheduled maintenance notices. Available at [status.blacksmith.sh](https://status.blacksmith.sh) Self-help resources are not part of the Support Services. ## 5. Miscellaneous Terms ### A. Exclusions Support Plans/Support Services do not apply to: * ***Pre-commercial services:*** Alpha, beta, or other pre-commercial releases of any Blacksmith product, service, or feature. * ***Billing questions:*** Direct billing questions to [billing@blacksmith.sh](mailto:billing@blacksmith.sh) or to your customer success representative. * ***Third-party tooling:*** Third-party GitHub Actions, customer-managed secrets, external registries, or infrastructure outside the Blacksmith platform. * ***Custom code:*** Debugging Customer-authored workflow code, scripts, or configurations that are not part of the Blacksmith platform. ### B. Etiquette Customers must communicate with Blacksmith Support in a professional and respectful manner. Blacksmith reserves the right to suspend Support Services to any user who engages in abusive, threatening, or objectionable communications. ### C. Modifications Support Plans may be modified from time to time by Blacksmith, provided that the level of support will not materially decrease during the applicable Order Term. Customers will be notified of material changes in writing. ### D. Exclusive Remedy Customer's sole and exclusive remedy for any alleged failure by Blacksmith to provide Support Services in accordance with the terms hereunder shall be re-performance of the applicable Support Services. # Terms of Service Source: https://docs.blacksmith.sh/about/terms-of-service Effective: **July 20th, 2026** ## 1. Definitions 1. **"*Agreement*"** means these Blacksmith Terms of Services. 2. **"*Account*"** means the place where You log into and use the Services. 3. **"*AI Feature*"** means a feature of the Services that uses machine learning or artificial intelligence to generate Output. 4. **"*Blacksmith*" or "*We*" or "*Us*" or "*Our*"** means Blacksmith Software, Inc. 5. **"*Blacksmith Website*"** means the website located at [https://blacksmith.sh/](https://blacksmith.sh/) and any valid subdomains. 6. **"*Customer*" or "*You*" or "*Your*"** means the individual person, company, or organization that is accessing and using the Services. 7. **"*Customer Content*"** means any data, information, files, code, configurations, documents, text, graphics, photos, software, or other materials that You upload, submit, transmit, store, or otherwise make available through the Services. This includes content generated or processed by GitHub and GitHub Actions that are relayed to the Services. 8. **"*Documentation*"** means Our standard published documentation for the Services. 9. **"*Force Majeure Event*"** means an unforeseen event outside of Our reasonable control. Examples include but are not limited to: major earthquake, war, pandemic, riot, act of terrorism, or public utility or internet failure. 10. **"*Output*"** means responses and suggestions, including code or other material, generated by an AI Feature. 11. **"*Personal Data*"** means any information that can be used to identify, locate, or contact a specific living individual. 12. **"*Privacy Policy*"** means Our privacy policy located at [https://docs.blacksmith.sh/about/privacy-policy](https://docs.blacksmith.sh/about/privacy-policy). 13. **"*Services*"** means any of the applications, software, products, and services provided by Blacksmith. 14. **"*Sensitive Personal Information*"** means any (i) special categories of Personal Data enumerated in European Union Regulation 2016/679, Article 9(1) or any successor legislation; (ii) patient, medical or other protected health information regulated by HIPAA; (iii) credit, debit or other payment card data subject to PCI DSS; (iv) other Personal Data subject to regulation or protection under specific laws such as the Gramm-Leach-Bliley Act (or related rules or regulations); (v) social security numbers, driver's license numbers or other government ID numbers; or (vi) any data similar to the foregoing that is protected under foreign or domestic laws or regulations. ## 2. Account 1. To use the Services, You must first set up an Account. You must be a human to create an Account and You must be age 13 or older. The Account setup process requires that You (i) install Blacksmith's GitHub integration in your org allowing connection of the Services to your GitHub account, and (ii) add a valid payment method, such as a credit card, which will be processed through Stripe. By integrating Your GitHub account with the Services, You grant Us a non-exclusive, limited, revocable license (i) to utilize Your code to create pull requests with changes in runner tags and execute GitHub binaries in Our virtual machines, and (ii) where You invoke an AI Feature such as Our coding agent, to access, analyze, modify, and create derivative works of Your code and to create branches, commits, and pull requests on Your behalf, solely for the purpose of providing the Services. You are solely responsible for ensuring access, use, and interoperation of Your GitHub account with the Services complies with all applicable third-party terms, policies and licenses. We do not access, reproduce, modify, distribute, or create derivative works from Your code outside the scope of the functionalities mentioned above. 2. You are responsible for keeping Your Account secure while You use the Services. You will promptly notify Us if You become aware of any unauthorized use or access to the Services through Your Account. ## 3. Restrictions You shall not: * decompile, decipher, prepare derivative works of, reverse engineer or otherwise attempt to access or derive the source code or other trade secrets of the Services; * provide, sell, transfer, sublicense, lend, distribute, rent, assign, act as service bureau, or otherwise allow third parties to access or use the Services; * remove, modify or obscure any proprietary notices or labels contained in the Services and Documentation; * conduct security or vulnerability tests on, interfere with the operation of, cause performance degradation of, or circumvent access restrictions of the Services; * use the Services with any activity prohibited by applicable law; * interfere with or disrupt, disable, damage, impair, or overburden the Services, including by transmitting viruses, malware, malicious code, or any other material that disrupts, slows down or causes the Services to malfunction; or * upload any Sensitive Personal Information to the Services. ## 4. Security We maintain industry standard physical and technical safeguards designed to protect the security and integrity of the Services (the **"*Security Measures*"**). Upon request to [https://trust.blacksmith.sh](https://trust.blacksmith.sh), We will provide You with a copy of Our third-party audit report or certification, such as a SOC 2 Type II report, that describes Our Security Measures along with a copy of Our most recent penetration test report. Also, You can access Our Data Processing Addendum located at [https://docs.blacksmith.sh/about/data-processing-addendum](https://docs.blacksmith.sh/about/data-processing-addendum). ## 5. Intellectual Property We and Our licensors retain ownership and title of all intellectual property rights of any kind related to the Services and Documentation. We reserve all rights that are not expressly granted to You under this Agreement or by law. ## 6. Customer Content 1. Between You and Us, You retain all right to the Customer Content. You are responsible for the Customer Content. You hereby confirm that You have the right to submit and use the Customer Content. You grant Us the right to store, host, archive, display, and use the Customer Content as necessary to provide the Services to You. 2. We use industry standard methods to delete the Customer Content when no longer needed to provide the Services to You. You may at any time, request deletion of Your Customer Content and We will comply with such request within 30 days of notice. ## 7. AI Features 1. The Services has AI Features that provide Outputs such as generated code, intelligent analytics, and insights. You may, at any time, disable these AI Features by contacting Us. We will not use Your Personal Data or Customer Content to train or improve AI models. 2. All Output is provided "as-is" and may be inaccurate, incomplete, or non-functional. We do not guarantee that the Output is free of errors, vulnerabilities, or intellectual property claims. ## 8. Payment You are responsible for all fees, including taxes, associated with Your use of the Services. Payment for the Services may be via credit card, or You and We may agree that payment be billed via invoice. For credit card payment, Your providing payment information authorizes Us to charge Your credit card for usage fees. For invoice-based agreements, You will make timely payments as specified in the invoicing terms. ## 9. Suspension and Termination 1. We have the right to suspend or terminate Your access and use of the Services effective immediately if (i) You violate Section 3 (Restrictions), (ii) it is necessary for the security or integrity of the Services, (iii) You are in arrears in payment for the Services, or (iv) a Force Majeure Event occurs. 2. Upon termination, all provisions of this Agreement which, by their nature, should survive termination will survive termination including, without limitation: Disclaimer of Warranties and Limitations of Liability. ## 10. Disclaimer of Warranties We provide the Services "as is" and "as available," without warranty of any kind. We expressly disclaim all warranties, whether express, implied or statutory, regarding the Services including without limitation: non-infringement, warranty of merchantability, and fitness for a particular purpose. We do not warrant that the Services will be uninterrupted, timely, or error-free. ## 11. Limitation of Liability 1. You agree that We, our affiliates, our officers and directors will not be liable for any indirect, punitive, incidental, special, or consequential damages, or for damages for business interruption, inability to use the Services, loss of profits, goodwill, or other intangible losses arising out of or relating to this Agreement and/or the Services. 2. You agree that Our cumulative and aggregate liability under this Agreement and/or relating to the Services will not exceed the fees paid or payable by You to Us under this Agreement in the 12 months preceding the event giving rise to the liability. ## 12. Update We reserve the right to amend or update these Terms of Service. We will notify You of any material changes to these Terms of Services, at least 30 days prior to the change taking effect by posting a notice on the Blacksmith Website or sending You an email. Your continued use of the Services after the 30 days constitutes your agreement to the amendment of these Terms of Service. ## 13. Miscellaneous 1. **Governing Law and Venue.** This Agreement will be governed by and construed in accordance with the laws of the State of California and federal laws of the United States, without regard to conflict of law provisions. You agree to submit to the exclusive jurisdiction and venue of the courts located in the City and County of San Francisco, California. 2. **Assignment.** You may not assign or delegate this Agreement, or any of its rights or obligations under this Agreement, without Our prior written consent. 3. **Severability; No Waiver.** If any part of this Agreement is held invalid or unenforceable, that portion of the Agreement will be construed to reflect the parties' original intent. The remaining portions will remain in full force and effect. Our failure to enforce any provision of this Agreement will not be considered a waiver of Our right to enforce such provision. 4. **Feedback.** If You provide Us with any ideas, suggestions, recommendations or any other feedback for Our products or services (**"*Feedback*"**), You give Us a royalty-free, fully paid-up, worldwide, transferable, sub-licensable, irrevocable, perpetual license to use, modify, commercially exploit the Feedback into Our products and services. 5. **Notices.** All notices to Us must be in writing and emailed to [hello@blacksmith.sh](mailto:hello@blacksmith.sh). 6. **Entire Agreement; Modification.** This Agreement together with Our Privacy Policy and Data Processing Addendum constitutes the complete and final agreement between You and Blacksmith pertaining to the Services, and supersedes any other prior agreements, understandings and discussions relating to the Services. This Agreement may only be modified by a written amendment signed by one of Our authorized representatives, or by Us posting a revised version in accordance with Section 12 (Update). # GitHub App Source: https://docs.blacksmith.sh/blacksmith-administration/github-app Permissions the Blacksmith GitHub App requests, and which product features use them ## Overview The [blacksmith.sh](https://github.com/apps/blacksmith-sh) GitHub App is the single integration point between Blacksmith and your GitHub organization. Installing it is how Blacksmith registers runners, receives workflow events, and powers observability and [\[code\]smith](/codesmith/overview) agent features; there are no PATs, deploy keys, or other standing credentials involved. You can review the exact permission set on the GitHub App listing before or after install, and choose whether the app can access all repositories or only the ones you select. The short version: * **Running your CI needs almost nothing.** Provisioning runners uses the organization self-hosted runners permission plus webhook events. It does not require access to your code. * **Observability is read-only.** [Run History](/blacksmith-observability/history), [Logs](/blacksmith-observability/logs), [Metrics](/blacksmith-observability/metrics), and [CI Analytics](/blacksmith-observability/dashboard) read workflow run and job data from the Actions API. * **Write access exists for two features you invoke.** The [Migration Wizard](/introduction/quickstart#use-our-migration-wizard-to-update-your-github-actions-workflow-files) and \[code]smith are the only features that write to your repositories. Both deliver changes through branches and pull requests, and those PRs remain subject to your existing branch protections, required checks, and review rules. The app does not have permission to change or bypass those controls. * **No secrets, no admin.** The app does not request access to secrets, variables, environments, or any administration permission, and GitHub never exposes secret values over its API in any case. ## Repository permissions | Permission | Access | Used for | | ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Metadata | Read | Required baseline for every GitHub App. Lets Blacksmith identify the installation and the repositories it can access. | | Actions | Read & write | Read workflow run and job metadata and job logs for Run History, Logs, Metrics, [Monitors](/blacksmith-observability/monitors), and CI Analytics. Write is used to cancel or re-dispatch runs when a product feature calls for it. | | Contents | Read & write | Read workflow files for the Migration Wizard and analytics. Create branches and commits when the Migration Wizard or \[code]smith prepares a pull request. | | Workflows | Read & write | Required by GitHub for any commit that touches `.github/workflows/`. Used solely by the Migration Wizard and \[code]smith when they edit workflow files; nothing else uses this scope. | | Pull requests | Read & write | Open Migration Wizard and \[code]smith pull requests, which remain subject to your branch protections, required checks, and review rules. Post PR comments (test results, CI summaries) and reply on review threads. | | Checks | Read & write | Post the `[code]smith` check run on a pull request. Read check suites so managed-PR status stays current. | | Issues | Read | Required by GitHub to receive pull request comment events, including `@codesmith` mentions. | ## Organization permissions | Permission | Access | Used for | | ------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------ | | Administration of self-hosted runners | Read & write | Just-in-time runner registration and deregistration, and runner group management. This is how jobs land on Blacksmith runners. | | Members | Read | Map GitHub org membership and repository collaborator access onto the Blacksmith dashboard, including the team page. | ## What we do not request The Blacksmith GitHub App does **not** request: * Actions secrets, organization secrets, Dependabot secrets, or Codespaces secrets * Actions variables or environments * Administration (repository or organization) * Packages, deployments, or Dependabot It cannot read secret values, change org or repository settings, or manage membership. ## Webhook events The app subscribes to the events it needs to provision runners and keep product features current: * `workflow_job`, `workflow_run`: runner pickup, run history, logs, monitors, [autofix](/codesmith/autofix) * `pull_request`, `pull_request_review`, `pull_request_review_comment`, `issue_comment`, `issues`: PR tracking, comments, `@codesmith` * `check_run`, `check_suite`: `[code]smith` check status and mergeability * `push`: merge-conflict detection when \[code]smith is enabled * `organization`, `membership`, `member`, `team`, `repository`: keep dashboard access and repo lists in sync * `installation`, `installation_repositories`, `installation_target`: install, repo-selection, and rename lifecycle # Network & IP Allowlisting Source: https://docs.blacksmith.sh/blacksmith-administration/network-allowlisting Control plane IPs to allowlist in GitHub for Blacksmith to register runners ## Overview Some GitHub organizations restrict access via IP allowlists. Blacksmith's control plane needs to reach GitHub to register runners and manage workflows. You can manage your organization's IP allowlist in GitHub under **Settings → Security → Authentication security → IP allow list**. ## Control plane outbound IPs These IPs are used by Blacksmith's control plane to communicate with GitHub (not by your CI jobs/runners). You can find the current IPs in the Blacksmith dashboard: [**Settings > Features**](https://app.blacksmith.sh/settings?tab=features). ## When to allowlist these IPs You need to allowlist these IPs if: * Your GitHub organization has **IP allowlists** or network restrictions enabled * Your jobs are not getting picked up by Blacksmith runners ## How this differs from runner static IPs Blacksmith also offers **static IPs for runners** as a paid feature, allowing your CI jobs to reach your own external services from a fixed IP. See the [Static IP](/blacksmith-runners/static-ip) page for details. * **Control plane IPs** (this page): used by Blacksmith to communicate with GitHub * **Runner static IPs** (paid): used by your CI jobs to reach your own external services # Permissions Source: https://docs.blacksmith.sh/blacksmith-administration/permissions How GitHub permissions map to Blacksmith access ## Overview Blacksmith uses GitHub for authentication, and inherits your GitHub organization's structure. All members of your GitHub organization can log in using their GitHub accounts to access the Blacksmith dashboard. ## Basics Blacksmith inherits permissions directly from your GitHub organization: * **Organization Admins** can manage all settings, billing, and have full access to all repositories * **Repository permissions** (Admin/Write/Read) determine what data and actions are available for each repository * Users without repository access in GitHub cannot view that repository's data in Blacksmith ### Key Permission Controls | Feature | Org Admin | Repo Admin | Repo Write | Repo Read | No Access | | -------------------------------------------------------- | --------- | ---------- | ---------- | --------- | --------- | | **Organization Management** | | | | | | | View organization settings | ✔ | ✔ | ✔ | ✔ | ✗ | | Modify organization settings (caching, ssh, etc) | ✔ | ✗ | ✗ | ✗ | ✗ | | Access billing and payments | ✔ | ✗ | ✗ | ✗ | ✗ | | **Analytics & Monitoring** | | | | | | | View usage, runs, logs, and analytics | ✔ | ✔ | ✔ | ✔ | ✗ | | **Cache & Sticky Disk** | | | | | | | View entries and metrics | ✔ | ✔ | ✔ | ✔ | ✗ | | Delete entries | ✔ | ✔ | ✔ | ✗ | ✗ | | **Repository Configuration** | | | | | | | Configure repository settings (PR comments, preferences) | ✔ | ✔ | ✗ | ✗ | ✗ | | Use migration wizard | ✔ | ✔ | ✔ | ✗ | ✗ | Repository access is automatically synced with your GitHub permissions. If you cannot see a repository in Blacksmith, ensure you have at least read access to it in GitHub. For the permission set the Blacksmith GitHub App requests on your organization, see [GitHub App](/blacksmith-administration/github-app). # Scale Apps Source: https://docs.blacksmith.sh/blacksmith-administration/scale-apps Auxiliary GitHub Apps that raise per-org rate-limit headroom for runner provisioning ## Overview Scale Apps are additional GitHub Apps (`blacksmith-sh-scale-1`, `blacksmith-sh-scale-2`, `blacksmith-sh-scale-3`) that you can install alongside the primary Blacksmith GitHub App. Each one gives Blacksmith additional GitHub API rate-limit budget, so that runner provisioning keeps up during high-volume CI activity without tripping GitHub's secondary rate limit. ## What they are used for Scale Apps have a deliberately narrow scope. Blacksmith uses Scale App tokens **only to provision and deprovision GitHub Actions runners** on your organization. Every other GitHub API call Blacksmith makes (webhooks, repository metadata, PR comments from features like [Test Analytics](/blacksmith-observability/test-analytics), and so on) goes through the primary Blacksmith GitHub App. Scale Apps are never used to read your code, write to your repositories, or act on pull requests or issues. ## Permissions Each Scale App requests a single organization permission: **self-hosted runners: read & write**. It does not request any other permissions, so it cannot read your source code, see your secrets, or interact with pull requests, issues, or workflows. You can confirm the exact permission set on the GitHub App listing before installing. ## Installing Scale Apps When your org hits GitHub's secondary rate limit, the Blacksmith dashboard shows org admins a notification suggesting they install the next available Scale App. To install one, open its GitHub App page and pick the organization to install it on: * [github.com/apps/blacksmith-sh-scale-1](https://github.com/apps/blacksmith-sh-scale-1) * [github.com/apps/blacksmith-sh-scale-2](https://github.com/apps/blacksmith-sh-scale-2) * [github.com/apps/blacksmith-sh-scale-3](https://github.com/apps/blacksmith-sh-scale-3) Install them one at a time as your rate-limit pressure grows. No workflow changes are required, and uninstalling a Scale App at any time is safe; it just gives back the extra headroom. If you have questions about Scale Apps or want help deciding how many to install, reach out through the [support console](https://app.blacksmith.sh/?support=open). # Bazel Build Caching Source: https://docs.blacksmith.sh/blacksmith-caching/bazel-build-caching Blacksmith transparently caches your Bazel build artifacts with zero configuration ## Overview Blacksmith transparently caches your Bazel build artifacts across jobs in a repository, with zero code changes required. There are no `.bazelrc` changes to make, no workflow configuration to set up, and no need for a third-party remote cache provider like EngFlow or BuildBuddy. ## What Bazel build caching speeds up Bazel breaks a build into individual actions. When an action's inputs have not changed, Blacksmith returns its saved outputs instead of making Bazel run it again. This can skip expensive work such as: * Compiling source files * Running cacheable tests * Generating code * Linking and packaging binaries The first build fills the cache, and later builds reuse everything that is still valid. Changes to source files, build flags, or toolchains will miss, as expected. ## Enable Bazel build caching An organization admin can enable Bazel build caching from [**Settings > Features**](https://app.blacksmith.sh/settings?tab=features) in the Blacksmith dashboard. Find **Bazel Build Caching** under **Caching**. ### Existing remote cache setups You don't need to change your workflow or `.bazelrc`, since Blacksmith configures Bazel before the job starts. The exception is an explicit remote cache: if your `.bazelrc` or workflow sets its own `--remote_cache` (for example, a remote caching solution like EngFlow or BuildBuddy), that configuration takes precedence, so remove its `--remote_cache` settings and credentials for Blacksmith's cache to take effect. Blacksmith replaces remote caching, not remote execution, so if you also rely on a provider for remote execution, contact us through the [Blacksmith support portal](https://app.blacksmith.sh/?support=open) first. ## Caching across branches Each repository has its own Bazel cache. Unlike the Actions cache, Bazel cache entries do not use branch-protection boundaries. Matching build artifacts are shared across branches and pull requests within that repository, so a build on `main` can warm the cache for a later pull request. Bazel only reuses an artifact when its action key matches. Caches are also separated by CPU architecture. ## Storage limits and deletion Each repository cache has a storage cap, shown alongside current usage on the [Cache page](https://app.blacksmith.sh/cache). When a cache grows past its cap, Blacksmith evicts the least recently used action results and their artifacts. If your working set regularly exceeds the cap, builds will see more cache misses. You can clear a repository's cache from the Cache page at any time, and the next Bazel job starts fresh. Disabling Bazel build caching deletes the existing cache. ## Measure the impact Open the [Cache page](https://app.blacksmith.sh/cache), choose a repository, then open the **Bazel** tab to see cache hit rate, build duration, storage usage, and recent jobs using the cache. The first few builds generally populate the cache, so look at how hit rate and build duration change across later runs. Hit rate shows how often Bazel reused previous work; build duration shows whether those hits made the workflow meaningfully faster. Bazel also reports remote cache hits in the process summary at the end of each build: ```text theme={"system"} INFO: 7 processes: 3 remote cache hit, 4 linux-sandbox. ``` Here, Bazel reused three action outputs and ran four actions locally. See Bazel's guide to [checking remote cache hits](https://bazel.build/remote/cache-local) for deeper troubleshooting. # Actions Source: https://docs.blacksmith.sh/blacksmith-caching/dependencies-actions Blacksmith automatically caches your dependencies to speed up your workflows ## Overview When you run jobs on Blacksmith, all official GitHub and popular third-party cache actions transparently interact with our 4x faster, colocated cache, instead of GitHub's backend. **Zero code changes are required.** ```yml actions-cache@v5 icon="code" lines theme={"system"} # If it's running on Blacksmith, it will use our cache name: Cache Cargo dependencies uses: actions/cache@v5 ``` ```yml actions-cache-save@v5 icon="code" lines theme={"system"} # If it's running on Blacksmith, it will use our cache name: Save cache uses: actions/cache/save@v5 with: path: node_modules key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} ``` ```yml actions-cache-restore@v5 icon="code" lines theme={"system"} # If it's running on Blacksmith, it will use our cache name: Restore cache uses: actions/cache/restore@v5 with: path: node_modules key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} ``` ```yml setup-go@v6 icon="code" lines theme={"system"} # If it's running on Blacksmith, it will use our cache name: Setup go uses: actions/setup-go@v6 with: go-version: '>=1.17.0' ``` ```yml setup-node@v6 icon="code" lines theme={"system"} # If it's running on Blacksmith, it will use our cache name: Setup node uses: actions/setup-node@v6 with: node-version: 20 cache: 'npm' ``` ```yml setup-python@v6 icon="code" lines theme={"system"} # If it's running on Blacksmith, it will use our cache name: Setup python uses: actions/setup-python@v6 with: python-version: '3.9' cache: 'pip' ``` ```yml setup-ruby@v1 icon="code" lines theme={"system"} # If it's running on Blacksmith, it will use our cache name: Setup ruby uses: ruby/setup-ruby@v1 with: ruby-version: '3.3' bundler-cache: true ``` ```yml setup-java@v5 icon="code" lines theme={"system"} # If it's running on Blacksmith, it will use our cache name: Setup java uses: actions/setup-java@v5 with: distribution: 'temurin' java-version: '21' ``` Currently, the Rust `sccache` and the GitHub Actions cache option in the `docker/build-push-action` are still redirected to GitHub's backend. For 40x faster Docker builds, please use our Blacksmith Docker actions. For more information, refer to the [Docker builds](/blacksmith-caching/docker-builds) page. ## Basics GitHub’s cache action stores artifacts in Azure Blob Storage. When your runner isn’t in the same availability zone, downloads are often slow and unreliable. Blacksmith fixes this by storing cache artifacts in the same datacenter as your runners. Our approach removes network latency and almost saturates the NIC. As a result, your downloads complete around 4x faster, with no code changes required. ### Branch Protected Caches When using our colocated cache, each cache entry will be scoped to its branch or tag to ensure cache entries are only accessible to the appropriate workflow runs. This enhances the security of our cache offering by creating a logical boundary between cache artifacts. These access restrictions are consistent with [GitHub's implementation](https://docs.github.com/en/actions/reference/dependency-caching-reference#restrictions-for-accessing-a-cache). If you would rather share cache artifacts across branches in a repository, you can toggle this feature `off` in the settings page of your Blacksmith dashboard. ### Managing cache entries You can browse and delete cache entries from the repository's cache page in the Blacksmith dashboard, or from the terminal with the [Blacksmith CLI](/blacksmith-cli/cache) (`blacksmith cache list | delete | clear`). ### Opt out If you’d rather not use our cache for any reason, just let us know by opening a [support ticket](https://app.blacksmith.sh/?support=open) and we’ll disable it for you. ## Pricing There is no additional cost for using our cache. For all other pricing, please visit our [pricing page](https://www.blacksmith.sh/pricing). ## FAQ By default, we provide 25GB of free storage per repo per week, a substantial increase from GitHub's 10GB to maximize your cache hits. If you'd like us to increase the allowed cache size for your organization, contact us at [support@blacksmith.sh](mailto:support@blacksmith.sh). Like GitHub, our cache evicts the least recently used cache entries that were last accessed more than 7 days ago. Our `useblacksmith/cache` action and all language-specific cache actions (e.g. `useblacksmith/setup-go`, `useblacksmith/setup-node`, `useblacksmith/setup-python`, `useblacksmith/setup-ruby`, `useblacksmith/setup-java`, `useblacksmith/rust-cache`, etc.) are archived and will no longer be maintained by Blacksmith. Our [new cache](/blacksmith-caching/dependencies-actions) requires no code changes and works automatically with GitHub's native cache actions. We recommend migrating any workflows still referencing `useblacksmith/*` cache forks to the upstream versions of those actions. # Sticky Disks Source: https://docs.blacksmith.sh/blacksmith-caching/dependencies-sticky-disks Blacksmith optionally offers Sticky Disks to speed up your workflows ## Overview [useblacksmith/stickydisk](https://github.com/useblacksmith/stickydisk) is a GitHub Action that helps persist state written to disk across jobs. This action can serve as a superior alternative to the Actions cache, especially when the cache artifacts are extremely large. Each sticky disk is hot-loaded into the runner and mounted at the specified path. The sticky disk is formatted as an ext4 filesystem. ## Basics ### Cache Performance Comparison | Caching Solution | Cache Size | Average Download Speed | Time to Access | | -------------------- | ---------- | ---------------------- | -------------- | | GitHub Actions Cache | 6GB | 90 MB/s | \~1m6s | | Blacksmith Cache | 6GB | 400 MB/s | \~15s | | Sticky Disks | 6GB | N/A | 3 seconds | Note that Sticky Disks can use much more than 6 GB of space - these numbers are simply a performance comparison. ### Use Cases #### NPM Package Caching Node.js projects can have extensive dependency trees, leading to large `node_modules` directories. Sticky disks provide persistent, high-performance storage for your NPM packages. ```yml Diff Example icon="code" lines theme={"system"} jobs: build: runs-on: blacksmith # [!code ++] steps: - uses: actions/checkout@v6 - name: Setup Node.js uses: useblacksmith/setup-node@v5 # [!code ++] with: node-version: '18.x' - name: Mount NPM Cache uses: useblacksmith/stickydisk@v1 # [!code ++] with: key: ${{ github.repository }}-npm-cache path: ~/.npm - name: Mount node_modules uses: useblacksmith/stickydisk@v1 # [!code ++] with: key: ${{ github.repository }}-node-modules path: ./node_modules - name: Install Dependencies run: npm ci - name: Build run: npm run build ``` ### How it works Blacksmith stores sticky disk artifacts in a secure, highly performant Ceph cluster, running on local NVMe drives. Our runners proxy their requests through our Storage Agents to interact with the Ceph cluster. Each sticky disk is uniquely identified by a key. When a GitHub Action job requests a sticky disk, the last committed snapshot will be cloned and mounted into the runner at the specified path. Once the job completes, the sticky disk will be unmounted and committed for future invocations. At the moment, customers can use up to 5 sticky disks in a single GitHub Action job. ### Branch protection Sticky disks are shared across all workflow runs in a repository, so by default any job — including one triggered by a `pull_request` — can commit changes that later runs will hydrate from. If you want to protect trusted state from being poisoned by untrusted code, you can enable Branch Protection for sticky disks in the settings page of your Blacksmith dashboard. Every job always works on its own isolated clone of the sticky disk — jobs never share a live disk, and a job's writes only become visible to future runs if its clone is committed as the new snapshot when the job completes. Branch protection controls who gets to commit: when enabled, only jobs triggered by a `push`, `schedule`, or `workflow_dispatch` event on your repository's default branch are committed. All other jobs (such as `pull_request` jobs) still hydrate from the latest trusted snapshot and can use the disk normally during the job, but their clone is discarded at the end — without failing the job. This protection applies to everything backed by sticky disks, including Docker layer caches and git mirrors. ### Using Sticky Disks inside a container If your GitHub Actions job runs inside a container, you will need to ensure that the container is hydrated with certain Blacksmith specific environment variables and is running in privileged mode. These environment variables allow the runner to coordinate with our control plane to hotload and commit the sticky disks used in the workflow. The privileged mode is required for mounting and unmounting block devices inside a container. The following changes can be made to your service container config in the workflow file: ```yml Diff Example icon="code" lines theme={"system"} container: image: mcr.microsoft.com/playwright:v1.41.1 options: --privileged # [!code ++:7] env: VM_ID: ${{ env.VM_ID }} GITHUB_REPO_NAME: ${{ env.GITHUB_REPO_NAME }} BLACKSMITH_STICKYDISK_TOKEN: ${{ env.BLACKSMITH_STICKYDISK_TOKEN }} BLACKSMITH_INSTALLATION_MODEL_ID: ${{ env.BLACKSMITH_INSTALLATION_MODEL_ID }} BLACKSMITH_REGION: ${{ env.BLACKSMITH_REGION }} ``` If the container image does not have `sudo` installed, you will need to install it as a step inside the container. `sudo` is required for mounting and formatting the sticky disk with proper permissions. ```yml theme={"system"} steps: - name: Install sudo run: | apk add --no-cache sudo ``` Without these steps, you will see a `401` error, an `Unauthenticated` error, or permission-related errors when attempting to mount or use the sticky disk. ## useblacksmith/stickydisk-delete [useblacksmith/stickydisk-delete](https://github.com/useblacksmith/stickydisk-delete) allows you to delete sticky disks programmatically. It supports two deletion methods: ### Delete by Key Delete a specific sticky disk using its key: ```yml theme={"system"} - name: Delete sticky disk uses: useblacksmith/stickydisk-delete@v1 with: delete-key: my-cache-disk ``` ### Delete Docker Cache Delete Docker build cache for your repository. This should be used in conjunction with `useblacksmith/setup-docker-builder@v1`, which sets up the sticky disk for Docker build caching: ```yml theme={"system"} - name: Delete Docker cache uses: useblacksmith/stickydisk-delete@v1 with: delete-docker-cache: true ``` ### Example: Cleanup After Build ```yml theme={"system"} name: Build with Cleanup on: push jobs: build: runs-on: blacksmith-4vcpu-ubuntu-2204 steps: - name: Create sticky disk for dependencies uses: useblacksmith/stickydisk@v1 with: key: deps-cache path: ~/.npm - uses: actions/checkout@v6 - name: Install and build run: | npm ci npm run build cleanup: runs-on: blacksmith-4vcpu-ubuntu-2204 needs: build if: always() steps: - name: Delete sticky disk uses: useblacksmith/stickydisk-delete@v1 with: delete-key: deps-cache ``` ## Managing sticky disks You can browse and delete sticky disks from the repository's cache page in the Blacksmith dashboard, or from the terminal with the [Blacksmith CLI](/blacksmith-cli/stickydisk) (`blacksmith stickydisk list | delete`). ## Pricing Sticky disks are charged at \$0.50/GB/mo. For pricing details, please visit our [pricing page](https://www.blacksmith.sh/pricing). ## FAQ Sticky disks are automatically evicted after 7 days of inactivity. The "last used" timestamp is updated each time a job mounts the sticky disk. As long as a sticky disk is used at least once within a 7-day window, it will remain available. If no jobs use a sticky disk for 7 consecutive days, it will be automatically purged. # 40x Faster Docker Builds Source: https://docs.blacksmith.sh/blacksmith-caching/docker-builds Blacksmith can cache your Docker layers to speed up your workflows ## Overview Now that you have a Blacksmith runner, you can take advantage of our NVMe-backed cache to persist your Docker layers across CI runs. To enable Docker layer caching, you'll use two Blacksmith actions in your GitHub Actions workflow file. This allows your Docker builds to reuse cached docker layers from previous runs, and only rebuild the layers that have changed. Our [customers have reported](https://www.linkedin.com/feed/update/urn:li:activity:7325661286027919361/) 2x to 40x improvements in build times due to this change. ```yml Diff Example icon="code" lines theme={"system"} name: Set up Docker Buildx uses: docker/setup-buildx-action@v4 # [!code --] uses: useblacksmith/setup-docker-builder@v2 # [!code ++] with: # [!code ++] cache-key: Dockerfile # [!code ++] name: Build and Push Docker Image uses: docker/build-push-action@v7 # [!code --] uses: useblacksmith/build-push-action@v2 # [!code ++] with: push: true tags: user/app:latest cache-from: type=registry,ref=user/app:latest # [!code --] cache-to: type=inline # [!code --] ``` Any external caching that was configured with cache-from and cache-to directives can now be removed. Exported caches (`type=gha`, `type=registry`, `type=inline`) serialize layer blobs on every build and never include the contents of `RUN --mount=type=cache` directories; Blacksmith keeps the builder's state (layers and cache mounts) on a persistent disk instead, so there is nothing to import or export: your builds skip the latency of downloading and uploading the entire cache blob on every run. Once you make this switch, the first Docker run will be an uncached run. Every subsequent run will have the hydrated layer cache mounted into your runners, so you should see several build steps cached from previous runs. The required `cache-key` input identifies the layer cache this build uses; builds with the same key share cached layers across runs. A good default is the Dockerfile being built (e.g., `services/api/Dockerfile`); see [scoping guidance](#scope-the-cache-to-one-build-workload) below for when builds should share a key. When using `useblacksmith/build-push-action` without `useblacksmith/setup-docker-builder`, the runner will use the default builder configured in your environment. However, this builder will not leverage Blacksmith's layer caching nor will it report analytics to the Blacksmith control plane. For a deeper treatment of how Docker build caching works (layer invalidation, cache mounts, backend trade-offs, and measurements), see our blog post on [the physics of Docker build caching](https://www.blacksmith.sh/blog/the-physics-of-docker-build-caching). ## Basics ### Not using the `docker/build-push-action`? If you're not using the `docker/build-push-action` in your workflow, but are instead calling Docker commands directly or are using the `docker/bake-action`, you can still cache your Docker layers by setting up a Blacksmith builder before interacting with Docker. This builder will be hydrated with the layer cache from previous runs and will commit the updated layer cache at the end of the job. ```yml Diff Example icon="code" lines theme={"system"} uses: useblacksmith/setup-docker-builder@v2 # [!code ++] with: # [!code ++] cache-key: Dockerfile # [!code ++] # ... Docker commands in your workflow ... ``` ### Garbage collection The layer cache is kept in check by BuildKit's native garbage collection with a time-based policy: layers that haven't been used for 8 days are automatically cleaned up, while actively used layers are kept regardless of total cache size. No configuration is needed. ### Getting the most out of the layer cache A persistent builder makes caching fast, but how much of each build is cached still depends on your Dockerfile and workflow. The following practices have the largest measured impact: #### Scope the cache to one build workload Builds only benefit from sharing a cache when they actually reuse each other's layers. Unrelated images building against one shared cache evict each other's state and can be slower than not caching at all. The required `cache-key` input on `setup-docker-builder` makes this scope explicit. The unit of scoping is the builder: one cache backs everything a builder instance builds. When each job builds one Dockerfile — the common case — that means one key per Dockerfile, and the Dockerfile's path is a good key. When a single job builds several related Dockerfiles behind one builder (variants of one image, a base image plus images derived from it), they share that job's key; name it after the image set rather than one Dockerfile. Related images that reuse each other's layers can share a key on purpose — it is genuinely unrelated builds that should be kept on separate keys. Use the same key for the same workload across workflows so, for example, release builds reuse layers from CI builds of the same image. #### Order layers by change frequency A changed instruction invalidates its layer and every layer after it. Put expensive, stable steps early and frequently changing content late. The most common form is manifest-first ordering: copy the dependency manifest, install dependencies, and only then copy the source, so the install layer is only rebuilt when the manifest changes. ```dockerfile Example icon="code" lines theme={"system"} COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build ``` #### Use cache mounts for package managers and compilers `RUN --mount=type=cache` directories persist package-manager and compiler state (Go's build cache, cargo's registry and `target/`, pip's wheels, pnpm's store) across builds, so a step that does have to re-run is incremental instead of from scratch. Because Blacksmith persists the whole builder disk, these mounts survive between CI jobs; with export-based backends (`type=gha`, `type=registry`) they are always empty on a fresh runner. ```dockerfile Example icon="code" lines theme={"system"} RUN --mount=type=cache,target=/root/.cache/go-build \ --mount=type=cache,target=/go/pkg/mod \ go build -o /app ./cmd/server ``` #### Push from the builder instead of loading into the daemon If your job pushes the image to a registry, use `push: true` on the build action rather than `load: true` followed by `docker push`. `load: true` exports the image into the local Docker daemon and then reads it back for the push, handling every byte twice; `push: true` streams the image from the builder straight to the registry. ```yml Example icon="code" lines theme={"system"} - uses: useblacksmith/build-push-action@v2 with: push: true # not: load: true + a separate docker push step tags: user/app:latest ``` If you need to inspect the pushed image (e.g., check its size), use `docker buildx imagetools inspect user/app:latest` instead of loading it locally. ### How it works Under the hood, your Docker layer caches are stored on [sticky disks](/blacksmith-caching/dependencies-sticky-disks). #### How caching works in Docker builds When you do a Docker build, each step in your Dockerfile creates a new layer in your Docker image. Without caching, when you make a change to your Dockerfile, Docker will rebuild all the layers in the image, even if only one layer has changed. This can be slow, especially for large Docker images. However, with caching, Docker can reuse layers from previous builds instead of rebuilding them from scratch. Docker will only rebuild from the layer that has changed and use the cached layers for the rest of the image. #### How Blacksmith runners cache your Docker layers When a GitHub Action job uses the Blacksmith Docker actions, the process works as follows: 1. The `setup-docker-builder` action configures a buildx builder with access to cached layers from previous runs 2. The `build-push-action` then uses this builder to run your Docker build, leveraging the cached layers instead of rebuilding everything from scratch 3. At the end of the job, the runner commits its changes to the layer cache for future runs. This commit only runs if no other steps in the job have failed or been canceled. The Docker layer cache is shared by all runners in a repository, in your organization. In case of several concurrent Docker builds, it may take a few runs until all the builds have their layers committed to the cache. This is in keeping with the Last Write Wins (LWW) policy we enforce in the face of concurrent committers. Note that the layer cache is separate from [Docker container caching](/blacksmith-caching/docker-container-caching), which caches the daemon's image store (`/var/lib/docker`) used by `docker pull`, `docker run`, service containers, and `container:` jobs. ### Multi-platform builds #### Current approach: Using a matrix strategy You can build multi-platform Docker images on Blacksmith by using GitHub Actions matrix strategy. This approach leverages Blacksmith's native runners for each architecture to avoid the performance penalties of emulation. ```yml Diff Example icon="code" lines theme={"system"} jobs: build: strategy: matrix: platform: [amd64, arm64] include: - platform: amd64 runner: blacksmith-8vcpu-ubuntu-2204 # [!code ++] docker_platform: linux/amd64 - platform: arm64 runner: blacksmith-8vcpu-ubuntu-2204-arm # [!code ++] docker_platform: linux/arm64 runs-on: ${{ matrix.runner }} steps: - name: Checkout uses: actions/checkout@v6 - name: Setup Docker Builder uses: useblacksmith/setup-docker-builder@v2 # [!code ++] with: # [!code ++] cache-key: Dockerfile # [!code ++] - name: Login to DockerHub uses: docker/login-action@v4 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - name: Build and push Docker image uses: useblacksmith/build-push-action@v2 # [!code ++] with: push: true tags: user/app:${{ matrix.platform }} platforms: ${{ matrix.docker_platform }} ``` This approach runs each architecture build on its native hardware - the amd64 build runs on `blacksmith-8vcpu-ubuntu-2204` and the arm64 build runs on `blacksmith-8vcpu-ubuntu-2204-arm`. Each image is pushed with its own tag that includes the architecture. For ARM builds, this avoids needing to use QEMU to emulate ARM on an amd64 runner, which can be extremely slow. ### Merging images into a multi-arch manifest After building separate images for each architecture, you can merge them into a single multi-arch manifest using Docker's manifest commands: ```yml Diff Example icon="code" lines theme={"system"} jobs: build: # ... matrix strategy builds from above ... merge-manifests: needs: build runs-on: blacksmith # [!code ++] steps: - name: Login to DockerHub uses: docker/login-action@v4 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - name: Create and push multi-arch manifest run: | docker manifest create user/app:latest \ user/app:amd64 \ user/app:arm64 docker manifest push user/app:latest ``` For registries that require explicit annotation of architectures: ```yml Diff Example icon="code" lines theme={"system"} - name: Create and push annotated manifest run: | docker manifest create user/app:latest \ user/app:amd64 \ user/app:arm64 docker manifest annotate user/app:latest user/app:amd64 --arch amd64 docker manifest annotate user/app:latest user/app:arm64 --arch arm64 docker manifest push user/app:latest ``` #### Coming soon: Native multi-platform support In the future, the `useblacksmith/build-push-action` action will support multi-platform builds natively. You'll simply need to specify the platforms you want to build for in the `platforms` input, and Blacksmith will automatically spawn native builders for each platform, eliminating the need for the matrix strategy shown above. ```yml Diff Example icon="code" lines theme={"system"} jobs: build: runs-on: blacksmith-8vcpu-ubuntu-2204 # [!code ++] steps: ... - name: Build and push Docker image uses: useblacksmith/build-push-action@v2 # [!code ++] with: platforms: linux/amd64,linux/arm64 ``` When this feature is available, each image will be built on a native builder (i.e., the amd64 Docker build on a `blacksmith-8vcpu-ubuntu-2204` and the arm64 build on a `blacksmith-8vcpu-ubuntu-2204-arm` runner) and automatically merged into a single multi-arch manifest. #### Security Docker layer caching executes within the same runners that process your GitHub Actions workflows. This means they automatically inherit all security protections and isolations that are detailed in our [security documentation](https://www.blacksmith.sh/security). The BuildKit daemon in each runner (`buildkitd`) that powers Docker builds, runs exclusively on a local Unix socket and is not exposed to the public internet. The Docker layer cache for each repository is stored in a secure Ceph cluster. Every runner gets an ephemeral authentication token that allows it to request and commit artifacts. The runners do not have persistent credentials to the Ceph cluster or direct access to artifacts in the cluster. The Ceph cluster is configured with object-level access controls. ## Pricing Docker build caching is powered by sticky disks and is charged at the same rate of \$0.50/GB/mo. For pricing details, please visit our [pricing page](https://www.blacksmith.sh/pricing). ## FAQ Docker layer caches are stored on [sticky disks](/blacksmith-caching/dependencies-sticky-disks), with a separate sticky disk created per `cache-key`. The sticky disk is automatically evicted after 7 days of inactivity. Each Docker build updates the "last used" timestamp on the sticky disk, so as long as you run at least one Docker build within a 7-day window, your layer cache will remain available. Yes, `useblacksmith/build-push-action@v1` has been deprecated. Please move to the newer approach laid out above. If you were using setup-only refer to [this section](/blacksmith-caching/docker-builds#not-using-the-dockerbuild-push-action). Users can login to the Blacksmith dashboard and navigate to the `Usage & Billing` page to get a breakdown of their current usage. # Faster Container Init Source: https://docs.blacksmith.sh/blacksmith-caching/docker-container-caching Blacksmith caches Docker images across runs to eliminate pull and extraction overhead We are currently rolling out Docker container caching to all organizations, enabled by default. ## Overview Many GitHub Actions workflows use [service containers](https://docs.github.com/en/actions/use-cases-and-examples/using-containerized-services/about-service-containers) to run databases, caches, and other dependencies alongside jobs. Every run, these containers get pulled from a registry and extracted before the job can start. With Docker container caching, the images your workflows use are kept warm across runs. When your workflow starts, the images are already on the runner, so the pull and extraction steps become a no-op. Container caching is not limited to GitHub Actions service containers. Any image pulled during a job — whether through `docker pull`, `docker run`, `docker compose`, or any other Docker command — is automatically cached and available on subsequent runs. ## How it works Docker container caching uses [sticky disks](/blacksmith-caching/dependencies-sticky-disks) to persist Docker's image store across workflow runs. Each organization gets one cache disk per region and architecture (x64 and ARM), shared across all of its repositories. This org-level sharing means a common image only needs to be pulled once, and every workflow in your organization benefits from it. When a job starts, the runner mounts your organization's cache disk as Docker's local image store, so cached images are immediately available — no pull, no extraction. When the job finishes, any newly pulled images are merged back into the shared cache so future jobs can use them. Tagged images, digest-pinned images (`image@sha256:...`), and images pulled by Docker Compose are all cached. Concurrent jobs can safely share the cache: each job works against its own copy-on-write view of the disk, and updates are merged so one job never removes images another job needs. ## Impact The "Initialize containers" step in GitHub Actions is where service containers are pulled and started. With container caching, this step drops from minutes to seconds. The biggest wins come from large or uncommon images, where registry pull and extraction time dominates. Once the cache is warm, pull time drops to near zero. ## Pricing Docker container caching is **free**. Unlike other sticky disk products, you are not billed for the storage used by the container cache. Other sticky disk usage — such as [Docker layer caching](/blacksmith-caching/docker-builds) and [custom sticky disks](/blacksmith-caching/dependencies-sticky-disks) — is billed as before; see our [pricing page](https://www.blacksmith.sh/pricing). ## FAQ Cached images are automatically evicted after 8 days of inactivity. Each time a workflow uses a cached image, its "last used" timestamp resets. As long as your workflows use an image at least once within 8 days, it stays cached. Weekly workflows, releases, and maintenance jobs stay warm. No. Container caching is fully transparent — there are no workflow changes, labels, or actions required. Jobs that don't use containers are unaffected. No. Cache disks are scoped to your organization. Images pulled by your workflows are only ever visible to your organization's jobs. Private images work the same way: your job authenticates and pulls as usual on the first run, and the extracted image is cached on your organization's disk for subsequent runs. # Faster Git Checkouts Source: https://docs.blacksmith.sh/blacksmith-caching/git-checkout-caching Blacksmith can cache your Git repositories to speed up checkouts across runs ## Overview The `useblacksmith/checkout` action is a drop-in replacement for `actions/checkout` that caches git repositories on Blacksmith's [sticky disks](/blacksmith-caching/dependencies-sticky-disks). Instead of cloning your entire repository from GitHub on every workflow run, the action maintains a persistent git mirror that is updated incrementally, only fetching new commits and refs since the last run. ## Why use this **Large repositories that are slow to clone.** If your repo is multiple gigabytes and `git clone` adds minutes to the start of every job, checkout caching cuts that time down by keeping a local mirror on the runner. After the first run, only new commits are fetched, turning a multi-minute clone into a sub-second operation. **Fewer failures from intermittent GitHub outages.** Every object you pull from GitHub is a chance for a transient network error or rate limit to stall your pipeline. Caching the repository locally and only fetching the delta on each run means fewer objects transferred, and fewer chances for something to go wrong. ## Usage Swap `actions/checkout` for `useblacksmith/checkout`. All existing inputs work the same. The only additions are `dissociate` and `verbose`. ```yaml theme={"system"} steps: - uses: useblacksmith/checkout@v1 with: # All standard actions/checkout inputs are supported. # For example: fetch-depth: 0 ``` ### The `dissociate` option By default, the workspace references objects from the mirror via git alternates. This is fast, but means the checkout depends on the mirror mount being accessible. If you're running Docker-based actions that won't have access to the mount, set `dissociate: true` to copy objects into the workspace: ```yaml theme={"system"} steps: - uses: useblacksmith/checkout@v1 with: dissociate: true ``` This makes the checkout self-contained at the cost of a slightly longer checkout time and larger workspace. ## How it works Git checkout caching uses [sticky disks](/blacksmith-caching/dependencies-sticky-disks) to persist a bare git mirror across workflow runs. The checkout process has three phases: 1. **First run (hydration):** The action creates a full `git clone --mirror` of your repository on a sticky disk. This initial clone takes the same time as a regular clone, but it only happens once. 2. **Incremental updates:** On subsequent runs, the mirror is updated with `git fetch --prune` to pull only new refs and objects. The workspace checkout then uses git's [alternates mechanism](https://git-scm.com/docs/gitrepository-layout) to reference objects from the mirror without copying them, so checkout time stays flat no matter how big the repo gets. 3. **Concurrent job handling:** If a hydration is still in progress when another job starts, the action automatically falls back to a standard `actions/checkout` clone. Once the mirror is ready, all subsequent jobs use it. Cache failures are always safe. If the mirror or sticky disk is unavailable for any reason, the action falls back to a standard clone from GitHub and your workflow continues normally. ## Monitoring usage You can see storage usage for your git mirror sticky disk on the [Sticky Disks page](https://app.blacksmith.sh/sticky-disks) in the Blacksmith dashboard. ## Pricing Git checkout caching is powered by sticky disks and charged at \$0.50/GB/mo. For details, see our [pricing page](https://www.blacksmith.sh/pricing). ## FAQ Git mirror caches are stored on [sticky disks](/blacksmith-caching/dependencies-sticky-disks) and are automatically evicted after 7 days of inactivity. Each time a workflow uses the cached mirror, the "last used" timestamp resets. As long as your workflows run at least once within 7 days, the mirror stays available. Yes. The mirror always stores a complete clone, but your workspace respects the `fetch-depth` input. Git's alternates mechanism lets a shallow workspace reference objects from the full mirror without downloading them again. The action falls back to a standard clone from GitHub. Cache failures never break your workflow. They just mean that particular run won't benefit from caching. No. Garbage collection (`git gc --prune=now`) runs in the post-job cleanup phase, after all your workflow steps have completed. This keeps checkout fast and avoids impacting your build. # Cache Source: https://docs.blacksmith.sh/blacksmith-cli/cache List and delete cache entries from the terminal The `blacksmith cache` commands let you inspect and clean up a repository's cache data programmatically. This is especially useful for repositories with many generated or parameterized cache keys. ## Permissions Listing requires the user who created the CLI token to be able to see the target repository on GitHub (any permission level, including read) — the same visibility rule the dashboard enforces. Deleting (`delete` and `clear`) additionally requires the user who created the CLI token (via `blacksmith auth login`) to have **write access** to the target repository on GitHub (the `WRITE`, `MAINTAIN`, or `ADMIN` role) — the same rule the dashboard enforces. Tokens not tied to a user account cannot delete; re-authenticate with `blacksmith auth login` to mint a token tied to your account. [Organization tokens](/blacksmith-cli/overview#token-types) are exempt from these per-repository checks and can list and delete for any repository in the organization. Two kinds of cache entries are surfaced, distinguished by the `type` field in list output: | Type | What it is | | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | | `actions` | GitHub Actions cache entries (from `actions/cache` and Blacksmith's transparent caching). One row per key/version/scope variant. | | `bazel` | Bazel remote build cache namespaces. One row per build tool and architecture, with `size_bytes` reflecting the namespace's storage footprint. | ## `blacksmith cache list` Lists cache entries for a repository. ```bash theme={"system"} blacksmith cache list --repo my-org/my-repo --format table ``` ``` TYPE KEY VERSION SIZE_MB ARCH SCOPE TRANSPARENT LAST_USED_AT actions node-modules-a1b2c3 f00dfeed 412.3 amd64 main false 2026-08-19T18:02:11Z actions setup-go-1.25-linux-x64 cafebabe 88.1 amd64 true 2026-08-19T14:40:03Z bazel bazel 3 10240.0 amd64 false 2026-08-19T11:19:45Z ``` | Flag | Description | | :--------------------- | :-------------------------------------------------------------------------------------------------- | | `--repo` | Repository (owner/name or bare name). Required. | | `--search` | Filter to cache keys containing this substring. | | `--sort-by` | Sort column: `key`, `version`, `size`, `last_used_at`, `arch`, `scope`. Defaults to `last_used_at`. | | `--sort-direction` | `asc` or `desc`. Defaults to `desc`. | | `--page`, `--per-page` | Pagination (per-page 1-100, default 50). | | `--format` | `json`, `table`, or `yaml`. Defaults to `json`. | ## `blacksmith cache delete` Deletes all Actions cache entries for a repository that exactly match `--key`. By default every version, scope, and transparent-cache variant of the key is deleted; narrow the selection with the optional filters. ```bash theme={"system"} blacksmith cache delete --repo my-org/my-repo --key node-modules-a1b2c3 ``` | Flag | Description | | :-------------------- | :----------------------------------------------------------------------- | | `--repo` | Repository (owner/name or bare name). Required. | | `--key` | Exact cache key to delete. Required. | | `--version` | Restrict deletion to one cache version. | | `--scope` | Restrict deletion to one branch scope. Pass `null` for unscoped entries. | | `--transparent-cache` | Restrict deletion to transparent (`true`) or regular (`false`) entries. | | `--yes` | Skip the confirmation prompt. | ## `blacksmith cache clear` Deletes all Actions cache entries for a repository. ```bash theme={"system"} blacksmith cache clear --repo my-org/my-repo --yes ``` | Flag | Description | | :------- | :---------------------------------------------- | | `--repo` | Repository (owner/name or bare name). Required. | | `--yes` | Skip the confirmation prompt. | `delete` and `clear` operate on `actions` cache entries. Bazel cache namespaces are listed for visibility, but their storage is managed automatically by Blacksmith's server-side LRU retention and cannot be deleted through the CLI. # Jobs Source: https://docs.blacksmith.sh/blacksmith-cli/jobs Inspect job runs and aggregate CPU/memory metrics The `blacksmith jobs` commands expose the same job observability data as the dashboard: recent runs, logs, workflow steps, structured test timings, per-run CPU/memory/OOM metrics, and cross-run aggregates. ## `blacksmith jobs list` Browse recent job runs for your organization. Returns one row per completed job with labels, runner SKU, duration, billable minutes, conclusion, and the GitHub job URL. ```bash theme={"system"} blacksmith jobs list --repo my-org/my-repo --conclusion failure --since 7d --format table ``` | Flag | Description | | :-------------------- | :------------------------------------------------------------ | | `--repo` | Filter by repository (owner/name or bare name). | | `--workflow` | Filter by workflow name. | | `--job-name` | Filter by job name (exact match). | | `--runner-label` | Filter by runner SKU (e.g. `blacksmith-8vcpu-ubuntu-2204`). | | `--conclusion` | `success`, `failure`, `cancelled`, `skipped`, or `timed_out`. | | `--since` | Lookback window: `24h`, `7d`, `14d`, `30d`. | | `--limit`, `--cursor` | Pagination. | The numeric GitHub job ID in the output is the handle for the per-job commands below. ## Per-job inspection | Command | Description | | :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | | `blacksmith jobs logs ` | Fetch a job's logs. Filter with `--step`, `--search`, or fetch container logs with `--source-type`/`--source-name`. | | `blacksmith jobs steps ` | List workflow steps with line counts and timestamps. | | `blacksmith jobs tests ` | Structured test timings (JUnit or auto-parsed), slowest first. | | `blacksmith jobs containers ` | Docker service containers that ran alongside the job. | | `blacksmith jobs stats ` | Full per-run metrics: CPU utilization timeseries with p50/p90/p95/p99, memory timeseries, and OOM events. | | `blacksmith jobs thread-profiles ` | Per-thread scheduling snapshots (D-state debugging). | ```bash theme={"system"} blacksmith jobs logs 12345678 --step "Run tests" --search "FAILED" ``` ## Cross-run analysis ### `blacksmith jobs aggregate` Cross-run CPU/memory percentiles grouped by `(repo, workflow, job_name, runner_label)`: run counts, CPU average and busy-fraction percentiles, peak-memory percentiles, OOM totals, duration percentiles, and billable minutes. ```bash theme={"system"} blacksmith jobs aggregate --repo my-org/my-repo --group-by workflow,job_name --since 14d ``` ### `blacksmith jobs sample` Returns one representative run per percentile (min / p25 / p50 / p75 / p90 / max by default) along a chosen axis — `duration`, `cpu_avg`, `cpu_busy_frac_80`, `mem_peak_pct`, `billable_minutes`, or `oom_events` — each with a clickable `job_url`. ```bash theme={"system"} blacksmith jobs sample --workflow ci.yml --axis duration ``` ### `blacksmith jobs diagnose rightsize` Right-sizing recommendations: scale-up / scale-down runner SKU candidates with confidence scores and estimated savings. # Logs Source: https://docs.blacksmith.sh/blacksmith-cli/logs Search and analyze CI logs across your organization from the terminal ## `blacksmith logs` Organization-wide log search and analysis over all your CI logs, using the Blacksmith query language: ``` error substring match in message "connection refused" exact phrase match level:error filter by log level (error, warn, info, debug) repo:my-org/my-repo filter by repository workflow:ci.yml filter by workflow file branch:main filter by branch job_name:test filter by job name step_name:"Run tests" filter by step name pr:42 filter by pull request number -error exclude lines matching 'error' error AND timeout both must match (error OR warn) AND db grouping with parentheses ``` ### `blacksmith logs search` Full-text log search returning matching lines with metadata (repo, workflow, job, step, branch). Cursor-paginated. ```bash theme={"system"} blacksmith logs search --query 'level:error repo:my-org/my-repo "connection refused"' --since 24h ``` ### `blacksmith logs histogram` Time-bucketed log counts broken down by level. Useful as a first pass to identify windows with elevated error rates before drilling in with `search`. ```bash theme={"system"} blacksmith logs histogram --query 'level:error' --since 7d ``` Both support `--since` (`1h`, `6h`, `24h`, `7d`, `14d`, `30d`) or absolute `--start-time`/`--end-time` RFC3339 ranges. # Overview Source: https://docs.blacksmith.sh/blacksmith-cli/overview Allow your agents to access Blacksmith usage data through the terminal The Blacksmith CLI lets you and your coding agents inspect and manage your Blacksmith organization from the terminal: search CI logs, inspect job runs and their CPU/memory metrics, manage [Actions and Bazel caches](/blacksmith-cli/cache), manage [sticky disks](/blacksmith-cli/stickydisk), report usage, and run CI against local changes with [Testboxes](/blacksmith-cli/testbox). ## Installation ```bash theme={"system"} curl -fsSL https://get.blacksmith.sh | sh ``` The CLI auto-updates in the background on every invocation. You can also update explicitly: ```bash theme={"system"} blacksmith update ``` Set `BLACKSMITH_DISABLE_AUTO_UPDATE=1` to disable all automatic CLI updates. You can still update explicitly with `blacksmith update`. ## Authentication ```bash theme={"system"} blacksmith auth login ``` This opens a browser for the OAuth flow and saves a token to `~/.blacksmith/credentials`. You only need to do this once per machine. Tokens are scoped to an organization. If you're authenticated with multiple organizations, select one with the `--org` flag or the `BLACKSMITH_ORG` environment variable. Check your authentication state with: ```bash theme={"system"} blacksmith auth status ``` ### Token types `blacksmith auth login` mints a **user token** tied to your GitHub identity. Its permissions mirror yours: [Testbox](/blacksmith-cli/testbox) warmup requires write access to the repository, reads require repository access, and you only see and manage your own testboxes. Cache and sticky disk reads require repository access; deletes require write access. Organization admins can mint an **organization token** for machine agents (Cursor Cloud agents, CI bots) that need access across the whole organization: ```bash theme={"system"} blacksmith org-token create --label cursor-cloud ``` This opens a browser to verify you're an org admin, then prints the token once — it is never shown again. Org tokens can warm up testboxes on any installed repository, see and shut down all testboxes, and manage all cache entries and sticky disks. Manage them with `blacksmith org-token list` and `blacksmith org-token revoke `. Don't hand agents a copy of `~/.blacksmith/credentials` from a human login — that token is tied to that person's permissions and lifecycle. Mint an org token instead. For non-interactive environments (CI, scripts, agents), pass a token directly: ```bash theme={"system"} blacksmith auth login --api-token - --non-interactive --organization ``` ## Command groups | Command | Description | | :----------------------------------------------------------------------- | :----------------------------------------------------------- | | [`blacksmith cache`](/blacksmith-cli/cache) | List and delete Actions and Bazel cache entries | | [`blacksmith stickydisk`](/blacksmith-cli/stickydisk) | List and delete sticky disks | | [`blacksmith jobs`](/blacksmith-cli/jobs) | Inspect job runs and aggregate CPU/memory metrics | | [`blacksmith logs`](/blacksmith-cli/logs) | Search and analyze CI logs across your organization | | [`blacksmith usage`](/blacksmith-cli/usage) | Pull usage and cost data for billing and cost reporting | | [`blacksmith runners`](/blacksmith-cli/usage#blacksmith-runners-catalog) | Inspect Blacksmith runner SKUs and catalog metadata | | [`blacksmith testbox`](/blacksmith-cli/testbox) | Run CI against local changes, instantly | | `blacksmith auth` | Manage authentication | | `blacksmith org-token` | Mint, list, and revoke organization tokens (org admins only) | | `blacksmith update` | Update the CLI to the latest version | Most commands support `--format json | table | yaml` for output. JSON is the default, which makes the CLI easy to compose with tools like `jq` and easy for coding agents to consume. # Sticky disks Source: https://docs.blacksmith.sh/blacksmith-cli/stickydisk List and delete sticky disks from the terminal The `blacksmith stickydisk` commands let you inspect and delete a repository's [sticky disks](/blacksmith-caching/dependencies-sticky-disks) programmatically. ## Permissions Listing requires the user who created the CLI token to be able to see the target repository on GitHub (any permission level, including read) — the same visibility rule the dashboard enforces. For org-scoped sticky disks (such as container caching), access to any repository in the organization suffices for listing. Deleting additionally requires the user who created the CLI token (via `blacksmith auth login`) to have **write access** to the target repository on GitHub (the `WRITE`, `MAINTAIN`, or `ADMIN` role) — the same rule the dashboard enforces. For org-scoped sticky disks (such as container caching), write access to any repository in the organization suffices. Tokens not tied to a user account cannot delete; re-authenticate with `blacksmith auth login` to mint a token tied to your account. [Organization tokens](/blacksmith-cli/overview#token-types) are exempt from these per-repository checks and can list and delete for any repository in the organization. ## `blacksmith stickydisk list` Lists sticky disks for a repository. ```bash theme={"system"} blacksmith stickydisk list --repo my-org/my-repo --format table ``` ``` KEY TYPE SIZE_MB ARCH REGION LAST_USED_AT my-org/my-repo dockerfile 8192.0 amd64 us-east-1 2026-08-19T18:02:11Z my-org/my-repo-bazel-cache stickydisk 4096.0 arm64 us-east-1 2026-08-19T14:40:03Z ``` | Flag | Description | | :--------------------- | :------------------------------------------------------------------------------------------------ | | `--repo` | Repository (owner/name or bare name). Required. | | `--search` | Filter to sticky disk keys containing this substring. | | `--sort-by` | Sort column: `key`, `type`, `size`, `last_used_at`, `arch`, `region`. Defaults to `last_used_at`. | | `--sort-direction` | `asc` or `desc`. Defaults to `desc`. | | `--page`, `--per-page` | Pagination (per-page 1-100, default 50). | | `--format` | `json`, `table`, or `yaml`. Defaults to `json`. | ## `blacksmith stickydisk delete` Deletes all sticky disks for a repository that exactly match `--key`. By default every architecture variant of the key is deleted; narrow the selection with `--arch`. ```bash theme={"system"} blacksmith stickydisk delete --repo my-org/my-repo --key my-org/my-repo-bazel-cache ``` | Flag | Description | | :------- | :------------------------------------------------------------- | | `--repo` | Repository (owner/name or bare name). Required. | | `--key` | Exact sticky disk key to delete. Required. | | `--arch` | Restrict deletion to one architecture (e.g. `amd64`, `arm64`). | | `--yes` | Skip the confirmation prompt. | Deleting a sticky disk is safe: the next job that requests the key starts from an empty disk and repopulates it, the same as a cold cache. # Testbox Source: https://docs.blacksmith.sh/blacksmith-cli/testbox Testbox CLI commands and flags Testboxes are in early beta. The interface and behavior may change as we iterate. ## `blacksmith testbox warmup` Dispatches a testbox and returns an ID immediately. Required before any `run` command. ``` Usage: blacksmith testbox warmup [flags] Flags: --idle-timeout int Idle timeout in minutes (default 30) --job string Job name within the workflow --ref string Git ref to dispatch against (default: repo's default branch) --ssh-public-key string SSH public key to install on the testbox ``` | Flag | Description | | :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | | `--idle-timeout` | Minutes of inactivity before the testbox is automatically stopped. Defaults to 30. | | `--job` | Specific job within the workflow to run. Useful when the workflow defines multiple jobs. | | `--ref` | Git ref (branch, tag, SHA) to dispatch the workflow against. Defaults to the repo's default branch. | | `--ssh-public-key` | Path to an SSH public key to install on the testbox. When omitted, a keypair is auto-generated and cached at `~/.blacksmith/testboxes/{id}/`. | The returned testbox ID is the handle for all subsequent commands. ```bash theme={"system"} blacksmith testbox warmup blacksmith-testbox.yml # → tbx_01jkz5b3t9n8qr4xvwy0g6m2h1 blacksmith testbox warmup blacksmith-testbox.yml --ref feature/auth --job test-backend # → tbx_01jkz6a2m4p7rs5ywx0h8n3c4d ``` ## `blacksmith testbox run` Syncs local changes and executes a command on the testbox. If the testbox is still hydrating, the command blocks until the testbox is ready. ``` Usage: blacksmith testbox run --id "" [flags] Flags: --debug Show detailed sync timing information --id string Testbox ID from warmup --ssh-private-key string Path to SSH private key (use when warmup was called with --ssh-public-key) ``` | Flag | Description | | :------------------ | :----------------------------------------------------------------------------------------- | | `--id` | Testbox ID returned by `warmup`. Required. | | `--debug` | Prints detailed rsync timing and transfer statistics. | | `--ssh-private-key` | Path to the SSH private key. Only needed when `warmup` was called with `--ssh-public-key`. | File sync uses `rsync --delete --checksum` to mirror the local working tree to the testbox. Deleted files locally are also removed on the testbox, so it always matches your local state exactly. The command exits with the remote command's exit code, so agents can check it directly for pass/fail. ```bash theme={"system"} blacksmith testbox run --id tbx_01jkz5b3t9... "npm test" blacksmith testbox run --id tbx_01jkz5b3t9... "go test ./pkg/api/... -run TestHandler -v" blacksmith testbox run --id tbx_01jkz5b3t9... "cd backend && php artisan test --filter=HealthCheckTest" blacksmith testbox run --id tbx_01jkz5b3t9... "python -m pytest tests/test_api.py -k test_auth" ``` ## `blacksmith testbox status` Shows the current status of a testbox. Supports `--wait` to block until the testbox is ready. ``` Usage: blacksmith testbox status [flags] Flags: --id string Testbox ID to look up --wait Block until the testbox is ready --wait-timeout string Maximum time to wait (e.g., 5m, 10m, 1h) (default "5m") ``` | Flag | Description | | :--------------- | :------------------------------------------------------------ | | `--id` | Testbox ID returned by `warmup`. Required. | | `--wait` | Block until the testbox reaches `ready` status. | | `--wait-timeout` | Maximum duration to wait before timing out. Defaults to `5m`. | Testbox statuses progress through: `queued` → `hydrating` → `ready` → `completed`. ## `blacksmith testbox stop` Stops a running testbox and cancels the underlying GitHub Actions run. ``` Usage: blacksmith testbox stop --id [flags] Flags: --id string Testbox ID to stop ``` ## `blacksmith testbox init` Interactive onboarding TUI. Sets up a testbox workflow and agent skill for the current repository. The init command: 1. Scans the repo's `.github/workflows/` for workflow files 2. Prompts the user to select a workflow and job that has the dependencies and services they need 3. Uses AI to transform the workflow into a testbox-compatible version (strips test execution, keeps setup, adds testbox actions) 4. Writes `.github/workflows/blacksmith-testbox.yml` and an agent skill file 5. Optionally creates a PR The generated workflow is a `workflow_dispatch`-only workflow containing only setup steps, no test execution. The generated skill file teaches agents how to use Testbox in this repository. ## Authentication Testbox commands require authentication. See the [CLI overview](/blacksmith-cli/overview) for installation and `blacksmith auth login`. With a user token, testbox permissions follow your GitHub permissions: `warmup` requires write access to the repository, and you can only list, inspect, and shut down your own testboxes. Organization tokens (see [token types](/blacksmith-cli/overview#token-types)) can warm up testboxes on any installed repository and manage all testboxes in the organization — use them for shared machine agents. # Usage and cost reporting Source: https://docs.blacksmith.sh/blacksmith-cli/usage Pull your Blacksmith usage and cost data programmatically for billing and cost reporting workflows The Blacksmith CLI is the programmatic way to pull your organization's usage and cost data: billable minutes, estimated spend, and storage costs, broken down by day, repository, workflow, job, or runner type. Every command outputs JSON by default, so you can pipe results into `jq`, spreadsheets, dashboards, or your internal cost reporting and chargeback workflows without scraping the dashboard. For scripts and CI, authenticate with an [organization token](/blacksmith-cli/overview#token-types) instead of a personal login. ## `blacksmith usage` Billing-oriented Actions usage for the authenticated organization: jobs, billable minutes, billing minutes, runtime minutes, estimated cost, daily totals, and requested breakdowns. ```bash theme={"system"} blacksmith usage --since 30d --breakdown-by runner_type,repo --format table ``` | Flag | Description | | :----------------------------------------------------- | :----------------------------------------------------------------------------- | | `--since` | Relative time range: `24h`, `7d`, `30d`, `90d`. Defaults to `30d`. | | `--start-time`, `--end-time` | Absolute RFC3339 time range. | | `--breakdown-by` | CSV subset of `day`, `runner_type`, `repo`, `workflow`, `job`, `workflow_job`. | | `--repo`, `--workflow`, `--job-name`, `--runner-label` | Filters. | ### `blacksmith usage storage` Sticky disk storage usage for a time range: current/peak/average GB, GB-hours, and estimated cost from the hourly storage billing ledger. ```bash theme={"system"} blacksmith usage storage --since 30d --breakdown-by repo,type ``` ## `blacksmith runners catalog` Lists every Blacksmith runner SKU as a deterministic table of metadata: label, vCPUs, memory, architecture, OS, and cost per minute. ```bash theme={"system"} blacksmith runners catalog --format table ``` # CI Analytics Source: https://docs.blacksmith.sh/blacksmith-observability/dashboard Fastest way to monitor your GitHub Actions performance and costs across your team ## Overview Blacksmith provides detailed analytics for your CI pipeline's **performance**, **failure rate** and **costs** on the [GitHub Actions analytics page](https://app.blacksmith.sh/analytics). ## Basics ### Jobs The dashboard displays every job run across all your repositories. Jobs View You can filter and analyze jobs by repository, runner size, job status, and more, enabling you to answer questions like: * "What is the failure rate of my jobs?" * "How long does this job typically take to complete?" * "What is affecting the performance of my slowest job?" For instance, Blacksmith's dashboard helps identify if a job is failing more often than usual. By filtering jobs by repository, you can assess failure rates and compare them to previous months. Jobs Zoom In Blacksmith's dashboard helps identify what is affecting the performance of your slowest job. By hovering over the "p99" in the job duration distribution chart, you can see a breakdown of your slowest job's steps and the time taken for each step. Jobs Zoom In ### Caches The dashboard also provides insights into cache performance for your jobs. Cache View You can filter and analyze cache entries by repository, cache key, last hit time, and more, to answer questions like: * "What is my total cache usage?" * "What cache entries are currently available?" * "How many recent cache hits have I had?" Blacksmith makes it simple to track when a cache key was last hit. You can filter by repository to check the last hit time of cache entries, ensuring the cache key is functioning as expected. Cache Zoom In ### Costs The usage [view](https://app.blacksmith.sh/usage?tab=usage) provides visibility into usage and costs. Costs View You can break down costs by repository to better understand CI expenses and ask questions such as: * "How much more did I spend this month?" * "Which repositories are consuming the most resources?" * "How much am I spending on storage for caches?" With Blacksmith you can track spending across repositories to identify how your teams and services are consuming compute and storage resources. Costs Zoom In We are continuously working on additional visualizations. If there is something specific you'd like to see, feel free to reach out to us at [hello@blacksmith.sh](mailto:hello@blacksmith.sh). ## Pricing There is no additional cost for using this feature. For all other pricing, please visit our [pricing page](https://www.blacksmith.sh/pricing). # Run History Source: https://docs.blacksmith.sh/blacksmith-observability/history Fastest way to search, filter, and debug past CI runs on Blacksmith runners Job view interface ## Overview The Run History page is your central hub for searching, filtering, and debugging all CI workflows and jobs across Blacksmith runners. Whenever you’re tracking down who introduced a bug or checking whether a recent change caused a failure, the Run History page helps you find answers quickly. ## Basics Go to the **Workflow/Jobs** page and click on a job run to see its details. From there, you can view logs, compare runs, review metrics, and more. ### Logs Logs view interface You can search and filter logs using the dedicated log search bar. This is a much snappier experience than GitHub’s log search. #### Global log search Global log search interface If you want to see when a particular log line (e.g., an error) first appeared, you can select that log line and search for it globally across your entire CI pipeline. To learn more about how this works, check out our [logs page](/blacksmith-observability/logs). ### Metrics Metrics view interface You can view metrics from the machine running the job. To learn more, check out our [metrics page](/blacksmith-observability/metrics). ## Pricing There is no additional cost for using this feature. For all other pricing, please visit our [pricing page](https://www.blacksmith.sh/pricing). ## FAQ Only job runs on Blacksmith runners are visible in the Run History page. # Logs Source: https://docs.blacksmith.sh/blacksmith-observability/logs Fastest way to search and filter logs across all CI jobs running on Blacksmith runners ## Overview Whether you're triaging a broken build in a pull request or digging into a flaky test that only happens on main, logs are now a much better experience in GitHub Actions. You'll be able to zoom in locally or investigate patterns globally across all your CI runs.